Section 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公开契约 | 一个通用页面区域,带有 variant、选定的 dividers、带轴向和边缘覆盖的 padding,以及盒尺寸。 |
| 行为 | 外层包装器接受尺寸和调用方输入,并脱离父级的内缩空间;内层容器负责绘制 variant 和分隔线,并发布其 padding。 |
| 终端用户影响 | 读者会看到相关内容被分组在一个区域中,该区域的边缘和间距与周围的布局对齐。 |
| 构建者影响 | 无;此记录描述已发布的行为。 |
| 兼容性/就绪状态 | 将已发布行为记录为当前状态;无 API、默认值或输出变更。一个实现差距列于“当前状态影响”之下。 |
| 评审检查 | 拒绝物理左/右分隔线或 padding、不会移动其对应容器变量的边缘 padding,或失去脱离能力的嵌套 Section。 |
| 约束规则 | family:layout-regions/FR2,FR4,FR5,FR7–FR9;architecture:container-padding;architecture:public-component-api/INV5,INV6,INV8。 |
此表是评审投影;以下正文具有权威性。
意图¶
Section 是 layout-regions 家族中的通用绘制区域。它负责自身的 variant、选定的分隔线边缘、组件 padding,以及嵌套 Section 如何脱离其父级的内缩空间。
兼容性与迁移¶
- 已发布默认值保留:
yes - 兼容性类别:记录已发布行为;无公开 prop、默认值、DOM、样式或目标变更。
- 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移说明应放在消费者文档和发布说明中。
当前状态影响¶
- 绘制区域低于其最小高度(FR1)。 当设置
minHeight而未设置height时,外层包装器达到最小值,但内层容器(承载背景、分隔线和 padding)仍保持其内容高度。因此,muted或section区域只绘制其顶部部分,其底部分隔线会位于外层包装器底部边缘之上。
所有权边界¶
拥有
- 外层包装器和带
section目标的内部绘制容器。 - variant 绘制、选定的分隔线边缘、组件 padding 及其发布,以及嵌套脱离。
不拥有 / 非目标
- Section 内部的调用方内容。
- 槽位排列——由
component:Layout及其区域拥有。 - 地标语义、滚动和响应式替代——Section 不提供这些(
family:layout-regionsFR7–FR9)。
公开概念¶
| 概念 | 封闭值或状态 | 含义 | 按 variant/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| Variant | section、transparent、muted;主题新增 |
区域背景。 | 始终 | section |
component:Section |
稳定 | 没有匹配主题规则的主题新增值不会渲染 Section 背景,并保留 data-variant。 |
| Dividers | 任意 top、bottom、start、end |
哪些边缘绘制 1px 边框。 | 始终 | none | component:Section |
稳定 | TypeScript 拒绝其他值。 |
| Padding | 统一、按轴向或按逻辑边缘的间距档位 | 内部 padding,发布给后代。 | 始终 | 按 FR3 解析 | component:Section |
稳定 | TypeScript 拒绝其他值。 |
| Sizing | width、height、maxWidth、minHeight |
外层包装器的盒尺寸。 | 始终 | unset | component:Section |
稳定 | 字符串按 CSS 原样传递。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | Section 渲染一个外层 div 包裹层,其中包含一个内层 div,内层 div 带有 section 目标、反映 variant,并承载子内容。内层容器填满外层包裹层的高度。实现差距:它只填充设定的 height;仅使用 minHeight 时,被绘制的容器在更高的包裹层内保持自身内容高度(当前状态影响)。 |
当前源代码与测试 |
| FR2 | section 绘制 --color-background-surface,transparent 不绘制任何背景,muted 绘制 --color-background-muted;主题添加的变体若没有匹配的主题规则,则不绘制背景,但仍反映 data-variant(architecture:component-theming-surface INV14)。每个选中的分隔线在相应边缘绘制 1px 实线 --color-border 边框;start 和 end 是逻辑内联边缘。 |
当前源代码与测试 |
| FR3 | 省略 padding 时,按边缘依次解析主题的逐边缘和逐轴 section 内边距、最近祖先 Section 的显式 padding、主题的单一 section 内边距,然后是间距步长 4。一个步长设置统一内边距,并将其作为容器内边距变量发布给后代;未设置 padding 的嵌套 Section 会继承该值,但跨越 overlay 边界或布局根(如 AppShell 的根)时除外,此时继承值停止(architecture:container-padding INV5、component:AppShell FR18、component:Layout FR8)。paddingInline 和 paddingBlock 覆盖一个轴,边缘 prop 只覆盖其单独边缘;每次覆盖都会移动对应的容器内边距变量。 |
当前源代码、测试和族系记录 |
| FR4 | 包裹层脱离其父级发布的容器内边距:在两个内联边缘始终脱离;在块起始边缘仅作为第一个子元素时脱离,在块结束边缘仅作为最后一个子元素时脱离。内层容器在发布自己的内边距变量之前重置继承的内边距变量。 | 当前源代码与族系记录 |
| FR5 | ref、className、style、xstyle、尺寸以及 DOM、data、ARIA 和事件 props 都会到达外层包裹层;尺寸 props 中的数字以像素为单位。内层被绘制的容器不接收其中任何一项;Toolbar 依赖包裹层路由。 |
当前源代码与测试 |
允许的变化¶
- AV1 — 主题绘制。 主题可按
variant为section重设样式,并设置 section 内边距。 - AV2 — 内容。 任何调用方内容填充该区域。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 默认 | 表面绘制;主题 section 内边距;无分隔线。 | 内容。 |
| 带分隔线 | 选中逻辑边缘上的 1px 边框。 | 边缘。 |
| 边缘覆盖 | 仅指定的边缘连同其容器变量发生变化。 | 步骤。 |
| 嵌套 | 内部 Section 在内联方向以及首/末块边缘处脱离外部内边距。 | 变体。 |
变换与优先级顺序¶
- ORD1 — 每边缘内边距。 边缘 prop → 轴向 prop →
padding→ 主题中每边缘和每轴向的 Section 内边距 → 最近祖先 Section 的显式padding,且不跨越叠加层边界或布局根 → 主题中的单一 Section 内边距 → 间距步骤 4。
性能与资源¶
- PR1 — 静态渲染。 Section 不持有状态,也不使用任何 hook。
无障碍契约¶
- AR1 — 不添加语义。 Section 不添加 role、名称、地标或 Tab 停靠点(
family:layout-regionsFR8);当上下文需要时,由调用方提供 role 和标签。
设计关系¶
| 结构或状态 | 设计要求 | 表示权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| Section 容器 | 带可选分隔线和内边距的绘制区域。 | 当前源码与文档 | 支撑性 | FR1–FR4 |
| 使用方内容 | 区域内部的调用方内容。 | 调用方提供的内容 | 视上下文而定 | AR1 |
主题结构¶
{
"Section container": {"target": "section"},
"Consumer content": {
"none": {
"reason": "intentional: caller content keeps its own theming ownership; Section applies no content target."
}
}
}
外层包装器是实现结构,不携带任何目标。
家族与系统关系¶
family:layout-regions将 Section 命名为通用区域和容器发布者;FR2–FR4 应用其逻辑方向、内边距和边界规则。architecture:container-padding掌管 Section 发布并脱离的内边距协议。architecture:public-component-api掌管调用方输入的路由;FR5 将外层包装器指定为在 INV5 和 INV8 下接收调用方输入和ref的元素。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1, FR2 | Section.test.tsx 结构和变体测试;稳定的视觉基线 core-section--default |
变体;默认 Section | 丢失两层 div 结构、内层 div 上丢失 section 目标,或变体体现丢失,都会导致失败;默认表面的变化会原样返回以供审查。缺口:分隔线测试仅断言内容能渲染,因此分隔线边框以及 transparent 和 muted 绘制没有自动化检查;也没有任何检查断言内层容器填满包装器的高度,包括 minHeight 缺口。主题新增的变体若没有匹配的规则,同样没有针对性测试。 |
audit:Section/anatomy |
| FR3, ORD1 | Section.test.tsx 内边距、传播和边缘覆盖测试;overlayPaddingReset.test.tsx;layoutReset.test.tsx;AppShell.test.tsx 中的 “AppShell 布局根 (FR18)” 套件;Section.stories.tsx 中的 NestedPaddingInheritance |
均匀、轴向、边缘、嵌套;位于叠加层内部;位于带内边距的 Section 内部的 AppShell | 将轴向视为两条边缘的漂移、末端边缘上边缘覆盖轴向、嵌套 Section 的传播值丢失、祖先 Section 的内边距跨越叠加层边界或布局根,或容器变量(内联或块级)未随边缘覆盖一起移动,都会导致失败。缺口:起始边缘上边缘覆盖轴向、轴向覆盖均匀、主题中每边缘和每轴向的内边距优先于继承值,以及变量在轴向和边缘两条路径上都停止移动,这些情况均无检查。 | audit:Section/layout |
| FR4 | Section.stories.tsx 在浏览器中的嵌套夹具 |
嵌套的 Section | 缺口:没有单元测试断言脱离外边距;脱离效果一旦丢失,即可在渲染的夹具中看到。 | audit:Section/layout |
| FR5 | Section.test.tsx ref、className、style 和透传测试 |
调用方输入 | 如果 className 或 style 未作用到外层包装,或 data-testid 被丢弃,测试会失败。差距:ref 测试接受任一 div,透传测试在树中的任意位置查找 data-testid,因此 DOM、data、ARIA 和事件属性的传递没有检查;尺寸和 xstyle 测试仅断言内容能够渲染。 |
audit:Section/api |
| AR1, PR1 | serverSafeComponents.test.ts;源码审查 |
每个状态 | 未添加客户端指令的客户端 API(state、hook)会导致 serverSafeComponents.test.ts 失败。差距:与客户端指令一起添加的客户端 API 可以通过;如果 Section 添加了角色、名称、地标或 Tab 停靠点,没有任何自动化检查会失败。 |
audit:Section/a11y |
| Theming anatomy map | scripts/check-knowledge.mjs |
使用方的结构组成和当前目标 | 缺失、多余或过时的映射会导致仓库验证失败。 | audit:Section/theming |
决策日志¶
无记录。此记录描述的是已发布行为。
待解决问题¶
无。
内容边界¶
本文件不重复使用者的 prop 表/示例、当前审计结果、实现步骤或家族/系统规则。它会链接到这些内容的维护方。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx