跳转至

图表组件契约

意图

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 链接到 SVG desc。
  • 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