60FOLDCOMPONENTS

框架适配器

可在 React、Vue、Angular、Svelte 和 SolidJS 中使用 Sixtyfold Charts 的折线图和股票图。

Sixtyfold 的框架包是在相同 LineChart 与 StockChart 引擎周围的轻量生命周期适配器。它们不会复制渲染逻辑、重塑数据、添加运行时遥测或将每个图表拉入你的应用。

安装一个适配器及你使用的引擎。仅导入其 /line 或 /stock 入口点：

pnpm add @sixtyfold/react@next @sixtyfold/line@next
import { SixtyfoldLineChart } from "@sixtyfold/react/line";

将 react 替换为 vue、angular、svelte 或 solid。对于股票图表，安装 @sixtyfold/stock 并导入 /stock。图表引擎是适配器的可选对等依赖项，因此安装折线图不会同时安装股票图表。

共享适配器契约

所有适配器在组件挂载后创建图表，等待 initialize()，应用响应式输入，并在卸载时调用 destroy()。这也会终止图表 Worker 并释放观察者、监听器和大型缓冲区引用。在 SSR 期间组件仅输出其画布宿主；当服务器必须绘制图表像素时使用 @sixtyfold/ssr。

属性/输入折线类型股票类型行为
optionsLineChartOptionsStockChartOptions构建时快照。要替换适配器请重新挂载；如需实时视觉更改，请使用 appearance。
dataTimeSeriesData | MultiSeriesDataOHLCVData一次性可转移的大量数据，按对象标识响应式。务必使用新的对象来分配新的缓冲区。
dataUpdateOptionsLineDataUpdateOptions—控制动画线数据替换，包括 preservePreviousFrame。
appearanceDeepPartial<LineAppearanceOptions>DeepPartial<StockAppearanceOptions>在不重建图表或替换数据的情况下应用深度视觉补丁。
viewportPartial<Viewport>Partial<Viewport>响应式 X 范围。以图表的 X 单位提供 xMin、xMax 或两者。
viewportAnimatedbooleanboolean覆盖对应视口更新的动画。留空以继承图表选项。
statsIntervalMsnumbernumber最小遥测回调间隔（毫秒）；若无监听器则遥测保持禁用。
就绪回调/事件LineChartStockChart在 initialize() 解析并暴露命令式图表后触发一次。
error 回调/事件unknownunknown报告构建错误、渲染器初始化/运行时故障和覆盖层解析或交付失败。
stats 回调/事件LineChartStatsStockChartStats在 statsIntervalMs 报告渲染器和数据遥测。
series-visibility 回调/事件SeriesVisibilityChangeEvent—报告来自初始化、API 调用和交互图例的可见性更改。

每个适配器都会报告就绪、构建、渲染器与覆盖错误，以及渲染统计。线型适配器还报告 SeriesVisibilityChangeEvent。每个框架通过其常规 ref 或组件 API 暴露底层 LineChart 或 StockChart 实例，因此不常用的命令式操作仍然可用。

处理图表故障

适配器错误钩子接受 unknown，因为 JavaScript 构造错误不要求使用特定类。由 Sixtyfold 渲染器发出的失败是 ChartRendererError 实例。覆盖层解析或渲染器交付失败是 ChartOverlayError 实例。在读取结构化字段之前缩小该值的类型：

import {
  ChartOverlayError,
  ChartRendererError,
} from "@sixtyfold/line";

export function reportChartError(error: unknown) {
  if (error instanceof ChartRendererError) {
    console.error(error.phase, error.message);
    return;
  }
  if (error instanceof ChartOverlayError) {
    console.error("Overlay sources failed:", error.sources);
    return;
  }
  console.error(error);
}

在仅包含标准组件的应用中从 @sixtyfold/stock 使用相同导入。error.phase 要么是 "initialization" 要么是 "runtime"。渲染器失败会销毁该图表实例；如果应用选择恢复，则需重新挂载适配器。覆盖失败为非致命：成功项目仍保持安装；如果所有请求项目均失败，则保留此前渲染的覆盖层。

批量类型化数组传输到 Worker。将每个数据对象视为一次性使用：不要在原地修改它，并在每次更新时为其分配带有全新缓冲区的新对象。这可为数百万点级的数据集保留零拷贝路径。

