跳转至

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-padding INV11 要求宿主发布其已应用的内边距,而 component:List FR8 将 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