Textual 样式指南offset 属性详解——布局之后微调控件位置的偏移机制【免费下载链接】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/textualoffset是 Textual 框架中用于微调控件widget位置的 CSS 样式属性控件先由其父容器的布局算法确定最终位置随后offset再在此基础上叠加一个水平/垂直方向上的位移量。本指南完整讲解offset、offset-x、offset-y的语法、scalar取值类型、CSS 与 Python 两种设置方式并结合框架源码说明其底层实现帮助你在不需要改动整体布局的前提下精确调整单个控件的呈现位置。offset 是什么布局完成之后的相对偏移在 Textual 的布局体系中控件的位置由父容器的布局算法如 horizontal、vertical、grid 等决定。而offset定义的是一个相对偏移量它会在控件位置由父布局确定之后再被叠加到该位置上见 布局指南 Offsets 一节。这意味着如果一个控件从未通过 CSS 或 Python 修改过offset它的偏移量默认为(0, 0)即不发生任何位移offset不会影响其他控件的布局位置也不会触发父容器的重新布局计算——它只改变当前控件自身的渲染位置。从源码实现看offset的变更走的是布局刷新路径在 src/textual/css/_style_properties.py 的OffsetProperty.__set__中设置成功后调用obj.refresh(layoutTrue, repaintFalse)通知框架重新计算布局并把新的偏移应用到渲染上。语法offset 与单轴变体offset的完整语法如下定义见 docs/styles/offset.mdoffset: scalar scalar; offset-x: scalar; offset-y: scalar;两个scalar分别定义控件的**水平x 轴和垂直y 轴**偏移量。如果只想设置单个轴可以使用offset-x和offset-y两个子属性。坐标方向语义offset的两个值遵循屏幕坐标系方向见 布局指南第一个值x 轴正值向右移动控件负值向左移动第二个值y 轴正值向下移动控件负值向上移动。这与部分 CSS 传统习惯y 轴向下为负不同在 Textual 的终端坐标系中 y 轴向下为正方向使用时需注意。取值类型offset的两个分量都是scalar类型即一个数字加一个单位或特殊值auto。它支持以下单位单位符号名称示例说明无单元格10固定数量的终端单元格行/列是唯一绝对单位浮点会被截断为整数fr比例1fr相对其他控件按比例分配空间%百分比75%相对容器控件的大小w宽度25w相对容器宽度的百分比h高度75h相对容器高度的百分比vw视口宽度25vw相对视口宽度的百分比视口宽度 终端宽度减去左右停靠控件宽度vh视口高度75vh相对视口高度的百分比视口高度 终端高度减去上下停靠控件高度auto自动auto尝试计算恰好容纳内容且无需滚动的最优尺寸需要注意的是offset的分量通常以单元格为单位使用例如offset: 8 2表示水平移动 8 列、垂直移动 2 行但既然分量是scalar类型也允许使用百分比、w/h甚至vw/vh等相对单位来表达偏移量。完整示例三个不同偏移量的控件官方文档提供了一个直观的示例源码见 docs/examples/styles/offset.py 与 docs/examples/styles/offset.tcss。应用由三个 Label 组成屏幕采用 horizontal 布局from textual.app import App from textual.widgets import Label class OffsetApp(App): CSS_PATH offset.tcss def compose(self): yield Label(Paul (offset 8 2), classespaul) yield Label(Duncan (offset 4 10), classesduncan) yield Label(Chani (offset 0 -3), classeschani) if __name__ __main__: app OffsetApp() app.run()对应的样式表Screen { background: white; color: black; layout: horizontal; } Label { width: 20; height: 10; content-align: center middle; } .paul { offset: 8 2; /* 向右 8 格向下 2 格 */ background: red 20%; border: outer red; color: red; } .duncan { offset: 4 10; /* 向右 4 格向下 10 格 */ background: green 20%; border: outer green; color: green; } .chani { offset: 0 -3; /* 不水平移动向上 3 格 */ background: blue 20%; border: outer blue; color: blue; }运行python docs/examples/styles/offset.py可以看到三个 Label 首先按 horizontal 布局依次排开随后分别按各自offset指定的方向被推离原本的位置——chani的offset: 0 -3尤其能体现负值向上移动的效果。由于offset只作用于自身即便三个控件发生位移重叠也不会改变其他控件的布局位置。在 CSS 中使用 offset在 Textual CSS 中直接声明即可支持单行双值形式和单轴子属性/* 将控件沿 x 方向移动 8 格、沿 y 方向移动 2 格 */ offset: 8 2; /* 仅沿 x 方向移动 4 格 */ offset-x: 4; /* 仅沿 y 方向移动 -3 格即向上 3 格 */ offset-y: -3;offset-x与offset-y是独立的单轴变体二者可与完整的offset同时出现CSS 优先级由选择器具体性决定。当只想调整一个方向而保持另一方向不变时用单轴变体最简洁。在 Python 中编程设置 offset在 Python 中通过widget.styles.offset设置需要同时给出 x 与 y 两个值——offset没有对应的 Python 单轴 API无法单独修改某一个轴# 将控件沿 x 方向移动 2 格、沿 y 方向移动 4 格 widget.styles.offset (2, 4)从源码实现看Python 端赋值由OffsetProperty.__set__src/textual/css/_style_properties.py处理它接受三种输入None清除当前偏移规则恢复默认的(0, 0)ScalarOffset对象直接作为规则值设置(x, y)二元组x、y 既可以是int也可以是str——字符串形式支持任意合法scalar单位。因此Python 端也可以使用带单位的字符串例如# 使用视口相对单位表达偏移量 widget.styles.offset (0.5vw, 0.5vh)如果传入的字符串无法解析为合法的Scalar例如使用了不存在的单位会抛出StyleValueError其内部由ScalarParseError触发并附带对应的帮助提示文本。底层原理offset 是如何被应用的offset的实现可以拆解为三个层次均能在当前仓库源码中得到印证样式层offset的值在内部被表示为ScalarOffset——一个包含x、y两个Scalar的具名元组src/textual/css/scalar.py。ScalarOffset.null()返回(0, 0)的空偏移from_offset((x, y))则把整数元组转换为以单元格为单位的 Scalar 对x 使用宽度方向、y 使用高度方向。源码注释明确指出它是两个标量组成的偏移量可用于在两个 Scalar 之间做动画——这也是offset能够参与 Textual 动画系统的基础。排列层真正把offset落到控件位置上的逻辑位于 src/textual/_arrange.py。在对停靠dock控件进行排布时框架读取styles.offset并调用resolve(size, viewport)把两个Scalar解析为具体的单元格像素偏移若控件未显式设置offset规则则使用NULL_OFFSET。最终该偏移作为_WidgetPlacement的offset字段传入叠加到布局计算得到的区域dock_region之上。查询/设置层读取时OffsetProperty.__get__通过obj.get_rule(self.name, NULL_SCALAR)返回规则值未设置时默认得到空偏移这正是文档所述未修改过 offset 的控件偏移为(0, 0)的实现依据。典型使用场景与注意事项微调而非重排当布局整体令人满意、只有个别控件需要轻微位移如弹出提示、徽标角标、标题栏装饰时offset比引入新的容器或修改布局参数更轻量。允许控件重叠由于offset不参与布局计算位移后的控件可以覆盖在相邻控件之上可用于实现叠加效果。负值合法x、y 均为带符号值负偏移可将控件移出容器的显示范围之外此时内容可能被裁剪或滚动取决于overflow等其他样式。默认值未设置时偏移恒为(0, 0)且offset: 8 2中两个分量都遵循scalar的取值规则浮点单元格值会被截断为整数。参见布局指南Offsetsoffset 在整体布局体系中的位置与坐标方向详解。scalar类型参考offset 分量的完整单位表与解析规则。Textual 样式参考总览其他定位、尺寸相关样式如position、margin、dock与 offset 的配合使用。【免费下载链接】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），仅供参考 Textual 样式指南：offset 属性详解——布局之后微调控件位置的偏移机制
Textual 样式指南offset 属性详解——布局之后微调控件位置的偏移机制【免费下载链接】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/textualoffset是 Textual 框架中用于微调控件widget位置的 CSS 样式属性控件先由其父容器的布局算法确定最终位置随后offset再在此基础上叠加一个水平/垂直方向上的位移量。本指南完整讲解offset、offset-x、offset-y的语法、scalar取值类型、CSS 与 Python 两种设置方式并结合框架源码说明其底层实现帮助你在不需要改动整体布局的前提下精确调整单个控件的呈现位置。offset 是什么布局完成之后的相对偏移在 Textual 的布局体系中控件的位置由父容器的布局算法如 horizontal、vertical、grid 等决定。而offset定义的是一个相对偏移量它会在控件位置由父布局确定之后再被叠加到该位置上见 布局指南 Offsets 一节。这意味着如果一个控件从未通过 CSS 或 Python 修改过offset它的偏移量默认为(0, 0)即不发生任何位移offset不会影响其他控件的布局位置也不会触发父容器的重新布局计算——它只改变当前控件自身的渲染位置。从源码实现看offset的变更走的是布局刷新路径在 src/textual/css/_style_properties.py 的OffsetProperty.__set__中设置成功后调用obj.refresh(layoutTrue, repaintFalse)通知框架重新计算布局并把新的偏移应用到渲染上。语法offset 与单轴变体offset的完整语法如下定义见 docs/styles/offset.mdoffset: scalar scalar; offset-x: scalar; offset-y: scalar;两个scalar分别定义控件的**水平x 轴和垂直y 轴**偏移量。如果只想设置单个轴可以使用offset-x和offset-y两个子属性。坐标方向语义offset的两个值遵循屏幕坐标系方向见 布局指南第一个值x 轴正值向右移动控件负值向左移动第二个值y 轴正值向下移动控件负值向上移动。这与部分 CSS 传统习惯y 轴向下为负不同在 Textual 的终端坐标系中 y 轴向下为正方向使用时需注意。取值类型offset的两个分量都是scalar类型即一个数字加一个单位或特殊值auto。它支持以下单位单位符号名称示例说明无单元格10固定数量的终端单元格行/列是唯一绝对单位浮点会被截断为整数fr比例1fr相对其他控件按比例分配空间%百分比75%相对容器控件的大小w宽度25w相对容器宽度的百分比h高度75h相对容器高度的百分比vw视口宽度25vw相对视口宽度的百分比视口宽度 终端宽度减去左右停靠控件宽度vh视口高度75vh相对视口高度的百分比视口高度 终端高度减去上下停靠控件高度auto自动auto尝试计算恰好容纳内容且无需滚动的最优尺寸需要注意的是offset的分量通常以单元格为单位使用例如offset: 8 2表示水平移动 8 列、垂直移动 2 行但既然分量是scalar类型也允许使用百分比、w/h甚至vw/vh等相对单位来表达偏移量。完整示例三个不同偏移量的控件官方文档提供了一个直观的示例源码见 docs/examples/styles/offset.py 与 docs/examples/styles/offset.tcss。应用由三个 Label 组成屏幕采用 horizontal 布局from textual.app import App from textual.widgets import Label class OffsetApp(App): CSS_PATH offset.tcss def compose(self): yield Label(Paul (offset 8 2), classespaul) yield Label(Duncan (offset 4 10), classesduncan) yield Label(Chani (offset 0 -3), classeschani) if __name__ __main__: app OffsetApp() app.run()对应的样式表Screen { background: white; color: black; layout: horizontal; } Label { width: 20; height: 10; content-align: center middle; } .paul { offset: 8 2; /* 向右 8 格向下 2 格 */ background: red 20%; border: outer red; color: red; } .duncan { offset: 4 10; /* 向右 4 格向下 10 格 */ background: green 20%; border: outer green; color: green; } .chani { offset: 0 -3; /* 不水平移动向上 3 格 */ background: blue 20%; border: outer blue; color: blue; }运行python docs/examples/styles/offset.py可以看到三个 Label 首先按 horizontal 布局依次排开随后分别按各自offset指定的方向被推离原本的位置——chani的offset: 0 -3尤其能体现负值向上移动的效果。由于offset只作用于自身即便三个控件发生位移重叠也不会改变其他控件的布局位置。在 CSS 中使用 offset在 Textual CSS 中直接声明即可支持单行双值形式和单轴子属性/* 将控件沿 x 方向移动 8 格、沿 y 方向移动 2 格 */ offset: 8 2; /* 仅沿 x 方向移动 4 格 */ offset-x: 4; /* 仅沿 y 方向移动 -3 格即向上 3 格 */ offset-y: -3;offset-x与offset-y是独立的单轴变体二者可与完整的offset同时出现CSS 优先级由选择器具体性决定。当只想调整一个方向而保持另一方向不变时用单轴变体最简洁。在 Python 中编程设置 offset在 Python 中通过widget.styles.offset设置需要同时给出 x 与 y 两个值——offset没有对应的 Python 单轴 API无法单独修改某一个轴# 将控件沿 x 方向移动 2 格、沿 y 方向移动 4 格 widget.styles.offset (2, 4)从源码实现看Python 端赋值由OffsetProperty.__set__src/textual/css/_style_properties.py处理它接受三种输入None清除当前偏移规则恢复默认的(0, 0)ScalarOffset对象直接作为规则值设置(x, y)二元组x、y 既可以是int也可以是str——字符串形式支持任意合法scalar单位。因此Python 端也可以使用带单位的字符串例如# 使用视口相对单位表达偏移量 widget.styles.offset (0.5vw, 0.5vh)如果传入的字符串无法解析为合法的Scalar例如使用了不存在的单位会抛出StyleValueError其内部由ScalarParseError触发并附带对应的帮助提示文本。底层原理offset 是如何被应用的offset的实现可以拆解为三个层次均能在当前仓库源码中得到印证样式层offset的值在内部被表示为ScalarOffset——一个包含x、y两个Scalar的具名元组src/textual/css/scalar.py。ScalarOffset.null()返回(0, 0)的空偏移from_offset((x, y))则把整数元组转换为以单元格为单位的 Scalar 对x 使用宽度方向、y 使用高度方向。源码注释明确指出它是两个标量组成的偏移量可用于在两个 Scalar 之间做动画——这也是offset能够参与 Textual 动画系统的基础。排列层真正把offset落到控件位置上的逻辑位于 src/textual/_arrange.py。在对停靠dock控件进行排布时框架读取styles.offset并调用resolve(size, viewport)把两个Scalar解析为具体的单元格像素偏移若控件未显式设置offset规则则使用NULL_OFFSET。最终该偏移作为_WidgetPlacement的offset字段传入叠加到布局计算得到的区域dock_region之上。查询/设置层读取时OffsetProperty.__get__通过obj.get_rule(self.name, NULL_SCALAR)返回规则值未设置时默认得到空偏移这正是文档所述未修改过 offset 的控件偏移为(0, 0)的实现依据。典型使用场景与注意事项微调而非重排当布局整体令人满意、只有个别控件需要轻微位移如弹出提示、徽标角标、标题栏装饰时offset比引入新的容器或修改布局参数更轻量。允许控件重叠由于offset不参与布局计算位移后的控件可以覆盖在相邻控件之上可用于实现叠加效果。负值合法x、y 均为带符号值负偏移可将控件移出容器的显示范围之外此时内容可能被裁剪或滚动取决于overflow等其他样式。默认值未设置时偏移恒为(0, 0)且offset: 8 2中两个分量都遵循scalar的取值规则浮点单元格值会被截断为整数。参见布局指南Offsetsoffset 在整体布局体系中的位置与坐标方向详解。scalar类型参考offset 分量的完整单位表与解析规则。Textual 样式参考总览其他定位、尺寸相关样式如position、margin、dock与 offset 的配合使用。【免费下载链接】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），仅供参考