Python之rich-tui包语法、参数和实际应用案例

Python rich-tui 完整使用文档

一、rich-tui 基础概述

1. 包定位与核心功能

rich-tui 基于知名文本美化库 rich 二次封装，专门用于快速构建终端交互式TUI（文本用户界面），简化终端弹窗、表单、表格、布局、菜单、日志、进度条、分栏面板等交互组件开发，无需手动处理终端ANSI转义、光标、换行、色彩兼容。
核心能力分类：

2. 底层依赖

• rich >= 13.0.0：核心渲染引擎
• textual（可选）：高级交互式TUI完整应用（rich-tui弹窗组件复用其逻辑）
• pygments：代码语法高亮
• wcwidth：中英文字符宽度自适应排版

二、安装方式

1. 标准pip安装

# 基础完整版（含全部交互组件）
pip install rich-tui

# 国内镜像加速
pip install rich-tui -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 可选扩展安装

# 带完整交互式窗口、文件选择、图形组件
pip install rich-tui[full]

# 开发版（最新未发布代码）
pip install git+https://github.com/xxx/rich-tui.git

3. 卸载/升级

# 升级
pip install –upgrade rich-tui
# 卸载
pip uninstall rich-tui -y

三、核心语法、通用参数与API

3.1 基础导入模板

# 全局主对象（统一终端渲染入口）
from rich_tui import Console
# 各类组件
from rich_tui.components import (
Panel, Table, Progress, Select, InputBox, ConfirmPopup, Tree, Columns
)
# 样式常量
from rich_tui.style import Color, Align, BorderStyle
# 弹窗工具
from rich_tui.popups import alert, prompt, select_popup

3.2 核心类：Console（全局终端控制器）

构造函数参数

Console(
width: int | None = None, # 强制终端宽度，None自动适配窗口
height: int | None = None, # 强制高度
color_system: str = "auto", # 色彩模式：auto/truecolor/256/standard
force_terminal: bool = False, # 非终端环境也强制输出ANSI色彩
record: bool = False, # 是否记录输出，支持导出HTML
soft_wrap: bool = True, # 文本自动换行
stderr: bool = False, # 输出至stderr
tab_size: int = 4 # Tab空格宽度
)

常用方法

3.3 通用全局样式参数（所有组件通用）

所有可视化组件（Panel/Table/Columns等）共享以下参数：

3.4 交互输入组件通用参数（Select/InputBox）

四、8个完整可运行实战案例

案例1：基础彩色美化打印 + Emoji文本输出

功能：普通文字上色、渐变文本、代码块高亮

from rich_tui import Console
from rich_tui.style import Color

console = Console()

# 1. 基础彩色文字
console.print("[red]错误信息[/red]：文件读取失败")
console.print("[green bold]成功[/green bold]：数据同步完成")
console.print(f"[{Color.BLUE}]蓝色普通文字[/]")

# 2. 渐变文字
console.print("[gradient(red,yellow)]渐变标题文本[/gradient]", justify="center")

# 3. Python代码语法高亮
code = """
def hello():
print("Hello rich-tui")
"""
console.print(code, style="syntax.python")

console.pause()

案例2：卡片Panel分栏布局展示数据

功能：多卡片并排布局，展示多组业务信息

from rich_tui import Console
from rich_tui.components import Panel, Columns

console = Console()

# 三张卡片
panel1 = Panel("CPU使用率：78%", title="硬件监控", border_style="green")
panel2 = Panel("内存占用：6.2G/16G", title="内存信息", border_style="blue")
panel3 = Panel("磁盘剩余：120G", title="硬盘状态", border_style="yellow")

# 分栏并排输出
cols = Columns([panel1, panel2, panel3], equal_width=True)
console.print(cols)

案例3：交互式弹窗输入（单行文本+密码输入）

功能：弹出输入框获取用户账号密码

from rich_tui.popups import prompt

# 普通文本输入
username = prompt(label="请输入用户名", default="admin")
# 密码隐藏输入
password = prompt(label="请输入密码", password=True)

print(f"账号：{username}，密码长度：{len(password)}")

案例4：单选/多选下拉菜单弹窗

功能：菜单选择操作类型，返回选中值

from rich_tui.popups import select_popup

# 单选
op = select_popup(
label="请选择操作",
options=["新增数据", "修改数据", "删除数据", "导出报表"]
)
print("你选择：", op)

# 多选
multi_op = select_popup(
label="批量选择功能（空格多选）",
options=["备份", "压缩", "上传", "清理缓存"],
multi=True
)
print("选中项：", multi_op)

案例5：结构化数据表格渲染（业务报表）

功能：终端生成带色彩、对齐的二维表格，支持行高亮