React

import { useMemo, useRef } from "react";
import {
  SixtyfoldLineChart,
  type LineChartHandle,
} from "@sixtyfold/react/line";

export function Signals() {
  const chartRef = useRef<LineChartHandle>(null);
  const data = useMemo(() => ({
    x: new Float64Array([0, 1, 2, 3]),
    y: new Float64Array([3, 7, 4, 9]),
    length: 4,
  }), []);

  return (
    <SixtyfoldLineChart
      ref={chartRef}
      data={data}
      aria-label="Signal history"
      onError={console.error}
    />
  );
}

该组件接受普通的 canvas 属性。其 ref 暴露 ref.current?.chart。初始构造为微任务延后，因此 React Strict Mode 的开发生命周期探针无法将初始数据传递两次。

仅限 React 的表面类型描述
refRef<LineChartHandle | StockChartHandle>转发的句柄，其 chart 字段包含已挂载的命令式实例或 null。
本机画布属性CanvasHTMLAttributes<HTMLCanvasElement>传递给画布，但不包括 children。将它们用于 aria-label、类名、内联样式、测试和指针元数据。
onReady(chart) => void在初始化成功后调用一次。
onError(error: unknown) => void在构造、渲染器初始化/运行时或覆盖层解析/交付失败时调用。
onStats(stats) => void启用并接收渲染器遥测。
onSeriesVisibilityChange(event) => void仅限折线系列可见性回调。

Vue

<script setup lang="ts">
import { shallowRef } from "vue";
import { SixtyfoldLineChart } from "@sixtyfold/vue/line";

const data = shallowRef({
  x: new Float64Array([0, 1, 2, 3]),
  y: new Float64Array([3, 7, 4, 9]),
  length: 4,
});
</script>

<template>
  <SixtyfoldLineChart
    :data="data"
    aria-label="Signal history"
    @error="console.error"
  />
</template>

对批量数据请使用 shallowRef 或 markRaw，而非 Vue 的深层代理。组件会触发 ready、error 和 stats；折线图还会触发 seriesVisibilityChange。模板 ref 暴露其浅层 chart ref。

Vue 表面类型描述
shared props参见框架 prop 索引Vue props 使用与共享契约相同的名称和类型。
ready 事件LineChart | StockChart发出已初始化的命令式图表。
error 事件unknown发出构建、渲染器初始化/运行时或覆盖层解析/交付失败。
stats 事件LineChartStats | StockChartStats启用并发出遥测。
seriesVisibilityChange 事件SeriesVisibilityChangeEvent仅线可见性事件。
继承属性原生 Canvas 属性未识别的属性，例如 aria-label、class 和 style，会转发到 canvas。
模板 ref chartShallowRef<LineChart | StockChart | null>在不进行深度代理的情况下公开已挂载的命令式图表。

Angular

Angular 20–22 包使用独立组件和 Angular 包格式的次级入口点。

import { Component } from "@angular/core";
import { SixtyfoldLineChartComponent } from "@sixtyfold/angular/line";

@Component({
  standalone: true,
  imports: [SixtyfoldLineChartComponent],
  template: `
    <sixtyfold-line-chart
      [data]="data"
      ariaLabel="Signal history"
      (chartError)="reportError($event)"
    />
  `,
})
export class Signals {
  data = {
    x: new Float64Array([0, 1, 2, 3]),
    y: new Float64Array([3, 7, 4, 9]),
    length: 4,
  };

  reportError(error: unknown) {
    console.error(error);
  }
}

输入遵循共享表格并包含聚焦的无障碍字段和 canvasAttributes。输出为 chartReady、chartError 和 stats；折线组件还会触发 seriesVisibilityChange。组件引用公开其公共 chart。

Angular 的应用构建器不会转换包拥有的 Vite Worker URL。将应用使用的引擎添加到构建目标的 assets 数组中，位于 angular.json：

[
  { "glob": "**/*", "input": "node_modules/@sixtyfold/line/dist/assets", "output": "assets" },
  { "glob": "**/*", "input": "node_modules/@sixtyfold/stock/dist/assets", "output": "assets" }
]

图表构建由 isPlatformBrowser 保护，因此 Angular SSR 不会触及浏览器全局对象。

