控制台接口¶

为了完全控制终端格式，Rich 提供了一个类。大多数应用程序都需要单个控制台实例，因此您可能希望在模块级别创建一个实例或作为顶级对象的属性。例如，您可以将一个名为“console.py”的文件添加到您的项目中：

from rich.console import Console
console = Console()

然后，您可以从项目中的任何位置导入控制台，如下所示：

from my_project.console import console

控制台对象处理为颜色和样式生成 ANSI 转义序列的机制。它将自动检测终端的功能并在必要时转换颜色。

属性¶

控制台将自动检测渲染时所需的许多属性。

是终端的当前尺寸（如果调整窗口大小，可能会更改）。
是默认编码（通常为“UTF-8”）。
是一个布尔值，指示控制台实例是否正在写入终端。
是包含控制台颜色系统的字符串（见下文）。

色彩系统¶

将颜色写入终端有几个“标准”，并非所有标准都得到普遍支持。Rich 将自动检测相应的颜色系统，或者您可以通过向构造函数提供值来手动设置它。color_system

您可以设置为以下值之一：color_system

None完全禁用颜色。
"auto"将自动检测颜色系统。
"standard"可以显示8种颜色，具有正常和明亮的变化，总共16种颜色。
"256"可以显示“标准”中的 16 种颜色以及 240 种颜色的固定调色板。
"truecolor"可以显示 16 万种颜色，这可能是您的显示器可以显示的所有颜色。
"windows"可以在旧版Windows终端中显示8种颜色。新的Windows终端可以显示“真彩色”。

警告

设置颜色系统时要小心，如果设置的颜色系统高于终端支持的颜色系统，则文本可能无法读取。

印刷¶

要将丰富的内容写入终端，请使用该方法。Rich 将通过其（）方法将任何对象转换为字符串，并执行一些简单的语法突出显示。它还将漂亮地打印任何容器，例如字典和列表。如果打印字符串，它将呈现控制台标记。以下是一些示例：__str__

console.print([1, 2, 3])
console.print("[blue underline]Looks like a link")
console.print(locals())
console.print("FOO", style="white on blue")

您还可以用于呈现支持控制台协议的对象，其中包括 Rich 的内置对象，如、和 – 或其他自定义对象。

伐木¶

该方法提供与打印相同的功能，但添加了一些对调试正在运行的应用程序有用的功能。日志记录将当前时间写入左侧的列，将调用方法的文件和行写入右侧的列。下面是一个示例：

>>> console.log("Hello, World!")

[16:32:08] Hello, World!                                         <stdin>:1

为了帮助调试，log（）方法有一个参数。如果将其设置为，Rich 将显示调用该方法的局部变量表。log_localsTrue

打印 JSON¶

该方法将漂亮地打印（格式和样式）包含 JSON 的字符串。下面是一个简短的示例：

console.print_json('[false, true, null, "foo"]')

您还可以通过记录对象来记录 json：

from rich.json import JSON
console.log(JSON('["foo", "bar"]'))

由于打印 JSON 是一项常见要求，因此可以从主命名空间导入：print_json

from rich import print_json

您还可以通过命令行打印 JSON，如下所示：

python -m rich.json cats.json

低电平输出¶

除了和之外，Rich 还有一种方法可以提供一种较低级别的写入终端的方式。out（）方法将所有位置参数转换为字符串，并且不会漂亮地打印、自动换行或将标记应用于输出，但可以应用基本样式并选择性地进行突出显示。

下面是一个示例：

>>> console.out("Locals", locals())

规则¶

该方法将绘制一条带有可选标题的水平线，这是将终端输出划分为多个部分的好方法。

>>> console.rule("[bold red]Chapter 2")

─────────────────────────────── Chapter 2 ───────────────────────────────

规则方法还接受用于设置线条样式的参数和用于对齐标题的参数（“左”、“居中”或“右”）。stylealign

地位¶

Rich 可以显示带有“微调器”动画的状态消息，该动画不会干扰常规控制台输出。运行以下命令以演示此功能：

python -m rich.status

若要显示状态消息，请使用状态消息（可以是字符串、文本或其他可呈现对象）进行调用。结果是一个上下文管理器，它启动和停止代码块周围的状态显示。下面是一个示例：

with console.status("Working..."):
    do_work()

您可以通过以下参数更改微调器动画：spinner

with console.status("Monkeying around...", spinner="monkey"):
    do_work()

运行以下命令以查看的可用选项：spinner

python -m rich.spinner

对齐/对齐¶

