Card 组件契约¶
契约概览¶
| 领域 | 契约 |
|---|---|
| 公共契约 | 一个具有尺寸属性、间距刻度上的 padding、主题可扩展的 variant 以及静态 elevation 的容器。 |
| 行为 | Card 绘制圆角表面,通过容器内边距协议向其子级发布内边距,并且只有 default 变体绘制边框。 |
| 最终用户影响 | 读者可以在一致的表面上看到分组内容;在默认边框和主题边框宽度下,无论是否绘制边框,内容内边距都保持在间距刻度上,零内边距时除外。 |
| 构建者影响 | 无;该记录描述的是已发布的行为。 |
| 兼容性/就绪状态 | 已发布的行为记录为当前状态;无 API、默认值或输出变更。当前状态影响下列出了一个实现差距。 |
| 审查检查 | 拒绝以最小内容宽度保持其轨道的卡片、回退到另一个变体的变体、丢失的内边距发布,或发布的内边距进一步偏离已应用的内边距。 |
| 治理规则 | architecture:container-padding(容器发布者);architecture:component-theming-surface/INV6,INV14;architecture:public-component-api/INV5,INV6,INV8。 |
此表是审查投影;以下正文具有权威性。
意图¶
Card 将相关内容分组到一个容器表面上。它拥有该表面的绘制、边框、圆角、阴影、尺寸,以及它发布的内边距,以便 Layout 和其他后代与其对齐。
兼容性与迁移¶
- 已发布的默认值保留:
yes - 兼容性类别:记录已发布的行为;无公共属性、默认值、DOM 或样式输出变更
- 受控/非受控行为:不适用
- 迁移决策:无
消费者迁移说明属于消费者文档和发布说明。
当前状态影响¶
- 已发布的内边距超过已应用的内边距(FR3)。 在非零内边距下,
default卡片应用的内边距减去其边框宽度,但发布的是边框加内边距(在padding={0}时两者相等)。任何在任意边缘出血到已发布内边距的子级——全出血的 Divider、Layout 或 List 的outset或bleed框——都会超出内边距边缘一个边框宽度。持有此类子级的固定高度卡片,会在子级出血的每个轴上滚动该量(对于 Layout 则是两个轴),并且即使其内容适合,也会成为一个未命名的 Tab 停靠点:在 Chromium 中当它不包含任何可聚焦元素时,在 Firefox 中即使它包含可聚焦的子级也是如此。architecture:container-paddingINV11 要求宿主发布其已应用的内边距,而component:ListFR8 将 Card 的内容区域视为这样的宿主,因此非零内边距下的default卡片尚不满足 List FR8:List 的outset和bleed列表会超出其内边距边缘一个边框宽度,bleed行也是如此。
所有权边界¶
拥有
- Container:表面绘制、边框、圆角、阴影、尺寸和裁剪。
- 作为容器发布者解析和发布卡片内边距。
不拥有 / 非目标
- 卡片内部的内容结构——由调用方和 Layout 拥有。
- 交互——由组合 Card 的
component:ClickableCard和component:SelectableCard拥有。 - 内边距协议本身——由
architecture:container-padding拥有。
公共概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 变体 | default、transparent、muted、blue、cyan、gray、green、orange、pink、purple、red、teal、yellow;主题扩展 |
表面绘制;只有 default 绘制边框。 |
始终 | default |
component:Card |
稳定 | 主题添加的值会体现在 card 上,并渲染为无填充且无边框的基础表面。 |
| 阴影 | none、low、med、high |
来自阴影令牌刻度的静态阴影。 | 始终 | none |
component:Card |
稳定 | TypeScript 拒绝其他值。 |
| 内边距 | 间距刻度 0、0.5、1、1.5、2、3、4、5、6、8、10;省略 | 统一内边距;省略时使用主题的卡片内边距。 | 始终 | 主题卡片内边距 | component:Card |
稳定 | TypeScript 拒绝其他值。 |
| 尺寸 | width、height、maxWidth、minHeight:以像素为单位的数字或 CSS 字符串 |
卡片盒的大小。 | 始终 | unset | component:Card |
稳定 | 字符串将作为 CSS 直接传递。 |
行为与布局契约¶
| ID | 不变量 | 依据 |
|---|---|---|
| FR1 | Card 渲染一个携带 card 目标的 div,该 div 反映 variant 和 elevation,具有 --radius-container 圆角,并使用由选中环和 elevation 阴影组成的盒阴影。 |
当前源代码与测试 |
| FR2 | default 绘制 --color-background-card,并带有一条宽度为 --border-width 的实线 --color-border 边框;transparent 不绘制任何内容;muted 绘制 --color-background-muted;每个调色板变体绘制其 --color-background-<name> 色调。主题新增的变体会回退到基础表面,而绝不会回退到另一个变体。 |
当前源代码与测试 |
| FR3 | Card 作为容器发布者解析内边距:省略 padding 时使用主题的卡片内边距(无主题时为间距步长 4),且该步长会均匀地应用于每一条边。对于 default 边框,每条边的内边距都会减去全局 --border-width token(减到零为止),因此边框加内边距与无边框时的内边距一致。发布的内边距与卡片实际应用的内边距一致(architecture:container-padding INV11)。实现差距:在非零内边距下,default 卡片发布的是边框加内边距,比其实际应用的内边距多出一个边框宽度;因此通栏子元素会超出内边距边缘,固定高度卡片会按该宽度产生滚动,且该卡片尚不满足 component:List FR8(当前状态影响)。 |
当前源代码与测试 |
| FR4 | Card 的最小宽度为零,因此它会向所在轨道让步,而不是以最小内容宽度撑住轨道;同时它会裁剪溢出内容,但不会成为滚动容器。height 不为 auto 时,卡片会滚动。width、height、maxWidth 和 minHeight 按给定值生效,调用方设置的最小值可以优先于 width。 |
当前源代码与测试 |
| FR5 | elevation 将 elevation 阴影设置为 none,或设置为低、中或高阴影 token。 |
当前源代码与测试 |
| FR6 | ref 到达 div。受支持的 DOM、ARIA、data 与事件属性都会到达承载目标的元素;xstyle、className 和 style 按该顺序在组件样式之后合并,调用方的 className 会附加到目标类而非替换它。 |
当前源码与测试 |
允许的变化¶
- AV1 — 主题绘制与内边距。 主题可以根据
variant和elevation重新设置card的样式,包括边框宽度与颜色,并设置卡片的内边距。 - AV2 — 内容。 任意内容都可以填充卡片。
代表性状态¶
| 状态 | 必需不变式 | 允许的变化 |
|---|---|---|
| 默认 | 带边框的卡片表面;内边距等于主题卡片内边距。 | 内容。 |
| 无边框变体 | 无边框;与 default 的内边距相同,唯一例外是在 padding={0} 时,default 会增加其边框宽度。 |
变体。 |
| 主题新增变体 | 基础表面;data-variant 标明所添加的值。 |
主题绘制。 |
| 固定高度 | 滚动其内容;仍在其轨道中让出空间。 | 高度。 |
| 已抬升 | 抬升阴影与任何环状描边并存。 | 抬升。 |
转换与优先级顺序¶
- ORD1 — 内边距。
padding步骤 → 主题卡片内边距 → 间距步骤 4;然后针对default每边减去边框宽度,直到为零。 - ORD2 — 阴影。 环状描边与抬升阴影在同一个阴影列表中合成;两者都不会取代对方。
性能与资源¶
- PR1 — 静态渲染。 Card 不持有状态,也不使用任何 hooks。
无障碍契约¶
- AR1 — 不新增语义。 Card 本身不添加 role、name 或 tab stop;其内容的语义直接透传。例外:内容溢出的固定高度卡片是滚动容器(FR4),浏览器可能将其变为未命名的 tab stop,以便键盘用户可以滚动它(在 Chromium 中,当它不包含任何可聚焦内容时;在 Firefox 中,即使它包含可聚焦子元素也如此)。
设计关系¶
| 构成或状态 | 设计要求 | 呈现权威 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 容器 | 带有背景、可选边框和内边距的圆角表面。 | 当前源码与文档 | 支撑 | FR1–FR5 |
| 内容 | 调用方内容,位于已发布的内边距内。 | 当前源码与文档 | 主要 | FR3, AR1 |
主题化结构¶
{
"Container": {"target": "card"},
"Content": {
"none": {
"reason": "intentional: caller content keeps its own styling and has no component-owned paint target"
}
}
}
家族与系统关系¶
architecture:container-padding将 Card 命名为容器发布者;FR3 记录了 Card 如何解析并发布其内边距。component:ClickableCard和component:SelectableCard组合 Card;选择环与 Card 的抬升阴影合成(ORD2)。architecture:component-theming-surface设定了card目标所遵循的规则(INV6),并将variant限定为主题可扩展的轴(INV14)。
验证映射¶
| 契约 | 验证 | 代表性状态 | 突变或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR1, FR2, FR5, ORD2 | Card.test.tsx 反射、内置变体、阴影层级和主题添加变体测试;稳定视觉基线 core-card--default 和 core-card--theme-added-variant(探测主题) |
每个内置变体;阴影层级;添加的值;默认卡片 | 丢失的反射、没有自身类的阴影层级,或主题添加的值落入另一个变体则失败;默认表面、边框、圆角或静止阴影发生变化,或主题添加的卡片丢失其主题绘制,会以更改后的形式返回以供审查。差距:调色板色调、阴影层级值以及环与阴影的组合,除这两条基线外没有自动化检查。 | audit:Card/theming |
| FR3 | 在浏览器中运行 Card.stories.tsx |
默认和无边框变体;内边距档位 | 差距:没有单元测试断言内边距的发布或边框减法;内边距不匹配仅在渲染的夹具中可见。默认卡片中的全出血溢出没有自动化检查。 | audit:Card/layout |
| FR4 | Card.test.tsx 尺寸测试套件 |
每个变体;固定高度;调用方最小值 | 保持的最小内容宽度、没有固定高度的滚动容器,或丢失的调用方最小值则失败。 | audit:Card/layout |
| FR6 | Card.test.tsx 的 ref、透传和 className 测试 |
Ref;额外 props;className | 另一个元素上的 ref、目标以外的元素上的 prop,或替换的目标类则失败。差距:没有测试断言 xstyle、className、style 的合并顺序。 |
audit:Card/behavior |
| 主题结构映射 | scripts/check-knowledge.mjs |
消费者结构和当前目标 | 缺失、多余或过时的映射使仓库验证失败。 | audit:Card/theming |
| AR1, PR1 | 源码审查 | 每个变体 | 差距:如果 Card 添加 role、制表位、状态或钩子,没有自动化检查会失败。没有测试覆盖固定高度溢出的制表位,无论是否带有可聚焦内容。没有测试覆盖固定高度默认卡片因出血子元素溢出而获得的制表位。 | audit:Card/behavior |
决策日志¶
无记录。该记录描述的是已交付的行为。
未决问题¶
无。
内容边界¶
本文件不重复消费者 prop 表/示例、当前审计结果、实施步骤或族/系统规则。它链接到其所有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx