textual-builder

Textual 构建器

概述

此技能可帮助你使用 Textual 构建复杂的文本用户界面（TUI）。Textual 是一个 Python 框架，可通过现代、受 Web 启发的 API 创建基于终端和浏览器的应用程序。它包含参考文档、卡牌游戏模板，以及 Textual 开发最佳实践。

快速入门

基本 Textual 应用

from textual.app import App, ComposeResult
from textual.widgets import Header, Footer, Label

class MyApp(App):
    def compose(self) -> ComposeResult:
        yield Header()
        yield Label("Hello, Textual!")
        yield Footer()

if __name__ == "__main__":
    app = MyApp()
    app.run()

卡牌游戏模板

要快速构建卡牌游戏原型，请复制模板：

cp -r assets/card-game-template/* ./my-game/
cd my-game
python app.py

模板包含：

• 具有正面朝上和朝下状态的交互式卡牌组件
• 用于容纳玩家手牌的容器
• 带回合管理的游戏区域
• 用于选择和打出卡牌的按键绑定
• 可自定义的样式

自定义指南请参见 assets/card-game-template/README.md。

何时阅读参考文档

此技能包含全面的参考文件。请根据任务加载相应文件：

references/basics.md

阅读时机： 设置应用结构、使用响应式属性、处理挂载、查询组件，或处理消息和事件时。

涵盖内容：

• 应用结构和 compose 方法
• 响应式属性和观察器
• 挂载和动态创建组件
• 组件查询
• 消息、事件和自定义消息

references/widgets.md

阅读时机： 添加按钮、输入框、标签、数据表等 UI 元素，或创建自定义组件时。

涵盖内容：

• 显示组件（Label、Static、Placeholder）
• 输入组件（Button、Input、TextArea、Switch）
• 用于表格数据的 DataTable
• 布局容器（Container、Grid、Horizontal、Vertical）
• 自定义组件创建
• Header/Footer

references/layout.md

阅读时机： 设计布局、定位组件、使用网格系统，或处理响应式尺寸时。

涵盖内容：

• 布局类型（垂直、水平、网格）
• 网格配置（单元格跨列、行／列尺寸）
• 对齐和内容定位
• 将组件停靠在屏幕边缘
• 尺寸（固定、相对、分数、自动）
• 间距（margin、padding）
• 滚动

references/styling.md

阅读时机： 应用 CSS 样式、设置主题、添加边框，或自定义组件外观时。

涵盖内容：

• CSS 文件和选择器
• 颜色（命名颜色、十六进制、RGB、主题变量）
• 边框和边框样式
• 文本样式和对齐
• 不透明度和着色
• 用于设置文本样式的 Rich 标记
• 伪类（:hover、:focus 等）

references/interactivity.md

阅读时机： 实现键盘快捷键、处理鼠标事件、响应用户操作，或创建交互行为时。

涵盖内容：

• 按键绑定和操作
• 动态更新绑定
• 鼠标事件（单击、悬停、进入、离开）
• 键盘事件
• 焦点管理
• 组件专属消息
• 自定义消息
• 通知和计时器

常见工作流

创建新的 TUI 应用

1. 从基本应用结构开始（参见“快速入门”）
2. 设计布局（阅读 references/layout.md）
3. 添加组件（阅读 references/widgets.md）
4. 使用 CSS 设置样式（阅读 references/styling.md）
5. 添加交互功能（阅读 references/interactivity.md）

构建卡牌游戏原型

1. 复制卡牌游戏模板
2. 根据游戏的卡牌属性自定义 Card 组件
3. 在 action 方法中修改游戏逻辑
4. 在消息处理器中添加游戏专属规则
5. 在 app.tcss 中设置卡牌和布局的样式

添加交互功能

1. 在 BINDINGS 中定义按键绑定
2. 实现 action 方法（action_*）
3. 处理组件消息（on_button_pressed 等）
4. 使用响应式属性管理状态
5. 在观察器中更新 UI

最佳实践

• 渐进式开发：从简单开始，逐步增加复杂度
• 响应式状态：对影响 UI 的状态使用 reactive()
• CSS 分离：将样式放在 .tcss 文件中，而不是内联编写
• 组件复用：为重复使用的组件创建自定义组件
• 消息冒泡：使用 event.stop() 控制消息传播
• 类型提示：使用恰当的类型提示，以获得更好的 IDE 支持
• ID 和类：使用语义化的 ID/类进行查询和样式设置

安装

pip install textual
# or
uv pip install textual

当前版本：v0.86.0+（截至 2025 年 11 月，最新版本为 v6.6.0）

资源

references/

按需加载的完整文档：

• basics.md - 核心概念和应用结构
• widgets.md - 组件目录和用法
• layout.md - 布局系统和定位
• styling.md - CSS 和主题设置
• interactivity.md - 事件、绑定和操作

assets/

• card-game-template/ - 完整的卡牌游戏入门模板，包含交互式卡牌、手牌和回合管理

官方文档

对于此技能未涵盖的主题，请参阅：

• https://textual.textualize.io/（官方文档）
• https://github.com/Textualize/textual（GitHub 仓库）