打印和日志都支持一个参数，如果设置该参数必须是“默认”、“左”、“右”、“中心”或“完整”之一。如果为“左”，则任何打印（或记录）的文本将左对齐，如果“右”文本将左对齐到终端的右侧，如果为“居中”，则文本将居中，如果为“完整”，则文本将与终端的左边缘和右边缘对齐（如书籍中的打印文本）。justify

的默认值通常看起来与相同，但存在细微差别。左对齐将使用空格填充文本的右侧，而默认对齐则不会。只有当您使用参数设置背景颜色时，您才会注意到差异。以下示例演示了差异：justify"default""left"style

from rich.console import Console

console = Console(width=20)

style = "bold white on blue"
console.print("Rich", style=style)
console.print("Rich", style=style, justify="left")
console.print("Rich", style=style, justify="center")
console.print("Rich", style=style, justify="right")

这将生成以下输出：

Rich
Rich                
        Rich        
                Rich

溢出¶

溢出是当您打印的文本大于可用空间时发生的情况。如果您打印长“单词”（例如 URL），或者如果面板或表格单元格内有空间有限的文本，则可能会发生溢出。

您可以指定 Rich 应如何处理溢出，参数应为以下字符串之一：“折叠”、“裁剪”、“省略号”或“忽略”。默认值为“折叠”，它将任何多余的字符放在下一行，根据需要创建尽可能多的新行以适合文本。overflow

“crop”方法截断行尾的文本，丢弃任何会溢出的字符。

“省略号”方法类似于“crop”，但会在任何被截断的文本末尾插入省略号字符（“...”）。

以下代码演示了基本的溢出方法：

from typing import List
from rich.console import Console, OverflowMethod

console = Console(width=14)
supercali = "supercalifragilisticexpialidocious"

overflow_methods: List[OverflowMethod] = ["fold", "crop", "ellipsis"]
for overflow in overflow_methods:
    console.rule(overflow)
    console.print(supercali, overflow=overflow, style="bold blue")
    console.print()

这将生成以下输出：

──── fold ────
supercalifragi
listicexpialid
ocious

──── crop ────
supercalifragi

── ellipsis ──
supercalifrag…

您还可以将溢出设置为“忽略”，以允许文本运行到下一行。实际上，这看起来与“裁剪”相同，除非您在调用时也进行了设置。crop=False

控制台样式¶

控制台有一个属性，您可以使用该属性将样式应用于打印的所有内容。默认情况下为 None 表示不应用任何额外样式，但您可以将其设置为任何有效样式。下面是设置了样式属性的控制台示例：stylestyle

from rich.console import Console
blue_console = Console(style="white on blue")
blue_console.print("I'm blue. Da ba dee da ba di.")

软包装¶

富词通过插入换行符将打印的文本换行。您可以通过在调用时设置来禁用此行为。启用软换行后，任何不适合的文本都将运行到以下行，就像内置的 .soft_wrap=Trueprint

种植¶

该方法有一个布尔参数。裁剪的默认值为 True，它告诉 Rich 裁剪任何原本会运行到下一行的内容。您通常不需要考虑裁剪，因为 Rich 会调整内容大小以适应可用宽度。crop

注意

如果使用进行打印，则会自动禁用裁剪。soft_wrap=True

输入¶

控制台类有一个方法，其工作方式与 Python 的内置函数相同，但可以使用 Rich 可以打印的任何内容作为提示。例如，下面是一个带有表情符号的彩色提示：

from rich.console import Console
console = Console()
console.input("What is [i]your[/i] [bold red]name[/]? :smiley: ")

如果之前加载了 Python 的内置模块，将提供详细的行编辑和历史记录功能。

出口¶

控制台类可以将写入它的任何内容导出为文本、svg 或 html。若要启用导出，请首先在构造函数上设置。这会告诉 Rich 保存您或 .下面是一个示例：record=Trueprint()log()

from rich.console import Console
console = Console(record=True)

写入内容后，可以调用，或以字符串形式获取控制台输出。还可以调用、或将内容直接写入磁盘。

有关富控制台生成的 html 输出的示例，请参阅标准颜色。

导出 SVG¶

使用 or 时，SVG 的宽度将与终端窗口的宽度匹配（以字符为单位），而高度将自动缩放以适应控制台输出。

您可以在 Web 浏览器中打开 SVG。您还可以使用标记将其插入到网页中，或者通过将标记复制到 HTML 中。<img>

下图显示了 Rich 导出的 SVG 的示例。

您可以通过从模块导入所需的主题并将其传递给或通过参数传递来自定义 SVG 导出期间使用的主题：rich.terminal_themetheme

