Textual Rule 控件完全指南用hr式的分隔线组织终端界面布局【免费下载链接】textualThe lean application framework for Python. Build sophisticated user interfaces with a simple Python API. Run your apps in the terminal and a web browser.项目地址: https://gitcode.com/gh_mirrors/te/textual本文围绕 Textual 框架内置的Rule控件展开讲解如何用它像 HTML 的hr标签一样在终端界面中分隔内容区块覆盖水平/垂直两种方向的全部线型、Reactive 属性、构造器与类方法、CSS 布局定制以及参数校验与源码实现细节。读完本文你将能够在自己的 Textual 应用中熟练插入、定制和动态切换各种风格的分隔线。Rule 是什么Rule是 Textual 提供的一个分隔类separator控件功能与 HTML 中的hr水平线标签类似用来在视觉上把界面中的不同内容区块分隔开增强布局的层次感与可读性。在 Textual 官方 API 文档docs/widgets/rule.md中Rule 的定位被明确描述为 A rule widget to separate content, similar to ahrHTML tag。Rule 的两个关键特性不可聚焦Focusable否Rule 不参与键盘焦点管理用户无法通过 Tab 键聚焦到它非容器Container否Rule 不能挂载子控件它只是一个纯渲染的装饰性控件。这两个特性使其非常轻量它不发送任何消息Messages、没有绑定按键Bindings、也没有组件类Component Classes职责单一纯粹。快速上手在应用里放置一条分隔线最简单的用法是在compose()中直接yield Rule()然后app.run()启动from textual.app import App, ComposeResult from textual.widgets import Label, Rule class MyApp(App): def compose(self) - ComposeResult: yield Label(上半部分内容) yield Rule() yield Label(下半部分内容) if __name__ __main__: MyApp().run()默认情况下Rule()渲染为一条水平实线line_stylesolid并使用主题的$secondary颜色见下文 DEFAULT_CSS 源码这通常能很好地融入 Textual 自带的主题体系。水平 Rule默认方向与全部线型Rule 的默认方向orientation是horizontal水平。水平方向下Rule 会沿容器宽度方向延伸成一条横线。仓库中的官方示例 docs/examples/widgets/horizontal_rules.py 一次性展示了所有可用的水平线型配合标签标注每种线型的名称from textual.app import App, ComposeResult from textual.containers import Vertical from textual.widgets import Label, Rule class HorizontalRulesApp(App): CSS_PATH horizontal_rules.tcss def compose(self) - ComposeResult: with Vertical(): yield Label(solid (default)) yield Rule() yield Label(heavy) yield Rule(line_styleheavy) yield Label(thick) yield Rule(line_stylethick) yield Label(dashed) yield Rule(line_styledashed) yield Label(double) yield Rule(line_styledouble) yield Label(ascii) yield Rule(line_styleascii) if __name__ __main__: app HorizontalRulesApp() app.run()配套的样式文件 docs/examples/widgets/horizontal_rules.tcss 负责让示例居中并约束布局Screen { align: center middle; } Vertical { height: auto; width: 80%; } Label { width: 100%; text-align: center; }从示例可以看到构造时只需通过line_style参数即可切换线型。line_style一共支持 9 种取值ascii、blank、dashed、double、heavy、hidden、none、solid、thick。其中solid是默认值blank、hidden、none三种在视觉上等效于空白常用于隐藏分隔线但保留布局占位ascii使用纯 ASCII 字符-适合对字符集有严格限制的环境。垂直 Rule侧边栏与列布局的分隔将orientation设为verticalRule 就会变成一条竖线用于在左右分栏布局如侧边栏、双列内容中分隔列。仓库示例 docs/examples/widgets/vertical_rules.py 展示了所有垂直线型from textual.app import App, ComposeResult from textual.containers import Horizontal from textual.widgets import Label, Rule class VerticalRulesApp(App): CSS_PATH vertical_rules.tcss def compose(self) - ComposeResult: with Horizontal(): yield Label(solid) yield Rule(orientationvertical) yield Label(heavy) yield Rule(orientationvertical, line_styleheavy) yield Label(thick) yield Rule(orientationvertical, line_stylethick) yield Label(dashed) yield Rule(orientationvertical, line_styledashed) yield Label(double) yield Rule(orientationvertical, line_styledouble) yield Label(ascii) yield Rule(orientationvertical, line_styleascii) if __name__ __main__: app VerticalRulesApp() app.run()配套样式 docs/examples/widgets/vertical_rules.tcss 中Horizontal容器设定为固定高度比例、标签限定宽度并垂直居中文本从而让竖线与标签在垂直方向完整伸展Screen { align: center middle; } Horizontal { width: auto; height: 80%; } Label { width: 6; height: 100%; text-align: center; }要点垂直 Rule 需要所在的容器有确定的可用高度它才会伸展填满。若容器高度是auto竖线可能没有足够的长度可渲染。Reactive 属性orientation 与 line_styleRule 只有两个 Reactive 属性官方文档的属性表如下docs/widgets/rule.md名称类型默认值描述orientationRuleOrientationhorizontal规则的方向横/竖。line_styleLineStylesolid规则的线型。在源码 src/textual/widgets/_rule.py 中两者的类型别名与 reactive 定义如下RuleOrientation Literal[horizontal, vertical] LineStyle Literal[ ascii, blank, dashed, double, heavy, hidden, none, solid, thick, ] class Rule(Widget, can_focusFalse): orientation: Reactive[RuleOrientation] reactiveRuleOrientation line_style: Reactive[LineStyle] reactiveLineStyle因为二者是 Reactive 属性你可以在运行时直接赋值控件会自动重绘rule Rule() # ... 挂载到界面后运行时动态切换 rule.orientation vertical rule.line_style doublewatch_orientation回调会在方向变化时同步切换控件的 CSS 类-horizontal与-vertical见 src/textual/widgets/_rule.py这两个类正是 DEFAULT_CSS 中不同布局规则的选择器。源码解读Rule 是如何渲染的阅读 src/textual/widgets/_rule.py 可以清楚看到 Rule 的实现细节。1. 线型到字符的映射表每种线型在水平与垂直方向对应不同的 Unicode 制表符_HORIZONTAL_LINE_CHARS { ascii: -, blank: , dashed: ╍, double: ═, heavy: ━, hidden: , none: , solid: ─, thick: █, } _VERTICAL_LINE_CHARS { ascii: |, blank: , dashed: ╏, double: ║, heavy: ┃, hidden: , none: , solid: │, thick: █, }可以推断视觉风格差异正源于这些字符的选择heavy用粗线字符━/┃thick直接用实心块█double用双线字符═/║dashed用间断字符╍/╏ascii则退化为-/|。2. render() 的分发逻辑Rule.render()根据orientation选择字符表并构造对应的可渲染对象def render(self) - RenderResult: if self.orientation vertical: return VerticalRuleRenderable(_VERTICAL_LINE_CHARS[self.line_style], style, self.content_size.height) elif self.orientation horizontal: return HorizontalRuleRenderable(_HORIZONTAL_LINE_CHARS[self.line_style], style, self.content_size.width) else: raise InvalidRuleOrientation(...)HorizontalRuleRenderable将单个字符重复width次拼成一行Segment(self.width * self.character, self.style)VerticalRuleRenderable将单字符段与换行段交替重复height次形成纵向延伸的竖线。线条颜色来自self.rich_style而 rich_style 由 CSS 决定默认取主题色$secondary见 DEFAULT_CSS。3. 内容尺寸的确定Rule 重写了get_content_width与get_content_heightdef get_content_width(self, container, viewport): return container.width if self.orientation horizontal else 1 def get_content_height(self, container, viewport, width): return 1 if self.orientation horizontal else container.height即水平方向占满容器宽度高度固定 1 行垂直方向占满容器高度宽度固定 1 列。这与 DEFAULT_CSS 中的布局规则相互印证Rule { color: $secondary; } Rule.-horizontal { height: 1; margin: 1 0; width: 1fr; } Rule.-vertical { width: 1; margin: 0 2; height: 1fr; }可以看到水平 Rule 上下各留 1 行外边距、宽度为1fr垂直 Rule 左右各留 2 列外边距、高度为1fr。expand True在__init__中设置确保它在分配布局空间时尽量伸展。构造器参数与便捷类方法Rule.__init__的完整签名见 src/textual/widgets/_rule.pyRule( orientation: RuleOrientation horizontal, line_style: LineStyle solid, *, name: str | None None, id: str | None None, classes: str | None None, disabled: bool False, )除两个核心参数外其余参数与所有 Textual 控件一致DOM id、CSS 类、禁用状态等。同时 Rule 提供两个语义化的类方法构造器Rule.horizontal(line_stylesolid, ...)等价于Rule(orientationhorizontal, line_style...)Rule.vertical(line_stylesolid, ...)等价于Rule(orientationvertical, line_style...)。例如yield Rule.vertical(line_styleheavy)在快照测试应用 tests/snapshot_tests/snapshot_apps/rules.py 中就同时使用了位置参数形式Rule(vertical, line_style...)与关键字形式来创建竖线with Vertical(): for rule_style in RULE_STYLES: yield Rule(line_stylerule_style) with Horizontal(): for rule_style in RULE_STYLES: yield Rule(vertical, line_stylerule_style)参数校验无效值会抛出异常Textual 对 Rule 的两个核心参数做了严格校验源码中定义了两种异常InvalidRuleOrientation方向非法时抛出InvalidLineStyle线型非法时抛出。校验逻辑由 reactive 的validate_orientation与validate_line_style钩子实现非法值会被直接拒绝def validate_orientation(self, orientation): if orientation not in _VALID_RULE_ORIENTATIONS: raise InvalidRuleOrientation(fValid rule orientations are {friendly_list(_VALID_RULE_ORIENTATIONS)}) return orientation def validate_line_style(self, style): if style not in _VALID_LINE_STYLES: raise InvalidLineStyle(fValid rule line styles are {friendly_list(_VALID_LINE_STYLES)}) return style注意校验是在赋值时触发的因此无论在构造时还是运行时给orientation/line_style赋非法值都会立刻抛异常。测试文件 tests/test_rule.py 完整覆盖了这四种失败场景async def test_invalid_rule_orientation(): with pytest.raises(InvalidRuleOrientation): Rule(orientationinvalid orientation!) async def test_invalid_rule_line_style(): with pytest.raises(InvalidLineStyle): Rule(line_styleinvalid line style!) async def test_invalid_reactive_rule_orientation_change(): rule Rule() with pytest.raises(InvalidRuleOrientation): rule.orientation invalid orientation! async def test_invalid_reactive_rule_line_style_change(): rule Rule() with pytest.raises(InvalidLineStyle): rule.line_style invalid line style!这两个异常类与类型别名LineStyle、RuleOrientation均从 src/textual/widgets/rule.py 导出可以直接导入使用from textual.widgets.rule import InvalidLineStyle, InvalidRuleOrientation, LineStyle, RuleOrientation用 CSS 定制 Rule 的外观除了线型Rule 作为普通 Widget 同样支持 Textual 的 CSS 体系。常用的定制手段包括颜色color属性决定线条颜色例如Rule { color: $accent; }外边距与尺寸水平 Rule 可通过margin、width调整横线的位置与长短垂直 Rule 可通过height控制伸展范围组合选择器利用方向类Rule.-horizontal/Rule.-vertical分别定制横竖两种形态。例如将某条 Rule 变为较宽幅的强调色横线Rule.emphasis { color: $warning; margin: 1 0; }消息、绑定与组件类官方文档明确说明 Rule 的这三项均为空Messages消息不发送任何消息Bindings按键绑定无绑定Component Classes组件类无组件类。因此在实现自定义行为时你不需要为 Rule 处理任何消息或按键事件它的角色是纯装饰性的。测试与验证仓库通过快照测试保证 Rule 渲染的视觉回归相关用例位于 tests/snapshot_tests/test_snapshots.pytest_rule_horizontal_rules基于docs/examples/widgets/horizontal_rules.py生成快照test_rule_horizontal_rules.svgtest_rule_vertical_rules基于docs/examples/widgets/vertical_rules.py生成快照test_rule_vertical_rules.svgtest_rules基于 tests/snapshot_tests/snapshot_apps/rules.py 一次性渲染 9 种线型 × 横竖两方向test_rules.svg。此外 tests/test_rule.py 覆盖了非法方向与非法线型在构造与运行时赋值两种场景下的异常行为。若要在自己的应用中验证 Rule 行为也可以在测试中使用 Textual 的 Pilot 驱动应用后断言控件属性与渲染结果。小结Rule 是 Textual 中一个轻量、专注的分隔控件默认水平实线通过orientation与line_style两个 Reactive 属性即可在横/竖两个方向、9 种线型间自由切换并支持运行时动态修改作为纯装饰控件它无消息、无绑定、无组件类配合 CSS 的color、margin、width/height等规则可以灵活融入各种布局。无论是表单分区、侧边栏分隔还是日志区块划分Rule都能以最少代码提供清晰的结构化视觉反馈。【免费下载链接】textualThe lean application framework for Python. Build sophisticated user interfaces with a simple Python API. Run your apps in the terminal and a web browser.项目地址: https://gitcode.com/gh_mirrors/te/textual创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考