图表组件契约¶
意图¶
Chart 组件负责协调一个响应式笛卡尔坐标系绘图。它派生共享比例尺、分配默认系列颜色、将绘制委托给系列定义,并承载可选的图表装饰层和交互层。
兼容性与迁移¶
- 已发布的默认值保持不变:
not yet stable;@astryxdesign/charts仅限 canary 版本。 - 兼容性类别:现有 props、默认值、渲染顺序和输出不受此观察性回填的影响。
- 受控/非受控行为:不适用。
- 迁移决策:无;本草案不授权任何公开 API 变更。
使用方迁移说明应放在使用方文档和发布说明中。
所有权边界¶
拥有
- 测量图表容器并派生一个绘图区域和比例尺集合。
- 对系列、图表装饰层和交互槽位进行排序、裁剪和协调。
- 图表图像的可访问名称和小数据表回退。
不拥有 / 非目标
- 标记特有的几何形状或渲染;这些细节由每个系列定义自行负责。
- 轴、网格、图例或提示框在根节点中的放置之外的呈现。
- 对提供数据的特定于产品的解释、摘要或分析。
公共概念¶
| 概念 | 闭合值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 数据模型 | data、xKey、series |
单个绘图的行、共享 x 字段和标记定义。 | 始终必需。 | 无 | component:Chart |
实验性 | 缺少的字段会被 TypeScript 拒绝;格式错误的行值由每个标记自行处理。 |
| 高度 | 有限数值 | 外层 SVG 的 CSS 像素高度。 | 所有图表。 | 300 |
component:Chart |
实验性 | 负值或非有限值解析为 0。 |
| 绘图边距 | 部分 top、right、bottom、left 数值 |
内缩共享绘图区域。 | 所有图表。 | {top: 24, right: 24, bottom: 32, left: 48} |
component:Chart |
实验性 | 非有限的最终几何会被钳制为 0;物理字段名称仍是一个未决的 API 问题。 |
| Y 基线 | auto、zero、data |
选择感知标记的零值/留白、对称零值或紧凑的数据范围。 | 当 yDomain 不存在时使用。 |
auto |
component:Chart |
实验性 | 未知值会被 TypeScript 拒绝。 |
| 显式域 | xDomain、yDomain 有限数值对 |
固定数值比例尺的域。 | xDomain 在分类 x 轴上被忽略;yDomain 覆盖基线和刻度取整。 |
缺失 | component:Chart |
实验性 | 非有限数值对回退到自动推导。 |
| 图表装饰层 | grid、axes、legend、tooltip |
在系列周围放置调用方提供的或内置的图表上下文消费者。 | 可选。 | 关闭/缺失 | component:Chart |
实验性 | 布尔值或配置值为 false/省略时会禁用内置表面。 |
| 扩展槽位 | interactions、children |
按定义的绘制顺序添加交互覆盖层和高级 SVG 内容。 | 可选。 | 缺失 | component:Chart |
实验性 | 调用方内容按原样渲染。 |
| 可访问文本 | title、subtitle、生成的回退 |
命名并描述图表图像。 | 所有图表;当提供时可见。 | 本地化生成的名称 | component:Chart |
实验性 | 当不存在主系列时,使用通用本地化名称。 |
| 根 DOM 表面 | BaseProps<HTMLDivElement>、ref |
转发标准 DOM、data、ARIA、class、style、StyleX、事件以及根元素 ref。 | 所有图表。 | 缺失 | component:Chart |
实验性 | 组件自有的 SVG 语义保留在 SVG 上。 |
行为与布局契约¶
草案需求会标明其依据,以免将观察到的代码误认为有意的决策。
| ID | 候选不变量 | 依据 | 草案审查状态 |
|---|---|---|---|
| FR1 | Chart 在其宽度为零时 MUST 保留配置的高度,然后在容器调整大小后重新计算绘图几何。 | 当前实现及 Chart measurement gate 测试 |
待验证 |
| FR2 | 所有系列、坐标轴、网格线、工具提示和交互 MUST 使用一套共享的比例尺,该比例尺源自当前数据、定义域、基线和测量后的绘图尺寸。 | README、实现及包测试 | 待验证 |
| FR3 | 绘制顺序 MUST 保持为 网格 → 裁剪后的系列 → 坐标轴 → 指针层 → 交互 → 内置工具提示 → 子节点。 | 当前实现及渲染委派测试 | 待验证 |
| FR4 | 没有静态颜色的主系列 MUST 从当前主题调色板获取确定性颜色;工具标记 MUST NOT 占用调色板或图例槽位。 | 实现、调色板测试及浏览器证据 | 待验证 |
| FR5 | 指针移动 MUST 被归一化为绘图坐标,并派发最近的 x 位置;离开绘图区域 MUST 清除指针状态。 | 当前实现及工具提示浏览器证据 | 待验证 |
| FR6 | legend=true MUST 从主系列派生图例项;图例和工具提示配置对象 MUST 在覆盖受支持选项的同时启用其展示层。 |
当前实现及聚焦测试 | 待验证 |
| FR7 | 图表 MUST 暴露一个具名的 role="img";提供的副标题 MUST 作为其描述;最多 100 个 行×系列 单元格的数据集 MUST 也镜像到视觉隐藏的表格中。 |
当前实现、WCAG 1.1.1 及可访问性测试 | 待验证 |
| FR8 | 根 DOM props 和 ref MUST 到达根容器,同时 Chart 自身的 SVG 名称和描述保持权威。 |
共享 BaseProps 约定及聚焦回归测试 | 待验证 |
允许的变化¶
- AV1 — 系列输出。 标记定义在保留共享布局和渲染顺序接缝的前提下,可以渲染不同的 SVG 或 canvas 内容。
- AV2 — 消费方外壳。 网格、坐标轴、交互和子节点插槽可以缺失,也可以包含任何有效的图表上下文消费方内容。
代表性状态¶
| 状态 | 必需不变量 | 允许的变化 |
|---|---|---|
| 宽度未测量 | 仅保留高度的根节点;没有无效的 SVG 几何。 | 消费方根节点的样式和 DOM props 仍然生效。 |
| 正常数据 | 共享的有限比例尺,以及每个已解析系列对应的一个裁剪分组。 | 标记形状、颜色和内容来自系列定义。 |
| 空数据 | 有限的回退比例尺;没有无效的标记几何。 | 可见的空状态处理仍未确定。 |
| 小数据 | 具名图像加上隐藏的数据表。 | 单元格文本遵循提供的行值。 |
| 超过 100 个单元格 | 具名图像;省略内置隐藏表格。 | 等效的大数据替代方案仍未确定。 |
| 标题和副标题 | 可见标题;SVG title/description 关联。 | 消费方文本内容。 |
| 启用图例 | 在顶部、底部、起始处或结束处显示派生或显式项。 | 对齐方式和提供的项。 |
| 启用工具提示 | 指针更新指示器和分组工具提示;离开时清除。 | 自定义渲染器和放置方式。 |
| 窄布局 / RTL | 没有水平页面溢出;逻辑堆叠位置遵循方向。 | 物理图表域顺序仍由数据决定。 |
转换与优先级顺序¶
- ORD1 — 尺寸。 合并默认和提供的边距 → 限制高度和内部尺寸 → 派生比例尺 → 解析系列 → 按 FR3 顺序渲染。
- ORD2 — 定义域。 有限的显式定义域优先;否则派生有限的数据范围 → 扩展退化范围 → 应用请求的基线/留白 → 仅对自动定义域应用刻度取整(nicening)。
- ORD3 — 可访问名称。 提供的标题优先;否则使用提供方的区域设置格式化主系列标签,并用
xKey进行插值;如果没有主系列,则使用本地化的通用名称。
性能与资源¶
- PR1 — 调整大小观察。 每个已挂载的图表都会使用专用的
ResizeObserver观察其根元素,并在卸载时断开连接;迁移到共享观察器仍是审计 FIX。 - PR2 — 指针派发。 指针移动直接更新订阅者;只有当最近的数据索引发生变化时,tooltip 的 React 状态才会改变。
无障碍契约¶
- AR1 — 命名图像。 SVG MUST 通过
role="img"暴露已解析的可访问名称。 - AR2 — 描述。 提供的副标题 MUST 通过
aria-describedby链接到 SVGdesc。 - AR3 — 小数据替代方案。 最多 100 个 行×主系列 单元格 MUST 在具有语义表头且视觉隐藏的表格中镜像呈现。
- AR4 — 大数据缺口。 当前在表格阈值之上仅提供名称的路径并不保证等效替代;解决该问题需要所有者审查,且其仍是审计发现项。
- AR5 — Tooltip 补充。 指针 tooltip 内容 MUST NOT 成为所需图表信息的唯一可用来源。
设计关系¶
| 结构或状态 | 设计要求 | 呈现责任方 | 层级角色 | 组件契约 |
|---|---|---|---|---|
| 头部 | 核心 Text 角色 | 委托给 component:Text |
辅助 | FR7 |
| 绘图区与标记 | 有意义的图形满足渲染对比度要求 | 客观 WCAG 阈值;标记表示方式尚未确定 | 主要 | FR2、FR4 |
| 图例 | 标签和色块保持系列关联 | 委托给 component:ChartLegend |
辅助 | FR6 |
| Tooltip | 临时叠加层 | 当前设计约定 | 辅助 | FR5、FR6、AR5 |
| 隐藏表格 | 非视觉数据替代方案 | 客观的无障碍语义 | 辅助 | AR3、AR4 |
主题化结构¶
{
"Header": {
"none": {
"reason": "intentional: Text owns the visible title and subtitle styling."
}
},
"Plot": {
"none": {
"reason": "unsettled: Chart does not currently expose a public theme target for the SVG plot root."
}
},
"Grid and axes": {
"none": {
"reason": "unsettled: ChartGrid and ChartAxis own their output but do not yet have current component contracts."
}
},
"Legend": {
"none": {
"reason": "unsettled: ChartLegend owns the visible legend but does not yet have a current component contract."
}
},
"Tooltip and interactions": {
"none": {
"reason": "unsettled: ChartTooltip and consumer interaction layers own their painting surfaces."
}
},
"Data table": {
"none": {
"reason": "intentional: The small-data table is visually hidden accessibility content."
}
}
}
家族与系统关系¶
architecture:component-test-sufficiency负责证据质量和合理的状态划分。architecture:component-theming-surface负责从结构到主题的可达性。spec:AST-002负责公共 API 准入和操作形态。spec:AST-029负责观察性审计回填和外部证据接收。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 | 审计部分 |
|---|---|---|---|---|
| FR1、PR1 | Chart.test.tsx;Chromium 窄屏捕获 |
零宽度和正宽度;调整大小;320 px | 移除测量或清理逻辑会导致绘图区空白/过期,或产生观察器泄漏。 | audit:Chart/responsive-code-health |
| FR2–FR4、ORD1–ORD2 | Chart 与包测试;明/暗浏览器矩阵 | band 与 linear x;自动/显式域;分组/堆叠/工具标记 | 比例尺发散、几何体变为非有限值、裁剪/顺序改变,或调色板所有权发生偏移。 | audit:Chart/behavior-theming |
| FR5–FR6、PR2 | tooltip/legend 测试;Chromium 悬停和布局捕获 | 悬停/离开;派生/配置的图例;所有位置 | tooltip 状态过期、指针操作导致逐次移动提交,或界面元素渲染在错误的图层。 | audit:Chart/behavior |
| FR7、AR1–AR5、ORD3 | 可访问名称/表格测试;包特定的 axe;浏览器证据 | 标题/副标题;生成的名称;小型、空、大型数据 | 名称/描述消失、小型数据表格丢失、本地化回归,或大数据缺口被隐藏。 | audit:Chart/accessibility-i18n |
| FR8 | 根属性/ref 回归测试及包类型检查 | 占位渲染和测量渲染 | DOM props 或 ref 无法到达根元素,或使用者样式替换了组件样式。 | audit:Chart/public-api |
决策日志¶
无。本草案仅记录观察到的行为和未解决的缺口。
开放问题¶
- OQ1 — 大数据替代方案。 在 100 单元格表格截断之后,Chart 必须保证哪些等效的非视觉数据或摘要契约?(
human-api) - OQ2 — 方向性边距。 实验性的物理
left/right边距字段是否应在稳定版发布前迁移为逻辑名称?(human-api) - OQ3 — 系列元数据。 在金丝雀 API 稳定之前,每个图表的标识、堆叠状态和解析后的颜色应如何移入私有边界之后?(
human-api) - OQ4 — 主题根。 Chart 是否应为其绘图/根表面公开一个公共目标,还是有意保持仅 token?(
human-design)
内容边界¶
本文件不重复消费方 prop 表/示例、当前审计结果、实现步骤或共享系统规则。它链接到其所属方。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx