Textual 高度样式指南：深入理解 `height` 属性与 `＜scalar＞` 单位体系-北京尧图网络

Textual 高度样式指南深入理解height属性与scalar单位体系【免费下载链接】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/textualheight是 Textual 中控制组件Widget垂直尺寸的核心样式属性它建立在scalar单位体系之上支持固定单元格、百分比、比例fr、相对视口vw/vh等多种取值方式。本文以 docs/styles/height.md 为主干结合 src/textual/css/scalar.py 等源码完整讲解height的语法、每种单位的计算规则、CSS 与 Python 双路设置方式以及它和box-sizing、min-height、max-height的协作关系让你能精确掌控 Textual 应用的纵向布局。height属性是什么height样式用于设置一个 Widget 的高度。它是 Textual 布局系统中与width对称的纵向尺寸属性两者都接收一个scalar类型的值。在 src/textual/css/styles.py 中height被声明为height ScalarProperty(percent_unitUnit.HEIGHT) Set the height of the widget.其中percent_unitUnit.HEIGHT的含义是当使用%百分比单位时高度百分比默认相对于容器的高度计算这一点与width的percent_unitUnit.WIDTH正好对应。语法height: scalar;与box-sizing的关系height默认设置的是**内容区content area的高度只有当box-sizing被设置为border-boxTextual 的默认值时height设置的才是边框区border area**的高度。也就是说box-sizing: border-box默认height包含边框与内边距加了padding或border后组件整体尺寸不变但内容空间被压缩box-sizing: content-boxheight只作用于内容区padding和border会在其基础上继续撑大组件。scalar单位体系全解height的取值本质是一个scalar长度值。完整的单位参考表源自 docs/css_types/scalar.md如下单位符号单位名称示例说明无单元格 Cell10单元格行/列数量唯一绝对单位fr分数 Fraction1fr组件应占据的空间比例%百分比 Percent75%相对于容器组件的长度w宽度 Width25w相对于容器组件宽度的百分比h高度 Height75h相对于容器组件高度的百分比vw视口宽度 Viewport width25vw相对于视口宽度的百分比vh视口高度 Viewport height75vh相对于视口高度的百分比—自动 Autoauto尝试计算恰好容纳内容、无需滚动的最优尺寸对应到源码这套单位被定义为 src/textual/css/scalar.py 中的Unit枚举以及符号映射表UNIT_SYMBOLscalar.py。各单位的计算规则Cell无符号高度方向上一格即一行。例如height: 10表示组件高度为 10 行。支持整数与浮点数但浮点数最终会被截断为整数。Fractionfr比例分配剩余空间。例如两个并排组件分别设height: 1fr与height: 3fr后者的高度就是前者的 3 倍。Percent%相对于容器可用空间的比例。height: 50%表示组件高度为容器高度的 50%。w单位相对于容器宽度的比例。height: 25w表示组件高度容器宽度 × 25%。若容器宽 100 格则该组件高 25 格。h单位相对于容器高度的比例。height: 75h表示组件高度容器高度 × 75%。vw单位相对于视口宽度的比例无视中间容器。视口宽度终端宽度减去左右 dock 组件的宽度。height: 6.25vw即视口宽度的 6.25%。vh单位相对于视口高度的比例无视中间容器。视口高度终端高度减去上下 dock 组件的高度。height: 75vh即视口高度的 75%。auto自动计算恰好容纳内容的最优高度。例如一个内容只有一行的Labelheight: auto时其高度就是 1 行。快速上手基础示例原文档附带的入门示例位于 docs/examples/styles/height.pyfrom textual.app import App from textual.widget import Widget class HeightApp(App): CSS_PATH height.tcss def compose(self): yield Widget() if __name__ __main__: app HeightApp() app.run()配套样式表 docs/examples/styles/height.tcssScreen Widget { background: green; height: 50%; color: white; }运行后屏幕上会出现一个绿色背景、高度正好占屏幕 50% 的组件。由于Screen屏幕是它的直接容器height: 50%最终解析为「屏幕高度的一半」。实战对照所有高度格式一次看全原文档的进阶示例用 9 个占位组件把全部单位放在同一个界面中对比演示脚本是 docs/examples/styles/height_comparison.pyfrom textual.app import App from textual.containers import VerticalScroll from textual.widgets import Label, Placeholder, Static class Ruler(Static): def compose(self): ruler_text ·\n·\n·\n·\n•\n * 100 yield Label(ruler_text) class HeightComparisonApp(App): CSS_PATH height_comparison.tcss def compose(self): yield VerticalScroll( Placeholder(idcells), Placeholder(idpercent), Placeholder(idw), Placeholder(idh), Placeholder(idvw), Placeholder(idvh), Placeholder(idauto), Placeholder(idfr1), Placeholder(idfr2), ) yield Ruler() if __name__ __main__: app HeightComparisonApp() app.run()每个Placeholder的id标明其所用的单位右侧还有一个 dock 的垂直标尺方便目测高度。完整的样式表 docs/examples/styles/height_comparison.tcss 如下#cells { height: 2; } #percent { height: 12.5%; } #w { height: 5w; } #h { height: 12.5h; } #vw { height: 6.25vw; } #vh { height: 12.5vh; } #auto { height: auto; } #fr1 { height: 1fr; } #fr2 { height: 2fr; } Screen { layers: ruler; overflow: hidden; } Ruler { layer: ruler; dock: right; width: 1; background: $accent; }假设终端为 80×24文档中对每个高度的注释对应 height_comparison.tcss 中的(1)!(9)!逐条解释了计算过程height: 2—— 固定 2 行高。height: 12.5%—— 容器VerticalScroll高 24 行12.5% × 24 3 行。height: 5w—— 直接容器宽 805% × 80 4 行高注意这里用的是容器的宽度。height: 12.5h—— 直接容器高 2412.5% × 24 3 行高用的是容器的高度。height: 6.25vw—— 视口宽 806.25% × 80 5 行高。height: 12.5vh—— 视口高 2412.5% × 24 3 行高。height: auto—— 内容仅一行因此高度解析为 1。height: 1fr—— 占据 1 份比例空间高度是2fr组件的一半。height: 2fr—— 占据 2 份比例空间高度是1fr组件的两倍。这组例子清楚展示了w/h与vw/vh的区别前两者相对直接容器的宽/高计算后两者相对视口的宽/高计算与中间容器无关。CSS 与 Python 双路设置CSS 方式/* 显式单元格高度 */ height: 10; /* 百分比高度 */ height: 50%; /* 自动高度 */ height: autoPython 方式self.styles.height 10 # 显式单元格高度可以是 int self.styles.height 50% self.styles.height auto从源码看ScalarProperty.__set__src/textual/css/_style_properties.py对 Python 侧的赋值做了三种归一化处理传入int/float直接封装为Unit.CELLS单元格单位传入字符串调用Scalar.parse()解析解析失败会抛出带帮助信息的StyleValueError传入Scalar对象原样采用。无论哪种途径只要规则真正发生变化都会触发refresh(layoutTrue)触发布局重算保证界面立即响应。源码级原理Scalar 的解析与解析height之所以能支持如此多样的单位核心在于 src/textual/css/scalar.py 中的Scalar类型一个由「数值单位百分比基准单位」组成的三元组其解析正则如下scalar.py_MATCH_SCALAR re.compile(r^(-?\d\.?\d*)(fr|%|w|h|vw|vh)?$).matchScalar.parse()会先特判auto其余情况按正则拆分数值与单位符号再映射为Unit枚举成员随后resolve()根据单位在RESOLVE_MAPscalar.py中选择对应的解析函数_resolve_cells直接返回数值本身_resolve_fraction返回fraction_unit × 数值_resolve_width数值 × 容器宽度 / 100_resolve_height数值 × 容器高度 / 100_resolve_view_width/_resolve_view_height分别以视口宽度、视口高度为基准换算。一个值得注意的细节Scalar内部还保存了percent_unit百分比基准单位。height在声明时传入了Unit.HEIGHT因此在resolve()中遇到%单位时会先用percent_unit替换后再查RESOLVE_MAP最终按容器高度计算——这正是「height: 12.5%相对容器高度」这一行为在源码中的落点。与 min-height、max-height、width 的配合height不是孤立属性它通常与以下属性协同工作min-height与max-height限制组件高度的下限与上限。在 styles.py 中它们同样以ScalarProperty(percent_unitUnit.HEIGHT)声明但通过allow_autoFalse禁用了auto取值——也就是说min-height/max-height不能写auto。width设置组件宽度与height共同构成组件的二维尺寸。常见用法给一个百分比高度的组件加min-height兜底避免终端窗口缩小时组件被压得过矮而不可用。小结height是 Textual 布局体系中最常用的纵向尺寸属性其核心在于scalar单位的灵活组合精确控制用单元格height: 10响应式布局用百分比height: 50%或相对视口的vh弹性分配空间用fr自适应内容用auto。理解每种单位相对「直接容器」还是「视口」计算对应源码中size与viewport两个入参再配合box-sizing、min-height/max-height即可在终端与浏览器两种运行环境下都获得稳定、可预期的纵向布局效果。更多相关样式可参考 docs/styles/index.md 的完整样式目录。【免费下载链接】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 高度样式指南：深入理解 `height` 属性与 `＜scalar＞` 单位体系

相关推荐

Podman `--inherit-labels` 选项深度解析：podman build 中基础镜像标签继承的控制机制

NixOS 配置抽象：用 let 与函数消除 Nix 配置重复，以 Apache 虚拟主机为例

Eino流式处理4大范式详解：Invoke、Stream、Collect与Transform实战指南

更多资讯

ERP选型实战指南：从业务场景反推技术能力

一网统管方案落地实战：数据架构、事件模型与性能优化

Smart Connections 接 DeepSeek Harness，TaoToken 填 Key

CC Switch 接 TaoToken：Claude Code 秒切 GLM 5.3 Flash

Atlas 300V 24G部署YOLOv5实战：从ONNX到OM的完整指南

基于MSP430的辐射剂量仪开发：探测器选型、计数与标定

今日更新

校园网认证计费模式详解：AAA与代拨架构、原理及排障

Spring Boot+Vue垃圾分类毕设：分层、权限与排错实战

把 Cline 的 Base URL 改到 TaoToken 之后，DeepSeek 仍能修调试配置

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？