PyTermGUI 使用教程

1. 项目介绍

PyTermGUI 是一个 Python 终端用户界面（TUI）框架，支持鼠标操作、模块化小部件系统、可定制的快速终端标记语言等特性。它旨在简化终端应用程序的开发，提供了一种简单、可读且模块化的方式来创建终端应用。

主要特性

• 鼠标支持：无需额外配置即可支持鼠标操作。
• 模块化小部件系统：提供了一系列可定制的小部件。
• 快速终端标记语言：支持使用标记语言快速创建样式化的终端文本。
• YAML 样式引擎：支持使用 YAML 或 Python 进行样式定制。

2. 项目快速启动

安装

首先，使用 pip 安装 PyTermGUI：

pip3 install pytermgui

示例代码

以下是一个简单的示例，展示如何使用 PyTermGUI 创建一个显示当前时间的终端应用：

import time
import pytermgui as ptg

def macro_time(fmt: str) -> str:
    return time.strftime(fmt)

ptg.tim.define("time", macro_time)

with ptg.WindowManager() as manager:
    manager.layout.add_slot("Body")
    manager.add(
        ptg.Window("[bold]The current time is:[/]\n\n[time 75]%c", box="EMPTY")
    )

运行上述代码后，你将在终端中看到当前时间的显示。

3. 应用案例和最佳实践

案例1：联系人表单

以下是一个更复杂的示例，展示如何创建一个联系人表单：

import pytermgui as ptg

CONFIG = """
config:
    InputField:
        styles:
            prompt: dim italic
            cursor: '@72'
    Label:
        styles:
            value: dim bold
    Window:
        styles:
            border: '60'
            corner: '60'
    Container:
        styles:
            border: '96'
            corner: '96'
"""

def submit(manager, window):
    # 处理提交逻辑
    pass

with ptg.YamlLoader() as loader:
    loader.load(CONFIG)

with ptg.WindowManager() as manager:
    window = (
        ptg.Window(
            "",
            ptg.InputField("Balazs", prompt="Name: "),
            ptg.InputField("Some street", prompt="Address: "),
            ptg.InputField("[phone]", prompt="Phone number: "),
            "",
            ptg.Container(
                "Additional notes:",
                ptg.InputField("A whole bunch of\nMeaningful notes\nand stuff", multiline=True),
                box="EMPTY_VERTICAL",
            ),
            "",
            ["Submit", lambda *_: submit(manager, window)],
            width=60,
            box="DOUBLE",
        )
        .set_title("[210 bold]New contact")
        .center()
    )
    manager.add(window)

最佳实践

• 使用 YAML 配置：通过 YAML 文件配置样式，使代码更简洁且易于维护。
• 模块化设计：将不同的功能模块化，便于扩展和维护。
• 充分利用标记语言：使用 PyTermGUI 提供的标记语言快速创建样式化的文本。

4. 典型生态项目

Shade

Shade 是 PyTermGUI 的一个替代项目，提供了更完整的功能和更好的性能。如果你需要更高级的终端应用开发，可以考虑使用 Shade。

Termage

Termage 是一个用于生成终端截图的工具，支持 SVG 和 HTML 格式。它与 PyTermGUI 结合使用，可以方便地生成终端应用的截图。

其他相关项目

• Rich：一个用于在终端中显示富文本的 Python 库。
• Textual：一个用于创建复杂终端用户界面的 Python 库。

通过结合这些生态项目，你可以更高效地开发复杂的终端应用。