60FOLDCOMPONENTS

共享图表选项

在线图表和股票图表上可用的选项和运行时控件。

LineChartOptions 和 StockChartOptions 包含相同的交互、坐标轴、标签、覆盖层、视口和渲染控件。你无需构建基础图表或导入内部渲染引擎。

请参阅 Line options] 或 Stock options] 以获取精确字段。共享运行时方法直接出现在 LineChart] 和 StockChart] 上。

构造组

渲染器与交互

  • renderMode 选择 auto、worker 或 main。使用 getRenderMode() 读取实际结果。
  • rendererInitializationTimeout 以毫秒为单位限制渲染器启动时间。默认值为 15 秒，从构造开始计时，可设置为 0 以禁用看门狗。
  • interactive: false 在保留悬停信息的同时禁用平移、缩放、捏合和选择。
  • minViewportRange 限制 X 数据单位方向的缩放。
  • yDomain: { min, max } 在缩放、细节层级（LOD）更改和流式更新中固定一个或两个 Y 轴域边缘；被省略的边缘保持自动缩放。
  • wheelZoomSpeed、wheelZoomDirection、keyboardZoomSpeed 和 keyboardPanSpeed 用于微调导航。
  • keyboardActivation 在基于焦点或基于悬停的键盘控制之间进行选择。
  • keyboardAnnouncements 本地化在键盘平移、缩放、重置和取消选区后发出的礼貌状态消息；其可选的 viewport 模板接受 {startPercent}、{endPercent} 和 {spanPercent}。当宿主提供等效反馈时，将其设置为 false。
  • animated 控制数据揭示以及视口/坐标轴过渡。省略时，prefers-reduced-motion: reduce 禁用动画，并且在图表保持挂载时会观察到对该偏好的更改。显式的 true 或 false 保持优先。

画布内容

grid、axis、chartBackground、rangeSelector、tooltip、crosshairStyle、selection、labels、overlay、padding 和 textDirection 在折线图和股票图上以相同方式工作。

图表排版的默认值为导出的 DEFAULT_CHART_FONT_FAMILY，这是一个以 SFMono 为首的字体栈。每个表面级别的 family 字段仍然具有最终权威。

当实时显示应保持视觉尺度而不是随每个新极值改变时，请使用完全固定的域：

const chart = new LineChart(canvas, {
  yDomain: { min: 0, max: 100 },
});

yDomain 默认处于禁用状态。它由折线图和股票图共享，并在 Worker、主线程 和 SSR 渲染中一致适用。

视口控制

const current = chart.getViewport();

chart.setViewport(
  { xMin: current.xMin + 60_000, xMax: current.xMax - 60_000 },
  { animated: true },
);

chart.reset({ animated: true });

省略的视口边缘将保留其当前值。范围相对于完整数据范围和图表的 minViewportRange 进行归一化。

运行时外观

仅可在构造时设置的行为与可在运行时修改的外观有意分离。getOptions() 返回完整的规范化快照，getAppearance() 仅返回可在运行时安全更新的字段。两者的类型都是 DeepReadonly 快照；嵌套的普通对象和数组会被复制。因此，请通过运行时方法应用更改，而不要直接修改返回值。

chart.updateAppearance({
  chartBackground: "#081018",
  grid: { color: "rgba(130, 180, 220, 0.16)" },
  axis: { bottom: { labelFont: { color: "#a9bac9" } } },
});

补丁会合并到当前外观。setLabels() 和异步 setOverlay() 是针对相同状态的便捷方法。

当一次用户操作更新多个属性时，将同步更改批处理：

chart.batch(() => {
  chart.updateAppearance({ grid: { color: "#26384a" } });
  chart.setViewport({ xMin, xMax });
});

不要在 batch 内调用 await；只有回调返回前所做的同步调用会被合并。

工具提示

内置提示工具使用 Canvas2D 渲染。tooltip.onRender 在主线程上执行，可替换其标题和行；须保持高效，因为指针移动可能频繁触发。tooltip.onLeave 适合用于清理应用状态。

对于较大的数值 X 使用显式 titleFormat。自动检测会将大约超过十亿的值视为类时间值。

覆盖层

覆盖层支持相对于图表区域或整个画布的比率或 CSS 像素坐标中的文本、矩形、圆、线和图像。字符串图像源会异步获取并解码。请等待 setOverlay() 并为远程图像配置 CORS。

调用方提供的 ImageBitmap 句柄仍归调用方所有。Worker 和主线程在渲染时对其进行 structured-clone，仅关闭渲染器拥有的克隆。构造时的后台或仅预取的覆盖层可在 initialize() 完成后关闭。如果构造覆盖层将调用方位图与 URL 或其他异步解析的源混合，则在覆盖层被替换或销毁前保持句柄打开；或者在初始化后在关闭之前调用并 await setOverlay()。

运行时后台和仅预取的覆盖层可在 updateAppearance()（或包含它的 batch()）返回后关闭，即使初始化仍在进行。对于混合或延迟的运行时覆盖层，应直接调用 setOverlay() 并在其 promise 完结前保持调用方句柄打开。URL 获取/解码的实现作为单独的按需代码块提供，并不属于初始浏览器运行时的一部分。

如果部分源失败，setOverlay() 会安装成功项并以 ChartOverlayError 拒绝。如果每个请求的项都失败，则先前渲染的覆盖层继续保留已安装状态。解析和渲染器传递失败也会到达 setOverlayErrorCallback() 和框架适配器的错误钩子。替换一个挂起的更新或销毁图表被视为常规取消：挂起的 promise 在不安装的情况下解决，并且不会报告覆盖层错误。

可访问性

Sixtyfold 仅在宿主未已提供回退语义时才添加回退语义。交互式图表会收到 role="application"、tabindex="0" 以及一个回退可访问名称。仅查看图表（interactive: false）会收到 role="img" 并且不会被添加到 Tab 顺序中。现有的 role、tabindex、aria-label 和 aria-labelledby 属性将被保留。

优先使用应用特定的名称和描述：

<canvas
  aria-label="Hourly load for feeder 12"
  aria-describedby="feeder-12-summary"
></canvas>
<p id="feeder-12-summary">Latest load is 73 kW; the daily peak was 96 kW.</p>

对于交互式图表，提供相邻的文本摘要或数据表替代，并使用 aria-describedby 引用它。不要将 role="img" 强制应用到键盘操作的图表上。颜色不得成为周边应用识别系列的唯一方式。

键盘平移、缩放、重置和选择取消通过隐藏的 polite 实时区域宣布。使用 keyboardAnnouncements 本地化这些消息，稍后使用 setKeyboardAnnouncements() 更新它们，或在周边应用提供等效反馈时禁用它们。可选的视口模板可以将可见的开始、结束和跨度作为完整数据范围的百分比添加。动画平移、缩放和重置消息会等待渲染器确认的视口稳定，因此中间动画帧不会被宣布。

Sixtyfold 不会通过 aria-live 报告每一次流式样本或重绘；高频率的通告会使屏幕阅读器无法使用。对于应用中有意义的事件（例如连接中断或阈值越过），应通过应用自行拥有且节流的实时区域来公开。