Textual `keyline` 样式详解：在容器内绘制子控件分隔线

前端UI组件异步编程【免费下载链接】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点击查看免费下载keyline是 Textual 提供给容器的专用样式规则它可以在容器的每个子控件周围绘制线条形成控件之间的分隔线。与border不同的是keyline 绘制在控件边框之外、落在margin区域里且允许线条相互交叉重叠从而自然地在布局中切出分隔线。读完本文你将掌握keyline的语法、四种线条类型、颜色与透明度写法以及它在水平布局与网格布局中的真实用法并能理解其底层渲染原理。什么是 Keyline按 docs/styles/keyline.md 的定义keyline样式应用于容器用于围绕容器内的子控件绘制线条。Keyline 与 border 表面相似但本质不同border绘制在控件自身内部边缘keyline绘制在控件边框之外落在该控件的 margin外边距区域不同于border多个 keyline 可以相互重叠、交叉形成控件与控件之间的分隔线。由于 keyline 绘制在 margin 区域因此必须配合 margin 或 grid-gutter 才能看到效果——没有留白线条就没有绘制空间。从源码上看这一特性在控件渲染时会主动触发在 src/textual/widget.py 中当self.styles.layout存在且self.styles.keyline[0] ! none时控件会调用self.layout.render_keyline(self)来渲染 keyline 层。语法keyline: [keyline] [color];其中keyline取值由 docs/css_types/keyline.md 定义共四种值描述none无线条禁用 keyline。thin细线。heavy粗线。double双线。这些合法值在源码中有明确定义见 src/textual/css/constants.pyVALID_KEYLINE: Final {none, thin, heavy, double}与 两个参数均可省略且允许附加一个表示透明度的百分比标量详见下文底层解析一节。示例一水平布局中的细 Keyline下面是一个简单的水平布局示例容器使用thin细 keyline keyline_horizontal.pypython from textual.app import App, ComposeResult from textual.containers import Horizontal from textual.widgets import Placeholder class KeylineApp(App): CSS_PATH keyline_horizontal.tcss def compose(self) - ComposeResult: with Horizontal(): yield Placeholder() yield Placeholder() yield Placeholder() if __name__ __main__: app KeylineApp() app.run() keyline_horizontal.tcsscss Placeholder { margin: 1; width: 1fr; } Horizontal { keyline: thin $secondary; } 关键点每个Placeholder设置了margin: 1为 keyline 留出绘制空间容器Horizontal声明keyline: thin $secondary;使用主题色变量$secondary作为线条颜色三个子控件等宽width: 1fr排列keyline 在两两相邻处绘制出分隔线。完整示例文件见 docs/examples/styles/keyline_horizontal.py 与 docs/examples/styles/keyline_horizontal.tcss。示例二网格布局中的重 Keyline下面是一个网格布局示例使用heavy粗 keyline并展示了 keyline 在跨行跨列控件上的表现 keyline.pypython from textual.app import App, ComposeResult from textual.containers import Grid from textual.widgets import Placeholder class KeylineApp(App): CSS_PATH keyline.tcss def compose(self) - ComposeResult: with Grid(): yield Placeholder(idfoo) yield Placeholder(idbar) yield Placeholder() yield Placeholder(classeshidden) yield Placeholder(idbaz) if __name__ __main__: KeylineApp().run() keyline.tcsscss Grid { grid-size: 3 3; grid-gutter: 1; padding: 2 3; keyline: heavy green; } Placeholder { height: 1fr; } .hidden { visibility: hidden; } #foo { column-span: 2; } #bar { row-span: 2; } #baz { column-span: 3; } 关键点Grid声明grid-gutter: 1为 keyline 提供槽位gutter空间keyline: heavy green;使用粗线 绿色#foo跨 2 列、#bar跨 2 行、#baz跨整行3 列keyline 会沿着这些跨行跨列控件的实际矩形轮廓绘制形成划分网格单元格的分隔线注意名为hiddenvisibility: hidden的 Placeholderkeyline 渲染时会跳过不可见控件详见下文实现原理。完整示例文件见 docs/examples/styles/keyline.py 与 docs/examples/styles/keyline.tcss。CSS 用法keyline必须设置在容器上即拥有布局的控件例如/* 设置一条细的绿色 keyline */ /* 注意必须设置在容器或带有布局的控件上 */ keyline: thin green;可选的透明度写法keyline: thin green 50%;Python 用法在 Python 中可以通过widget.styles.keyline以线条类型 颜色的元组赋值widget.styles.keyline (thin, green)从 src/textual/css/_style_properties.py 的实现来看该属性读取时返回(none, TRANSPARENT)作为默认值写入时支持元组(str, Color)或NoneNone会清除该规则并回退到 CSS 定义Descriptor for getting and setting keyline information. def __get__(...): return obj.get_rule(keyline, (none, TRANSPARENT)) def __set__(self, obj, keyline: tuple[str, Color] | None): if keyline is None: ... else: obj.set_rule(keyline, keyline)底层实现原理CSS 解析keyline的 CSS 值由 src/textual/css/_styles_builder.py 中的process_keyline解析。其解析规则如下默认值线条类型为none颜色为Color.parse(green)绿色透明度keyline_alpha 1.0遇到颜色 token如green、$secondary、#ff0000解析为Color遇到普通 token先尝试按颜色解析失败则作为线条类型并校验其是否在VALID_KEYLINE集合中非法值会触发报错遇到百分比标量如50%作为透明度通道——注意必须以百分比给出否则报错alpha must be given as a percentage最终以(keyline_style, keyline_color.multiply_alpha(keyline_alpha))元组写入样式规则。对应的错误提示文案定义在 src/textual/css/_help_text.py会明确提示该属性期望 2 个值并列出合法线条类型。渲染keyline 的实际绘制位于 src/textual/layout.py 的render_keyline方法读取容器尺寸创建Canvas画布从container.styles.keyline取出(line_style, keyline_color)并将颜色与容器背景色叠加container.background_colors[0] keyline_color保证线条与背景混合自然遍历容器可见子控件widget.visible对每个子控件的 region 构造一个向外扩张 1 格的Rectangleoffset - (1, 1)、width 2、height 2即把线条绘制在控件 margin 区域所有矩形作为图元一次性渲染到画布上返回。由于每个子控件都会向外扩张绘制矩形相邻控件之间的线条自然重叠交叉这正是 keyline 能形成分隔线的机制而visibility: hidden的子控件会被跳过不会绘制其轮廓。与 border 的区别再梳理维度borderkeyline绘制位置控件内部边缘控件边框之外margin / gutter 区域是否可交叉否围绕单个控件是多控件线条重叠形成分隔线前置条件无需额外留白需配合margin或grid-gutter才可见适用对象任意控件容器有布局的控件补充说明单独使用keyline而不设置margin/grid-gutter时线条没有绘制空间视觉上不会有任何效果这是新手最常踩的坑颜色写法与 Textual 全局一致支持十六进制、命名颜色、$theme变量及透明度百分比更多与 keyline 搭配的网格属性grid-gutter、grid-size、column-span、row-span等可参考 docs/styles/grid/index.md若需要围绕控件绘制传统边框请参考 border。赞分享前端UI组件异步编程【免费下载链接】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 align 样式详解在终端应用中控制子组件的对齐方式Textual align 样式详解在终端应用中控制子组件的对齐方式 align 是 Textual 中用于定义 容器如何摆放其子组件 的样式规则。通过一行前端UI组件异步编程Textual layers 样式详解用有序图层精确控制组件绘制层级Textual layers 样式详解用有序图层精确控制组件绘制层级 layers 是 Textual 终端应用框架中用于控制组件绘制顺序的 CSS 样式它前端UI组件异步编程Textual 中 text-align 样式详解在控件内对齐文本的完整指南Textual 中 text align 样式详解在控件内对齐文本的完整指南 text align 是 Textual 中用于设置控件widget内文本水前端UI组件异步编程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考