textual-tui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Use this skill when the task is fundamentally about building or changing a Textual app, not merely printing Rich output or writing a non-interactive CLI.

当任务核心是构建或修改Textual应用，而非仅打印Rich输出或编写非交互式CLI时，可使用本技能。

Start by classifying the app

首先对应用进行分类

Pick the closest shape before writing code:

Single-screen shell
One main view with panels, tables, forms, or logs. Prefer containers plus built-in widgets.
Multi-screen workflow
Large context changes, separate flows, or drill-down views. Prefer
```
Screen
```
/
```
ModalScreen
```
.
Multi-mode admin app
Persistent top-level areas such as “dashboard / jobs / settings / logs”. Prefer named
```
MODES
```
, screen stacks, and command palette support.
Data explorer
Records plus details, filters, or side panes. Prefer
```
DataTable
```
, details panel, responsive breakpoints, and keyboard navigation.
Document or filesystem tool
Prefer
```
DirectoryTree
```
,
```
MarkdownViewer
```
,
```
TextArea
```
,
```
Tree
```
, and delivery APIs for export/download.
Chat / streaming / long-running task UI
Prefer a scrollable transcript or log plus
```
@work
```
/ workers for background operations.

If the user has not chosen an architecture, choose one and proceed.

在编写代码前，选择最贴合的应用架构：

单屏幕控制台
包含面板、表格、表单或日志的单一主视图。优先使用容器及内置组件。
多屏幕工作流
涉及较大上下文切换、独立流程或钻取式视图的场景。优先使用
```
Screen
```
/
```
ModalScreen
```
。
多模式管理应用
包含“仪表板/任务/设置/日志”等持久化顶级区域的应用。优先使用命名
```
MODES
```
、屏幕栈和命令面板支持。
数据浏览器
包含记录详情、筛选器或侧边面板的应用。优先使用
```
DataTable
```
、详情面板、响应式断点和键盘导航。
文档或文件系统工具
优先使用
```
DirectoryTree
```
、
```
MarkdownViewer
```
、
```
TextArea
```
、
```
Tree
```
，以及用于导出/下载的交付API。
聊天/流处理/长任务UI
优先使用可滚动的记录或日志，搭配
```
@work
```
/ 工作线程处理后台操作。

若用户未指定架构，请自行选择合适的架构后开展工作。

Default engineering stance

默认工程准则

Prefer built-in widgets first. Only hand-roll behaviour when a built-in widget clearly does not fit.
Keep the App
thin. Move screen-specific logic into
```
Screen
```
classes and reusable composite widgets.
Prefer .tcss
files over inline
```
CSS
```
once styling grows beyond a toy example.
Use IDs and semantic classes deliberately so styling and Pilot tests stay stable.
Design for narrow terminals first, then add split panes and breakpoint-driven layouts.
Leave behind tests whenever behaviour changes.

优先使用内置组件。仅当内置组件完全不适用时，才自定义实现功能。
保持**
```
App
```
轻量化**。将屏幕专属逻辑迁移至
```
Screen
```
类和可复用的复合组件中。
当样式复杂度超出示例级别时，优先使用
.tcss
文件而非内联
```
CSS
```
。
谨慎使用ID和语义类，确保样式和Pilot测试的稳定性。
先适配窄终端，再添加拆分面板和基于断点的布局。
只要功能发生变更，就同步更新测试用例。

Choose the right Textual primitive

选择合适的Textual基础组件

Use Screen
when navigation changes the user’s working context.
Use ModalScreen
for short interruptions: confirmations, pickers, destructive actions.
Use ContentSwitcher
for wizard steps or one-screen subflows.
Use named
MODES
when the app has durable top-level areas with separate navigation stacks.
Use command palette providers when there are many actions, bindings, or discoverability matters.
Use workers for network, subprocess, parsing, search, sleeps, or anything that may block input.

See:

Architecture decision tree
Screens, modes, and command palette

当导航会改变用户工作上下文时，使用**
```
Screen
```
**。
用于短暂中断场景（确认、选择、破坏性操作）时，使用**
```
ModalScreen
```
**。
用于向导步骤或单屏幕子流程时，使用**
```
ContentSwitcher
```
**。
当应用包含独立导航栈的持久化顶级区域时，使用命名
MODES
。
当存在大量操作、绑定或需要考虑可发现性时，使用命令面板提供者。
处理网络、子进程、解析、搜索、休眠或任何可能阻塞输入的操作时，使用工作线程。

参考：

架构决策树
屏幕、模式与命令面板

Widget-first selection rules

组件优先选择规则

Before inventing custom widgets, check the widget atlas.

Common defaults:

