Rich 是一个用于 Python 的命令行终端 UI 库，本条目是一份在编写 Rich 代码时的知识指引，帮助开发者写出正确的 Rich 终端界面代码，涵盖标记语法、样式化输出、表格、进度跟踪、实时显示、日志集成与自定义可渲染对象。
用途与触发条件
当编写从 rich 导入的 Python 代码，或被要求为 Python CLI 添加终端 UI、彩色输出、进度条、表格、语法高亮或美化打印时，应启用本知识。
覆盖范围
- Console 类、标记语法、样式字符串、颜色格式
- 所有可渲染类型（Panel、Table、Tree、Columns、Layout）
- 进度条（track()、Progress）与 Live 显示
- 标准库 logging 的 RichHandler 与 traceback 安装
- Text 类与编程式样式构建
- Syntax、Markdown、Pretty / pprint、JSON
- 自定义对象的 rich_console 和 rich_repr 协议
不覆盖
- Textual（Rich 的同类 TUI 框架，属于独立库）
- Segment 层以下的 Rich 内部实现
- Pygments 主题编写
按任务类型选择参考文件
- 打印样式化输出或标记 → console-and-markup.md
- 构建表格、面板、树、列 → renderables.md
- 进度条或实时更新 → progress-and-live.md
- 语法高亮或美化打印代码/数据 → text-and-syntax.md
- 日志或回溯显示 → logging-and-tracebacks.md
- 自定义可渲染对象、布局或高亮器 → advanced-patterns.md
各参考文件内容摘要
Console 与标记：Console 类的实例化与构造参数，print() / log() / rule() / status() 方法，标记语法（BBCode 风格标签），样式定义字符串，颜色格式（命名 / 256 数字 / hex / rgb），样式属性（bold/italic/underline 等），Style 类，Theme 类，环境变量，输出捕获与导出。适用于编写 console.print()、应用颜色/样式、使用 Rich 标记标签或配置 Console 行为时。
可渲染对象：Panel、Table（add_column、add_row、构造函数选项、列选项）、Tree（add、style、guide_style）、Columns 布局、Padding、Rule、Align 及 Box 样式，包含构造函数签名与关键参数。适用于构建带边框、表格、树视图或多列布局的结构化输出时。
进度与实时：track() 函数，Progress 类（add_task、update、advance），任务管理（visible、indeterminate、transient），全部内置列类（BarColumn、TextColumn、TimeRemainingColumn、SpinnerColumn 等），Live 类，以及 console.status() 加载指示器。适用于为 CLI 添加进度跟踪、加载动画或实时更新输出时。
文本与语法：Text 类（append、stylize、highlight_regex、assemble、from_markup），Syntax 类（from_path、line_numbers、theme、line_range），Markdown 可渲染对象，pprint / Pretty，JSON 可渲染对象，以及 rich_repr 协议与 @rich.repr.auto 装饰器。适用于高亮代码块、渲染 markdown、美化打印数据结构或自定义对象 repr 输出时。
日志与回溯：RichHandler 构造参数（完整表格），通过 extra={} 对每条消息覆盖标记/高亮器，rich_tracebacks=True 显示日志中的异常回溯，tracebacks_suppress 抑制框架栈帧，traceback.install() 安装全局处理器，console.print_exception() 参数及 max_frames 行为。适用于将 Rich 集成到 Python logging 模块、安装全局回溯处理器或改进异常显示时。
高级模式：rich 协议（从对象返回可渲染对象），rich_console 协议（生成器产出可渲染对象或 Segment），rich_measure 自定义宽度上报，Layout 类（split_column、split_row、update、命名窗格），RegexHighlighter 子类化，内置高亮器，inspect() 函数，以及 REPL 安装。适用于编写自定义可渲染对象、构建多窗格全屏布局、实现自定义语法高亮或调试 Python 对象时。
快速参考（代码）
Install
pip install rich
Drop-in print replacement
from rich import print print("[bold red]Hello[/bold red] [green]world[/green]")
Console (preferred for production code)
from rich.console import Console console = Console() console.print("[bold]Hello[/bold]", style="green") console.rule("[bold red]Section")
Style string formats
console.print("text", style="bold red underline on white") console.print("text", style="#af00ff") console.print("text", style="rgb(175,0,255)")
Progress bar — simple
from rich.progress import track for item in track(sequence, description="Processing..."): process(item)
Progress bar — multiple tasks
from rich.progress import Progress with Progress() as progress: task = progress.add_task("[cyan]Working...", total=100) progress.update(task, advance=10)
Logging
import logging from rich.logging import RichHandler logging.basicConfig( level="NOTSET", format="%(message)s", datefmt="[%X]", handlers=[RichHandler()] )
Tracebacks
from rich.traceback import install install(show_locals=True)
Table
from rich.table import Table table = Table("Name", "Value") table.add_row("foo", "bar") console.print(table)
Panel
from rich.panel import Panel console.print(Panel("content", title="Title"))
适用场景
为 Python 命令行程序添加彩色与样式化输出、构建表格与面板、展示树状结构与多列布局、添加进度条与加载动画、高亮显示代码或渲染 Markdown、美化打印数据结构、将 Rich 集成到 logging 与异常回溯显示中，以及编写自定义可渲染对象和全屏多窗格布局。
限制
本知识不覆盖 Textual TUI 框架、Segment 层以下的 Rich 内部实现以及 Pygments 主题编写。关于共享的架构、类型、测试或 CLI 规则，需查阅 ../python3-development/references/python3-standards.md。