ChartGPU API 完全参考create、setOption、appendData 核心接口逐一详解【免费下载链接】ChartGPUBeautiful, open source, WebGPU-based charting library项目地址: https://gitcode.com/gh_mirrors/ch/ChartGPUChartGPU 是一款基于 WebGPU 的高性能图表库本文以初学者视角拆解它最重要的三个核心接口create创建图表、setOption更新配置、appendData流式追加数据带你从零理解 ChartGPU 的 API 设计思路与调用方式。ChartGPU 用WebGPU而非 Canvas2D / WebGL 来渲染图表专门针对大规模数据、实时流式更新、多图表仪表盘和 3D 序列做了优化。它没有任何 npm 运行时依赖采用 MIT 协议可自由商用。 提示ChartGPU没有WebGL/Canvas 回退运行前需确保浏览器支持 WebGPU可用checkWebGPU()检测见 src/utils/checkWebGPU.ts。一、ChartGPU.create()—— 创建图表实例create是整个 API 的入口返回一个ChartGPUInstance实例。它的签名是const chart await ChartGPU.create(container, options, context?);三个参数各有分工container挂载容器ChartGPU 会在其中创建并管理一个 canvas。options图表配置对象包含series、theme、tooltip、dataZoom等完整类型见 src/config/types.ts。context?可选可共享的 WebGPU{ adapter, device, pipelineCache }用于多图表共用同一 GPU 设备。最简示例import { ChartGPU } from chartgpu/chartgpu; const el document.getElementById(chart)!; const chart await ChartGPU.create(el, { series: [{ type: line, data: { x: new Float64Array([0, 1, 2]), y: new Float64Array([1, 3, 2]), }, }], });两个容易踩坑的「创建期」选项antialias仅在create时生效决定 4× MSAA 管线与纹理管理器之后通过setOption修改无效需销毁重建。devicePixelRatio同样是创建期策略显式传入后会冻结整个生命周期省略则每次resize()重新读取实时 DPR。这两点都由 src/ChartGPU.ts 在构建时固化。二、setOption()—— 更新图表配置setOption(options)用于运行时更新配置并调度一次渲染。核心要点整体替换语义setOption是替换整个 options 对象而不是深度合并。要保留某字段请在每次更新时重新传入。序列身份复用若连续两次setOption传入相同的 series 元素对象只改坐标轴刻度之类ChartGPU 会直接复用之前的解析结果避免重新遍历每个序列若想改数据、颜色、可见性或样式请传入新的 series 元素对象或新的series数组。chart.setOption({ theme: dark, series: [ { type: line, data: newData, color: #38bdf8 }, // 新的 data 数组才会被识别 ], });⚠️ 注意原地修改series[i].data newData这类「稳定对象上的属性变更」不会被热路径检测到推荐始终传入新数组。数据上传时机setOption本身并不立刻上传数据。真正的数据打包、比例尺与边界推导发生在渲染协调器的render()阶段见 src/core/createRenderCoordinator.ts这是一种「按需渲染」设计能避免无谓的 GPU 写入。三、appendData()—— 流式追加数据appendData(seriesIndex, newPoints, options?)是实时数据流的推荐方式性能远优于每帧调用一次完整的setOption。const x new Float64Array([3, 4, 5]); const y new Float64Array([2.5, 2.1, 2.8]); chart.appendData(0, { x, y }, { maxPoints: 50_000 });支持的数据格式为减少逐点对象分配appendData支持多种列式/交错布局格式说明DataPoint[][x, y]元组或{ x, y }对象数组XYArraysData独立的x/y数组InterleavedXYDataFloat32Array等按[x0,y0,x1,y1,...]交错OHLCDataPoint[]蜡烛图 / ohlc 序列专用maxPoints环形缓冲FIFOoptions.maxPoints是按次生效的固定容量环形并非持久序列状态若单批数据 ≥maxPoints仅保留该批次尾部严格替换丢弃旧点。否则填满到maxPoints后每次溢出覆盖最旧槽位——GPU 采用模运算环形写入复杂度为 O(append)无需重写整个保留窗口峰值保留长度恒为maxPoints。// 高频率流式推荐固定容量环形 chart.appendData(0, { x, y }, { maxPoints: 50_000 });设备存储上限与自动窗口当无限追加导致序列缓冲区超过min(maxBufferSize, maxStorageBufferBindingSize)Chrome/Metal 上常为128 MiB ≈ 1670 万xy 点时ChartGPU 会自动把 x 域窗口化到该点数预算保持 GPU 驻留数据与坐标轴同步。想要更小的滑动窗口请显式传入{ maxPoints }。appendData不适用于heatmap/surface3d/pie它们各有专用更新接口见下文「其他关键方法」。四、其他关键实例方法除三大核心接口外ChartGPUInstance还暴露了一批实用方法生命周期resize()适配容器变化dispose()释放 GPU 资源并自动 flush 待提交的批量提交。交互事件on(...)/off(...)订阅click、crosshairMove、zoomRangeChange、dataAppend等事件见 docs/api/interaction.md。命中测试hitTest(e)返回指针坐标与命中的图表元素支持右键/上下文菜单场景。缩放控制getZoomRange()/setZoomRange(start, end)以百分比空间读写缩放窗口。3D 专用setCamera()/getCamera()/resetCamera()仅cartesian3d以及updateSurface3D()、updateHeatmap()等部分更新接口。多图表共享 GPU 设备页面上有 3 个及以上图表时推荐创建单一adapter/device/pipelineCache并注入每次create让多个图表复用同一 GPU 设备图表dispose()时不会销毁共享设备import { createPipelineCache, connectCharts } from chartgpu/chartgpu; const pipelineCache createPipelineCache(device); const chartA await ChartGPU.create(a, optsA, { adapter, device, pipelineCache }); const chartB await ChartGPU.create(b, optsB, { adapter, device, pipelineCache }); // 同步十字线/tooltip可选同步缩放 const disconnect connectCharts([chartA, chartB], { syncZoom: true });缓存与共享设备的完整说明见 docs/api/chart.md。五、速查与最佳实践场景推荐接口首次建图ChartGPU.create(container, options, context?)整体换主题/坐标轴setOption(完整 options)高频流式追加appendData(i, points, { maxPoints })热力图/3D 面局部更新updateHeatmap/updateSurface3D容器尺寸变化resize()销毁并释放资源dispose()✅上手建议用create建图注意antialias、devicePixelRatio只能在创建时设定。更新配置一律传新的series 对象/数组避免原地修改导致的静默失效。实时数据优先appendDatamaxPoints环形而非整帧setOption。多图表共享一个 GPU 设备与pipelineCache并用connectCharts同步交互。完整 API 索引可从 docs/api/README.md 入手3D 系列参考 docs/api/3d.md选项细节见 docs/api/options.md。掌握create、setOption、appendData这三个核心接口你就已经能覆盖 ChartGPU 绝大多数 2D 场景配合共享设备与 3D 扩展即可构建出流畅、可商用的 WebGPU 数据可视化应用。【免费下载链接】ChartGPUBeautiful, open source, WebGPU-based charting library项目地址: https://gitcode.com/gh_mirrors/ch/ChartGPU创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考