```
DataTable
```
for record-heavy views
```
DirectoryTree
```
for filesystem navigation
```
MarkdownViewer
```
for rich document views
```
TextArea
```
for editing
```
TabbedContent
```
for grouped settings or alternate panes
```
Log
```
/
```
RichLog
```
for live output

SelectionList

OptionList

ListView

Tree

Select

Switch

Input

Button

for most interaction needs

在自定义组件前，请查看组件图谱。

常见默认选择：

记录密集型视图使用
```
DataTable
```
文件系统导航使用
```
DirectoryTree
```
富文档视图使用
```
MarkdownViewer
```
编辑功能使用
```
TextArea
```
分组设置或替代面板使用
```
TabbedContent
```
实时输出使用
```
Log
```
/
```
RichLog
```

大多数交互场景使用

SelectionList

、

OptionList

、

ListView

、

Tree

、

Select

、

Switch

、

Input

、

Button

Reactivity and workers

响应式与工作线程

Use the playbook in reactivity and workers.

Core rules:

Put fast derived state in
```
compute_*
```
, but keep it cheap and side-effect free.
Use
```
watch_*
```
for UI reactions, not blocking work.
Use
```
var
```
when you want state without automatic refresh machinery.
Use
```
set_reactive
```
before mount when initial state changes should not trip watchers early.
Move blocking work into
```
@work
```
or
```
run_worker(...)
```
.
Use
```
exclusive=True
```
for stale-search cancellation and similar “latest request wins” flows.
For thread workers, update the UI via messages or
```
call_from_thread
```
.

请遵循响应式与工作线程中的指南。

核心规则：

将快速派生状态放入
```
compute_*
```
，但需确保其轻量化且无副作用。
使用
```
watch_*
```
处理UI响应，而非阻塞型工作。
当需要无需自动刷新机制的状态时，使用
```
var
```
。
若初始状态变更不应提前触发监听器，请在挂载前使用
```
set_reactive
```
。
将阻塞型工作移至
```
@work
```
或
```
run_worker(...)
```
中执行。
对于过时搜索取消等“最新请求优先”的流程，使用
```
exclusive=True
```
。
线程工作线程需通过消息或
```
call_from_thread
```
更新UI。

Browser, dev loop, and delivery

浏览器、开发循环与交付

Textual may run in a terminal or be served to a browser. Build with both in mind when relevant.

Use
```
textual run --dev
```
while iterating.
Use
```
textual console
```
and devtools when behaviour is unclear.
Use
```
textual serve
```
when browser parity matters.
Prefer
```
deliver_text
```
,
```
deliver_binary
```
, or
```
deliver_screenshot
```
for browser-friendly exports and downloads.
Use
```
open_url
```
when handing off to the user’s browser is appropriate.

See:

Browser and delivery guide
Packaging and CI

Textual可在终端运行，也可部署至浏览器。相关场景下请兼顾两种运行方式。

迭代开发时使用
```
textual run --dev
```
。
行为不明确时使用
```
textual console
```
和开发工具。
需保证浏览器兼容性时使用
```
textual serve
```
。
浏览器友好的导出和下载优先使用
```
deliver_text
```
、
```
deliver_binary
```
或
```
deliver_screenshot
```
。
适合移交至用户浏览器处理的场景使用
```
open_url
```
。

参考：

浏览器与交付指南
打包与CI

Testing is part of the feature

测试是功能的一部分

Default output after any non-trivial change:

one smoke test with
```
run_test()
```
one behaviour test for the changed flow
one narrow-terminal or alternate-size test when layout matters
one snapshot test when the view structure matters visually

See testing matrix.

任何非微小变更完成后，默认输出以下测试：

一个使用
```
run_test()
```
的冒烟测试
一个针对变更流程的行为测试
涉及布局时，一个窄终端或替代尺寸测试
视图结构对视觉有影响时，一个快照测试

参考测试矩阵。

When working on an existing project

处理现有项目时

Start with the scripts, then refine by hand:

python scripts/inspect_textual_project.py <project>

python scripts/audit_textual_project.py <project>

Generate scaffolds or tests only after you understand the existing structure.

Use the audit to catch:

oversized
```
App
```
classes
blocking handlers
missing breakpoints
missed built-in widget opportunities
missing command palette or delivery APIs
missing Pilot tests

先运行脚本，再手动优化：

python scripts/inspect_textual_project.py <project>

python scripts/audit_textual_project.py <project>

仅在理解现有结构后，再生成脚手架或测试用例。

通过审计排查以下问题：

过大的
```
App
```
类
阻塞型处理器
缺失响应式断点
未充分利用内置组件
缺失命令面板或交付API
缺失Pilot测试

Bundled scripts

内置脚本

