60FOLDCOMPONENTS

框架适配器

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

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

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

pnpm add @sixtyfold/react@1 @sixtyfold/line@1
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最小遥测回调间隔（毫秒）；若无监听器则遥测保持禁用。
readiness callback/eventLineChartStockChart在初始化及首次成功的数据、外观和视口属性批处理之后，每个图表实例触发一次；不等待绘制帧。
error callback/eventunknownunknown报告构造和响应式属性安装错误、渲染器初始化/运行时故障，以及覆盖层解析或交付失败。
stats callback/eventLineChartStatsStockChartStats在 statsIntervalMs 报告渲染器和数据遥测。
series-visibility callback/eventSeriesVisibilityChangeEvent—报告来自初始化、API 调用和交互式图例的可见性更改。

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

就绪（Readiness）表示初始 props 已被接受，并不意味着其第一帧 Canvas 已被绘制。ready 回调中以命令式方式所做的更改不会被延迟的初始 prop 批次覆盖。

处理图表故障

适配器错误钩子接受 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);
}

在仅库存（stock-only）应用中从 @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 19.2+ Activity 可以在不重新创建渲染器或重新传输数据的情况下隐藏和显示图表。属性安装以及就绪/错误通知会等待到显示时才进行；统计和序列可见性回调在隐藏时被断开。保留的 Worker 和缓冲区会在组件实际卸载时释放，包括在隐藏状态下的卸载。

React 在隐藏时会断开转发的 ref。先前捕获的句柄在显示前也会从 .chart 返回 null。React 18 和 React 19.2 之前的 React 19 版本通过被动清理在卸载时销毁图表，这包括被重新挂起的 Suspense 边界隐藏的图表。

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。

统计收集遵循响应式监听器。唯一的 @stats.once 监听器在首次事件后禁用收集；普通的 @stats 监听器则保持启用。已消费的 .once 监听器在该组件生命周期内保持已消费状态。

Vue 表面类型描述
共享属性参见框架属性索引Vue 属性使用与共享契约相同的名称和类型。
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。

仅在存在活跃订阅者能够接收 stats 输出时才启用统计收集。包括 take(1) 在内的最后一个订阅者退订后即停止，或在该输出完成、出现错误或被关闭时停止。

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>响应式 X 轴域补丁。
viewportAnimatedboolean | undefined视口输入的动画覆盖。
statsIntervalMsnumber | undefined当 stats 有订阅者时的最小遥测间隔。
canvasClassstring应用于内部画布的类。
ariaLabelstring可访问的画布名称。
ariaDescribedBystring描述图表的相邻文本或表格替代项的 ID。
canvasRolestring显式的 canvas 角色；通常让图表选择 application 或 img。
canvasTabIndexnumber显式的标签顺序；仅供查看的图表默认被省略。
canvasAttributesRecord<string, string | number | boolean | null | undefined>额外的 canvas 属性，例如测试钩子和元数据。类、样式、大小、角色、标签顺序以及焦点可访问性输入由其他机制单独管理。
Angular 输出有效载荷描述
chartReadyLineChart | StockChart在初始化和首次成功的响应式属性批次之后发出图表。
chartErrorunknown发出构造、响应式属性设置、渲染器初始化/运行时或覆盖解析/交付失败的事件。
statsLineChartStats | StockChartStats启用并发出渲染器遥测。
seriesVisibilityChangeSeriesVisibilityChangeEvent仅限线条可见性输出。
公开 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 prop/binding类型描述
共享 props参见框架 prop 索引使用共享的 options、data、appearance、视口、遥测和回调 props。
onReady(chart) => void在初始化且首次成功的响应式 prop 批次之后接收图表。
onError(error: unknown) => void报告构建、响应式 prop 安装、渲染器初始化/运行时或覆盖解析/传递失败。
onStats(stats) => void启用并接收遥测。
onSeriesVisibilityChange(event) => void仅折线可见性回调。
canvasClassstring应用于画布的类。
canvasStylestring应用于画布的 CSS 声明文本。
ariaLabelstring可访问的画布名称。
可绑定 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 传递原生画布属性。所有其他属性遵循共享契约。

仅限 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仅针对折线的可见性回调。

完整示例

公共代码库包含每个受支持框架的最小响应式应用示例。每个示例展示了所需的包、数据结构、图表设置以及清理步骤，以重现折线图和股票图两种图表。