跳转至

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-regions FR7–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-regions FR8);当上下文需要时,由调用方提供 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