from rich.console import Console
from rich.terminal_theme import MONOKAI

console = Console(record=True)
console.save_svg("example.svg", theme=MONOKAI)

或者，您可以通过自己构建实例并将其传入来创建自己的主题。rich.terminal_theme.TerminalTheme

注意

SVG 引用 Fira 代码字体。如果您在页面中嵌入了丰富的 SVG，您可能还需要添加指向 Fira Code CSS 的链接

错误控制台¶

默认情况下，控制台对象将写入（以便您在终端中看到输出）。如果使用 Rich 构造控制台，则会写入。您可能希望使用它来创建错误控制台，以便可以从常规输出中拆分错误消息。下面是一个示例：sys.stdoutstderr=Truesys.stderr

from rich.console import Console
error_console = Console(stderr=True)

您可能还希望在控制台上设置参数，以使错误消息在视觉上有所不同。您可以通过以下方式执行此操作：style

error_console = Console(stderr=True, style="bold red")

文件输出¶

您可以通过在构造函数上设置参数来告诉 Console 对象写入文件 - 构造函数应该是为写入文本而打开的类似文件的对象。您可以使用它写入文件，而不会在终端上显示输出。下面是一个示例：file

import sys
from rich.console import Console
from datetime import datetime

with open("report.txt", "wt") as report_file:
    console = Console(file=report_file)
    console.rule(f"Report Generated {datetime.now().ctime()}")

请注意，在写入文件时，如果不想将输出包装为当前控制台宽度，则可能需要显式设置参数。width

捕获输出¶

在某些情况下，您可能希望从控制台捕获输出，而不是将其直接写入终端。您可以使用返回上下文管理器的方法执行此操作。从此上下文管理器退出时，调用以返回将写入终端的字符串。下面是一个示例：

from rich.console import Console
console = Console()
with console.capture() as capture:
    console.print("[bold red]Hello[/] World")
str_output = capture.get()

捕获输出的另一种方法是将控制台文件设置为 .如果要在单元测试中测试控制台输出，则建议使用此方法。下面是一个示例：

from io import StringIO
from rich.console import Console
console = Console(file=StringIO())
console.print("[bold red]Hello[/] World")
str_output = console.file.getvalue()

寻呼¶

如果你有一些很长的输出要呈现给用户，你可以使用寻呼机来显示它。寻呼机通常是操作系统上的应用程序，它至少支持按键滚动，但通常支持上下滚动文本和其他功能。

您可以通过调用返回上下文管理器来从控制台分页输出。当寻呼机退出时，打印的任何内容都将发送到寻呼机。下面是一个示例：

from rich.__main__ import make_test_card
from rich.console import Console

console = Console()
with console.pager():
    console.print(make_test_card())

由于大多数平台上的默认寻呼机不支持颜色，因此 Rich 将从输出中去除颜色。如果您知道寻呼机支持颜色，则可以在调用该方法时进行设置。styles=True

注意

Rich 将查看然后环境变量（优先）以获取寻呼机命令。在 Linux 和 macOS 上，您可以设置其中之一以启用具有 ANSI 样式的分页。MANPAGERPAGERMANPAGERless -r

备用屏幕¶

警告

此功能目前处于实验阶段。您可能需要等待，然后再在生产中使用它。

终端支持“备用屏幕”模式，该模式与常规终端分开，并允许全屏应用程序保持输入和命令流不变。Rich 通过该方法支持此模式，但建议您使用它返回一个上下文管理器，该管理器在退出时禁用备用模式。

下面是备用屏幕的示例：

from time import sleep
from rich.console import Console

console = Console()
with console.screen():
    console.print(locals())
    sleep(5)

上面的代码将在备用屏幕上显示一个漂亮的打印词典，然后在 5 秒后返回命令提示符。

您还可以提供一个可呈现对象，当您调用时，该可呈现对象将显示在备用屏幕中。update()

下面是一个示例：

from time import sleep

from rich.console import Console
from rich.align import Align
from rich.text import Text
from rich.panel import Panel

console = Console()

with console.screen(style="bold white on red") as screen:
    for count in range(5, 0, -1):
        text = Align.center(
            Text.from_markup(f"[blink]Don't Panic![/blink]\n{count}", justify="center"),
            vertical="middle",
        )
        screen.update(Panel(text))
        sleep(1)

使用可渲染对象更新屏幕允许 Rich 在不滚动的情况下裁剪内容以适应屏幕。

有关使用 Rich 构建全屏界面的更强大方法，请参阅实时显示。

注意

如果您在退出 Python 代码后发现自己陷入了备用模式，请在终端中键入reset