textual-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Textual Builder

Textual 构建工具

Overview

概述

This skill helps you build sophisticated Text User Interfaces (TUIs) using Textual, a Python framework for creating terminal and browser-based applications with a modern web-inspired API. It includes reference documentation, a card game template, and best practices for Textual development.

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

Quick Start

快速开始

Basic Textual App

基础Textual应用

python

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()

python

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()

Card Game Template

卡牌游戏模板

For card game prototyping, copy the template:

bash

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

The template includes:

Interactive Card widget with face-up/down states
Hand containers for player cards
Play area with turn management
Key bindings for card selection and playing
Customizable styling

See

assets/card-game-template/README.md

for customization guide.

如需进行卡牌游戏原型开发，请复制以下模板：

bash

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

该模板包含：

支持正面/翻面状态的交互式Card组件
玩家卡牌的手牌容器
包含回合管理的游戏区域
卡牌选择与出牌的按键绑定
可自定义样式

自定义指南请查看

assets/card-game-template/README.md

。

When to Read Reference Documentation

何时查阅参考文档

This skill includes comprehensive reference files. Load them based on your task:

本技能包含全面的参考文件，请根据你的任务加载对应文档：

references/basics.md

Read when: Setting up app structure, using reactive attributes, handling mounting, querying widgets, or working with messages/events.

Covers:

App structure and compose method
Reactive attributes and watchers
Mounting and dynamic widget creation
Widget querying
Messages, events, and custom messages

查阅时机： 设置应用结构、使用reactive属性、处理组件挂载、查询组件或处理消息/事件时。

涵盖内容：

应用结构与compose方法
Reactive属性与监听器
组件挂载与动态组件创建
组件查询
消息、事件与自定义消息

references/widgets.md

Read when: Adding UI elements like buttons, inputs, labels, data tables, or creating custom widgets.

Covers:

Display widgets (Label, Static, Placeholder)
Input widgets (Button, Input, TextArea, Switch)
DataTable for tabular data
Layout containers (Container, Grid, Horizontal, Vertical)
Custom widget creation
Header/Footer

查阅时机： 添加UI元素（如按钮、输入框、标签、数据表格）或创建自定义组件时。

涵盖内容：

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

references/layout.md

Read when: Designing layouts, positioning widgets, using grid systems, or handling responsive sizing.

Covers:

Layout types (vertical, horizontal, grid)
Grid configuration (cell spanning, row/column sizing)
Alignment and content positioning
Docking widgets to screen edges
Sizing (fixed, relative, fractional, auto)
Spacing (margin, padding)
Scrolling

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

涵盖内容：

布局类型（垂直、水平、网格）
网格配置（单元格跨区、行/列尺寸）
对齐与内容定位
组件停靠至屏幕边缘
尺寸设置（固定、相对、比例、自动）
间距（外边距、内边距）
滚动

references/styling.md

Read when: Applying CSS styles, theming, adding borders, or customizing widget appearance.

Covers:

CSS files and selectors
Colors (named, hex, RGB, theme variables)
Borders and border styling
Text styling and alignment
Opacity and tinting
Rich markup for styled text
Pseudo-classes (:hover, :focus, etc.)

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

涵盖内容：

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

references/interactivity.md

Read when: Implementing keyboard shortcuts, handling mouse events, responding to user actions, or creating interactive behaviors.

Covers:

Key bindings and actions
Dynamic binding updates
Mouse events (click, hover, enter, leave)
Keyboard events
Focus management
Widget-specific messages
Custom messages
Notifications and timers

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

涵盖内容：

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

Common Workflows

常见工作流

Creating a New TUI App

创建新的TUI应用

Start with basic app structure (see Quick Start)
Design layout (read
```
references/layout.md
```
)
Add widgets (read
```
references/widgets.md
```
)
Style with CSS (read
```
references/styling.md
```
)
Add interactivity (read
```
references/interactivity.md
```
)

从基础应用结构开始（见快速开始）
设计布局（查阅
```
references/layout.md
```
）
添加组件（查阅
```
references/widgets.md
```
）
使用CSS设置样式（查阅
```
references/styling.md
```
）
添加交互功能（查阅
```
references/interactivity.md
```
）

Prototyping a Card Game

原型化卡牌游戏

Copy the card game template
Customize the Card widget for your game's card properties
Modify game logic in action methods
Add game-specific rules in message handlers
Style cards and layout in
```
app.tcss
```

复制卡牌游戏模板
针对游戏的卡牌属性自定义Card组件
在动作方法中修改游戏逻辑
在消息处理器中添加游戏专属规则
在
```
app.tcss
```
中设置卡牌与布局的样式

Adding Interactive Features

添加交互功能

Define key bindings in
```
BINDINGS
```
Implement action methods (
```
action_*
```
)
Handle widget messages (
```
on_button_pressed
```
, etc.)
Use reactive attributes for state management
Update UI in watchers

在
```
BINDINGS
```
中定义按键绑定
实现动作方法（
```
action_*
```
）
处理组件消息（
```
on_button_pressed
```
等）
使用reactive属性进行状态管理
在监听器中更新UI

Best Practices

最佳实践

Progressive Development: Start simple, add complexity incrementally
Reactive State: Use
```
reactive()
```
for state that affects UI
CSS Separation: Keep styling in
```
.tcss
```
files, not inline
Widget Reuse: Create custom widgets for repeated components
Message Bubbling: Use
```
event.stop()
```
to control message propagation
Type Hints: Use proper type hints for better IDE support
IDs and Classes: Use semantic IDs/classes for querying and styling

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

Installation

安装

bash

pip install textual

bash

pip install textual

or

uv pip install textual


Current version: v0.86.0+ (as of November 2025, latest is v6.6.0)

uv pip install textual


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

Resources

资源

references/

Comprehensive documentation loaded on-demand:

```
basics.md
```
- Core concepts and app structure
```
widgets.md
```
- Widget catalog and usage
```
layout.md
```
- Layout systems and positioning
```
styling.md
```
- CSS and theming
```
interactivity.md
```
- Events, bindings, and actions

按需加载的全面文档：

```
basics.md
```
- 核心概念与应用结构
```
widgets.md
```
- 组件目录与使用方法
```
layout.md
```
- 布局系统与定位
```
styling.md
```
- CSS与主题
```
interactivity.md
```
- 事件、绑定与动作

assets/

```
card-game-template/
```
- Complete starter template for card games with interactive cards, hands, and turn management

```
card-game-template/
```
- 完整的卡牌游戏启动模板，包含交互式卡牌、手牌与回合管理

Official Documentation

官方文档

For topics not covered in this skill, consult:

https://textual.textualize.io/ (official docs)
https://github.com/Textualize/textual (GitHub repo)

对于本技能未涵盖的主题，请查阅：