```
scripts/scaffold_textual_app.py
```
Generate starter apps, TCSS, tests, optional
```
pyproject.toml
```
, and CI workflow.
```
scripts/inspect_textual_project.py
```
Inventory app classes, screens, widgets, bindings, IDs, workers, and styling.
```
scripts/audit_textual_project.py
```
Heuristic architecture/performance/test audit for an existing Textual project.
```
scripts/generate_pilot_tests.py
```
Emit starter smoke and behaviour tests for an existing app.
```
scripts/dump_dom_and_bindings.py
```
If Textual is installed, launch an app under
```
run_test()
```
and dump DOM and active bindings.

scripts/emit_textual_pyproject.py

Generate a packageable Hatch-based

pyproject.toml

```
scripts/emit_github_actions_ci.py
```
Generate a GitHub Actions workflow for Textual tests.

scripts/build_upstream_pattern_atlas.py

Summarise a local Textual repo snapshot into

references/repo-map.md

and

references/upstream-pattern-atlas.md

```
scripts/self_check.py
```
Compile scripts and scaffold all bundled templates as a package validation step.

```
scripts/scaffold_textual_app.py
```
生成初始应用、TCSS、测试、可选的
```
pyproject.toml
```
和CI工作流。
```
scripts/inspect_textual_project.py
```
盘点应用类、屏幕、组件、绑定、ID、工作线程和样式。
```
scripts/audit_textual_project.py
```
对现有Textual项目进行启发式架构/性能/测试审计。
```
scripts/generate_pilot_tests.py
```
为现有应用生成初始冒烟测试和行为测试。
```
scripts/dump_dom_and_bindings.py
```
若已安装Textual，在
```
run_test()
```
下启动应用并导出DOM和活跃绑定。

scripts/emit_textual_pyproject.py

生成基于Hatch的可打包

pyproject.toml

。

```
scripts/emit_github_actions_ci.py
```
生成用于Textual测试的GitHub Actions工作流。

scripts/build_upstream_pattern_atlas.py

将本地Textual仓库快照汇总至

references/repo-map.md

和

references/upstream-pattern-atlas.md

。

```
scripts/self_check.py
```
编译脚本并搭建所有内置模板，作为包验证步骤。

Bundled starter templates

内置初始模板

Available scaffolds:

```
dashboard
```
```
form
```
```
chat
```
```
data-explorer
```
```
file-browser
```
```
settings
```
```
wizard
```
```
log-monitor
```
```
editor
```
```
admin-modes
```
```
download-demo
```

List them with:

bash

python scripts/scaffold_textual_app.py --list-templates

Generate one with:

bash

python scripts/scaffold_textual_app.py \
  --template data-explorer \
  --module my_app \
  --class-name MyApp \
  --app-title "My App" \
  --output-dir .

可用脚手架模板：

```
dashboard
```
```
form
```
```
chat
```
```
data-explorer
```
```
file-browser
```
```
settings
```
```
wizard
```
```
log-monitor
```
```
editor
```
```
admin-modes
```
```
download-demo
```

使用以下命令列出模板：

bash

python scripts/scaffold_textual_app.py --list-templates

使用以下命令生成模板：

bash

python scripts/scaffold_textual_app.py \
  --template data-explorer \
  --module my_app \
  --class-name MyApp \
  --app-title "My App" \
  --output-dir .

Output checklist

输出检查清单

Before you finish, aim to leave behind:

a clear app structure
stable IDs/classes for styling and tests
TCSS separated from Python unless the app is tiny
background work off the main event path
keyboard-discoverable actions
responsive layout decisions
at least a smoke test and one behaviour test
notes on how to run the app in dev mode

完成工作前，确保留下以下内容：

清晰的应用结构
用于样式和测试的稳定ID/类
除微型应用外，TCSS与Python代码分离
后台工作脱离主事件流
可通过键盘发现的操作
响应式布局决策
至少一个冒烟测试和一个行为测试
关于如何在开发模式下运行应用的说明

按需阅读以下内容

Architecture decision tree
Widget selection atlas
Reactivity and workers
Screens, modes, and command palette
Browser and delivery
Testing matrix
Anti-patterns
Packaging and CI
Repository map
Upstream pattern atlas

架构决策树
组件选择图谱
响应式与工作线程
屏幕、模式与命令面板
浏览器与交付
测试矩阵
反模式
打包与CI
仓库图谱
上游模式图谱

textual-tui

Original

Translation

Start by classifying the app

首先对应用进行分类

Default engineering stance

默认工程准则

Choose the right Textual primitive

选择合适的Textual基础组件

Widget-first selection rules

组件优先选择规则

Reactivity and workers

响应式与工作线程

Browser, dev loop, and delivery

浏览器、开发循环与交付

Testing is part of the feature

测试是功能的一部分

When working on an existing project

处理现有项目时

Bundled scripts

内置脚本

Bundled starter templates

内置初始模板

Output checklist

输出检查清单

Read next as needed

按需阅读以下内容