Angular 输入类型描述
optionsLineChartOptions | StockChartOptions构建时快照。
dataLineData | OHLCVData一次性可转移响应式数据集。
dataUpdateOptionsLineDataUpdateOptions仅限线条的替换动画选项。
appearanceDeepPartial<LineAppearanceOptions | StockAppearanceOptions>响应式视觉补丁。
viewportPartial<Viewport>响应式跨域补丁。
viewportAnimatedboolean | undefined视口输入的动画覆盖。
statsIntervalMsnumber | undefined当 stats 有订阅者时的最小遥测间隔。
canvasClassstring应用于内部画布的类。
ariaLabelstring可访问画布名称。
ariaDescribedBystring描述图表的相邻文本或表格替代项的 ID。
canvasRolestring明确的画布角色；通常让图表选择 application 或 img。
canvasTabIndexnumber明确的标签顺序；只读图表默认被省略。
canvasAttributesRecord<string, string | number | boolean | null | undefined>额外的画布属性，如测试钩子和元数据。类、样式、尺寸、role、标签顺序和聚焦的可访问性输入仍由其他部分管理。
Angular 输出有效负载描述
chartReadyLineChart | StockChart发出已初始化的命令式图表。
chartErrorunknown发出构建、渲染器初始化/运行时或覆盖层解析/交付失败。
statsLineChartStats | StockChartStats启用并发发渲染器遥测。
seriesVisibilityChangeSeriesVisibilityChangeEvent仅线条可见性输出。
public chartLineChart | StockChart | null在组件引用上公开的命令式实例。

Svelte

<script lang="ts">
  import LineChart from "@sixtyfold/svelte/line";

  const data = {
    x: new Float64Array([0, 1, 2, 3]),
    y: new Float64Array([3, 7, 4, 9]),
    length: 4,
  };
</script>

<LineChart
  {data}
  ariaLabel="Signal history"
  onError={console.error}
/>

chart 可绑定以便进行命令式访问。额外的 Svelte 属性为用于折线图的 onReady、onError、onStats、onSeriesVisibilityChange，以及 canvasClass、canvasStyle 和 ariaLabel。

Svelte 属性/绑定类型描述
共享属性参见框架属性索引使用共享的 options、data、appearance、视口、遥测和回调属性。
onReady(chart) => void接收已初始化的命令式图表。
onError(error: unknown) => void报告构建、渲染器初始化/运行时或覆盖层解析/交付失败。
onStats(stats) => void启用并接收遥测。
onSeriesVisibilityChange(event) => void仅线条可见性回调。
canvasClassstring应用于 canvas 的类。
canvasStylestring应用于 canvas 的 CSS 声明文本。
ariaLabelstring可访问的 canvas 名称。
bindable chartLineChart | StockChart | null挂载的命令式图表；在清理时重置为 null。

SolidJS

import { SixtyfoldLineChart } from "@sixtyfold/solid/line";

const data = {
  x: new Float64Array([0, 1, 2, 3]),
  y: new Float64Array([3, 7, 4, 9]),
  length: 4,
};

export function Signals() {
  return (
    <SixtyfoldLineChart
      data={data}
      canvasProps={{ "aria-label": "Signal history" }}
      chartRef={(chart) => console.log(chart)}
      onError={console.error}
    />
  );
}

chartRef 接收已挂载的图表，随后在清理时接收 null。canvasProps 传递原生画布属性。所有其他 props 遵循通用约定。

仅限 SolidJS 的 surface类型描述
chartRef(chart | null) => void接收已挂载的命令式图表，随后在清理时接收 null。
canvasPropsJSX.CanvasHTMLAttributes<HTMLCanvasElement>原生画布属性、可访问性元数据、class、style 和测试钩子。
onReady(chart) => void在初始化成功后调用。
onError(error: unknown) => void在构造、渲染器初始化/运行时或覆盖层解析/交付失败时调用。
onStats(stats) => void启用并接收遥测。
onSeriesVisibilityChange(event) => void仅限折线的可见性回调。

完整示例

公共仓库包含针对每个受支持框架的最小响应式应用。每个应用展示了重现折线图和股票图所需的包、数据结构、图表设置与清理。