from rich_tui import Console
from rich_tui.components import Table

console = Console()

# 创建表格
table = Table(title="员工薪资表", border_style="cyan")
# 添加表头
table.add_column("工号", justify="center")
table.add_column("姓名")
table.add_column("部门")
table.add_column("薪资", style="green")

# 填充数据
table.add_row("001", "张三", "技术部", "15000")
table.add_row("002", "李四", "运营部", "9500")
table.add_row("003", "王五", "财务部", "12000")

console.print(table)

案例6：循环任务进度条（批量文件处理）

功能：多任务并行进度条，带进度百分比、剩余时间

from rich_tui import Console
from rich_tui.components import Progress
import time

console = Console()

# 模拟批量处理文件
with Progress() as progress:
task1 = progress.add_task("[red]处理图片…", total=100)
task2 = progress.add_task("[green]导出文档…", total=80)

while not progress.finished:
progress.update(task1, advance=1)
progress.update(task2, advance=0.8)
time.sleep(0.05)

console.print("[bold green]全部任务执行完成！[/bold green]")

案例7：树形结构展示目录/层级数据

功能：树形组件展示文件目录、组织架构

from rich_tui import Console
from rich_tui.components import Tree

console = Console()
tree = Tree("项目根目录", border_style="gold")

# 一级节点
src = tree.add("src/ 源代码")
static = tree.add("static/ 静态资源")

# 子节点
src.add("main.py")
src.add("utils/")
src.add("config.yaml")
static.add("img/")
static.add("css/")

console.print(tree)

案例8：确认弹窗+日志系统完整工具脚本

功能：弹窗二次确认、分级日志打印、错误提示弹窗

from rich_tui import Console
from rich_tui.popups import alert, confirm

console = Console()

# 分级日志
console.log("程序启动成功", level="info")
console.log("加载配置文件config.json", level="debug")
console.log("检测到低磁盘空间", level="warning")

# 警告弹窗
alert("警告：磁盘剩余空间不足5G", style="red")

# 确认弹窗
is_del = confirm("确认删除所有临时文件？此操作不可恢复！")
if is_del:
console.log("已执行清理", level="success")
else:
console.log("用户取消操作", level="info")

五、常见错误、报错原因与解决方案

1. ModuleNotFoundError: No module named ‘rich_tui’

• 原因：未安装包、安装包名写错、虚拟环境不匹配
• 解决：

pip install rich-tui
# 检查当前环境已安装包
pip list | findstr rich

2. 颜色不显示，只有纯文本无ANSI色彩

• 原因1：Windows cmd默认不支持真彩色；使用PyCharm普通输出面板
• 原因2：Console初始化color_system="standard"限制色彩
• 解决：

# 开启自动真彩色、强制终端色彩
console = Console(color_system="auto", force_terminal=True)
# Windows推荐使用Windows Terminal / PowerShell

3. 弹窗Select/InputBox无交互，直接跳过无输入

• 原因：代码使用IDE内置输出窗口，不支持终端键盘交互；脚本重定向输出到文件
• 解决：在原生终端（cmd/终端/PowerShell）直接运行python xxx.py，不要IDE运行

4. 表格/Panel排版错乱、文字溢出换行异常

• 原因：未设置expand=False，终端窗口过小；中文字符宽度计算错误
• 修复参数：

Table(expand=False, width=80)
Panel(..., width=90, soft_wrap=True)

5. Progress进度条卡顿、更新延迟

• 原因：循环内无sleep，短时间高频刷新终端IO阻塞
• 优化：降低advance刷新频率，增加微小延时

6. 报错 AttributeError: ‘Console’ object has no attribute ‘popup’

• 原因：新旧版本API变更，弹窗不在Console内置，需单独导入popups模块
• 正确导入：

from rich_tui.popups import alert, prompt, select_popup

7. 多选菜单返回空列表，无法选中

• 原因：忘记设置multi=True，默认单选模式；键盘操作不熟悉（空格勾选、回车确认）
• 修复：添加multi=True参数

8. 导出HTML空白，无色彩样式

• 原因：创建Console时未开启record=True记录输出

console = Console(record=True)
# 所有打印完成后导出
console.export_html("output.html")

六、使用注意事项与最佳实践

1. 环境兼容

2. 性能优化

3. 交互规范

4. 样式规范

5. 打包发布注意

使用pyinstaller打包脚本时，需显式包含依赖：

pyinstaller –collect-data rich-tui main.py

否则打包后运行报组件缺失。

6. 编码问题

Windows终端默认gbk编码，出现中文乱码时，启动脚本前设置：

import sys
sys.stdout.reconfigure(encoding="utf-8")

《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。