Vela

海内存知已，天涯若比邻。——王勃

Vela：为 Web 而生的可扩展金融图表核心

项目地址：https://github.com/LuxAlgo/Vela

金融图表从来不只是几根蜡烛和几条均线。

当一张图表真正进入产品，它往往需要承载行情数据、实时更新、不同周期、指标系统、用户绘图、主题样式、多个图表单元、状态恢复、键盘操作、数据源切换，以及持续演进的自定义能力。

Vela 试图把这些需求收拢为一套面向 Web 的金融图表基础设施。

它提供快速、可扩展的金融图表能力，采用原生 WebGL2 渲染，并提供 Canvas 2D 后备方案。它的图表核心保持无界面状态，开发者可以完全通过代码驱动图表；如果希望快速得到完整的图表应用，也可以直接使用 workspace。

Vela 的设计并不要求开发者在“灵活”与“完整”之间二选一。

需要完全掌控时，可以直接使用 headless core。

需要一套具备常用交互能力的图表界面时，可以使用 workspace。

需要接入自定义数据、脚本语言、图表类型或渲染层时，可以通过公开接口进行扩展。

一张图表，不必被界面结构绑死

Vela 的一个核心特点是 headless。

它将图表本身保持为无界面核心，这意味着图表的数据模型、引擎、绘图能力、数据提供方与渲染能力可以通过代码进行控制。

开发者不需要被预设 UI 限制，也不必为了更换某个部分而重写整套图表系统。

README 对这一思路描述得很清楚：数据提供方、脚本引擎与渲染器都位于公开端口之后，每一层都可以被替换，而不必触碰其余部分。

这让 Vela 更像一个可组合的图表底座。

你可以从外部提供自己的 K 线数据。

可以注册不同的数据源。

可以接入脚本引擎。

可以构建新的图表形态。

也可以添加直接参与每帧绘制的渲染层。

图表不再只是一个固定组件，而成为可以围绕产品需求持续组装的系统。

安装，从一个包开始

安装 Vela 的方式很直接：

npm install @luxalgo/vela

安装后，可以选择两条使用路径。

第一条是 workspace。

它适合希望快速拥有完整图表应用的场景。

第二条是 headless core。

它适合需要自行组织页面、控件、交互和产品结构的场景。

两种方式共享 Vela 的图表能力，只是在应用层的组织程度上有所不同。

Workspace：一行初始化，得到完整图表应用

对于希望快速构建完整图表体验的场景，Vela 提供了 VelaWorkspace。

它可以创建单张图表，也可以通过布局配置创建多图表网格。Workspace 还包含共享顶部栏、状态栏、底部栏、对象树、快捷键操作、命名单元格、同步组以及统一的持久化状态文档。

最基础的使用方式如下：

import { VelaWorkspace } from '@luxalgo/vela/workspace';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';

const chart = new VelaWorkspace('#chart', {
  layout: false,
  symbol: 'BTCUSDT',
  timeframe: '60',
  live: true,
  theme: 'dark',
  providers: {
    binance: () => new BinanceProvider(),
  },
  persist: true,
});

这段代码中，layout: false 表示创建单张图表。

如果需要多图表网格，可以将布局设置为相应值，例如：

layout: '2h'

Workspace 的共享顶部栏可以处理交易标的、周期、样式和指标等入口。

状态栏、标的水印与底部栏也已经包含在完整应用结构中。底部栏提供范围、时钟与时区相关能力。

对象树则为图表对象提供了可查看的组织入口。

在操作方式上，Workspace 强调键盘优先。

输入一个字母或数字 0 可以进行标的搜索。

输入数字 1 到 9 可以进入周期输入。

输入 ? 可以打开快捷键面板。

同时，Workspace 也支持命名单元格与同步组，适合由多个图表构成的工作区。

持久化状态，让图表重新打开时仍记得自己

金融图表经常会积累许多用户状态。

当前查看的市场。

选择的样式。

所在时区。

添加过的指标。

画过的趋势线、水平线与其他绘图对象。

如果这些状态在刷新页面后全部消失，图表就会像每天重新归零的工作台。

Vela Workspace 通过 persist: true 提供状态持久化能力。

const chart = new VelaWorkspace('#chart', {
  symbol: 'BTCUSDT',
  timeframe: '60',
  persist: true,
});

启用后，市场、样式、时区、绘图与指标可以从 localStorage 恢复。

这让图表不只是一次性的渲染结果，也能成为带有连续工作状态的界面。

Headless Core：让图表彻底由代码驱动

如果产品拥有自己的界面体系，或者开发者希望对图表周边交互进行完全控制，可以直接使用 Vela 的核心包。

import { Vela } from '@luxalgo/vela';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';

const chart = new Vela('#chart', {
  symbol: 'binance:BTCUSDT',
  timeframe: '60',
  live: true,
});

chart.data.registerProvider('binance', new BinanceProvider());

await chart.ready();

这里，图表创建、数据提供方注册和就绪等待都由代码完成。

这条路径不会强制引入完整 workspace 结构。开发者可以按照自己的产品设计组合控件、导航、指标面板、订单信息、交易终端或其他界面模块。

Vela 的图表核心保持 headless，并不意味着它缺少渲染能力。

相反，它拥有原生渲染器。headless 描述的是图表不强制绑定某套应用 UI，而不是图表不负责图形呈现。

没有网络，也能绘制图表

Vela 不要求一定使用内置数据提供方。

如果不需要网络，也不想注册任何 Provider，可以通过 data 选项直接传入自己的 bars。

这意味着图表可以完全离线运行。

对于回放数据、内部数据源、本地文件、测试数据或独立产品服务来说，这种方式很重要。图表的数据来源不必被绑定到某个远程平台，也不必局限于预置 Provider。

Vela 提供 Binance、Coinbase 与 Hyperliquid 等数据提供方，并允许开发者自行供应数据。

数据层是可替换的。

图表核心负责组织和呈现。

数据从哪里来，则可以由应用自己决定。

浏览器脚本标签也可以直接使用

除了模块化安装方式，Vela 还提供适合 script 标签使用的浏览器构建产物。

其中包括：

dist/vela.global.js

以及：

dist/vela.global.min.js

前者是可读的开发版本。

后者是压缩后的生产版本。

两者都会将库的公开 API 挂载到：

window.Vela

并且包含打包后的 Provider。

这种形式让 Vela 不只适用于现代构建工具链，也能被放入更直接的浏览器脚本使用方式中。

原生 WebGL2 渲染与 Canvas 2D 后备方案

图表渲染是金融可视化体验的基础。

Vela 使用原生 WebGL2 渲染，并提供 Canvas 2D 后备方案。

这意味着图表核心拥有自己的渲染路径，而不是依赖外部图表绘制组件来完成画面呈现。

对使用者来说，最直接的结果是 Vela 以金融图表为中心组织自己的渲染系统。

对扩展者来说，公开的渲染层接口也让图表画面不必止步于默认内容。

自定义图层可以被注册，并随着图表的每一帧绘制。

70 多种内置指标，覆盖常见分析维度

Vela 内置 70 多种研究指标。

这些指标覆盖多个类别：

• 移动平均线
• 通道与带状指标
• 动量振荡器
• 趋势指标
• 波动率指标
• 成交量研究指标
• 锚定价格叠加指标
• VWAP
• SuperTrend
• Pivot Points

这些内置指标直接基于图表自身的 bars 进行计算，不需要脚本引擎。

每一个指标都会拥有图例行、设置对话框，并能够在页面重新加载后保持状态。

成交量和可见范围成交量分布也作为图表能力的一部分存在。

这意味着指标并不只是被绘制出来的一组数据线。

它们可以进入图表应用的交互结构，拥有设置入口、可见状态与持久化行为。

脚本引擎不内置，但始终可接入

Vela 自身不附带默认脚本引擎。

这是其架构中的一个明确选择。

README 中说明，自定义脚本通过可插拔引擎运行。开发者可以安装希望使用的语言扩展，也可以基于公开的 ScriptingEngine 端口实现自己的引擎。

Pine Script® 可以通过单独的扩展包接入：

npm i @luxalgo/vela-pinets pinets

随后注册 Pine 引擎：

import { PineEngine } from '@luxalgo/vela-pinets';

chart.registerEngine('pine', new PineEngine());

chart.addIndicator(`//@version=6
indicator("EMA 20", overlay=true)
plot(ta.ema(close, 20), color=color.orange, linewidth=2)`);

Vela 本体采用 Apache License 2.0，并不包含 Pine 代码。

Pine Script® 扩展包采用单独许可证，因为其执行的 PineTS 运行时采用 AGPL-3.0。

这种拆分与 Vela 的整体架构方向一致。

图表核心保持独立。

脚本语言作为可选扩展接入。

不同能力层之间保持可替换关系。

执行指标脚本，也读取运行中的状态

Vela 提供 chart.runIndicator(source)，用于安全地执行并注入指标脚本。

这个入口会返回结构化错误，并避免留下无效图例行。

对于已经运行的脚本，还可以通过 handle.context() 读取其执行上下文。

const context = handle.context();

读取结果是只读快照，并且适用于 worker 安全场景。

其中还包括脚本的返回值。

这让脚本不只是单向向图表写入结果。运行中的脚本状态也可以被外部读取，从而参与更复杂的应用逻辑。

指标清单，让 Workspace 的指标来源更加灵活

Workspace 接受指标清单。

这个清单可以是内联 JSON。

可以是返回清单的 URL。

也可以是异步加载函数。

new VelaWorkspace('#chart', {
  engines: {
    pine: () => new PineEngine(),
  },
  indicators: '/indicators.json',
});

也可以将指标直接写为内联定义。

new VelaWorkspace('#chart', {
  indicators: [
    {
      name: 'My Indicator',
      script: '...',
      language: 'pine',
      enabled: true,
    },
  ],
});

这种机制让 Workspace 不必只依赖固定的指标列表。

指标可以随应用配置变化。

可以从远程来源加载。

可以随着不同产品、不同用户组或不同工作区组织方式而改变。

插件 SDK：不需要 Fork，也能创造新的图表类型

金融图表经常需要超出默认蜡烛图、折线图或基础形态的表现方式。

有时需要新的价格样式。

有时需要根据数据转换生成新的图形结构。

有时需要在图表数据上方或下方绘制自定义画布内容。

Vela 提供 Plugin SDK，让这些扩展不必通过 Fork 主项目完成。

注册新的图表类型：

import { registerChartType, registerRendererLayer } from '@luxalgo/vela/plugin';

registerChartType({
  id: 'renko-like',
  label: 'Renko-like',
  barTransform: {
    full: (bars) => transformAll(bars),
    next: (bar) => transformOne(bar),
  },
});

这段定义中，barTransform.full 用于处理完整 bars 集合。

barTransform.next 用于处理新到达的单根 bar。

随后，可以注册自定义渲染层：

registerRendererLayer({
  id: 'renko-like',
  placement: 'above-data',
  create: () => ({
    mount(canvas) {
      /* keep it */
    },
    render({ bars, data, coords, scale, bounds }) {
      /* paint */
    },
  }),
});

渲染层会在每一帧随图表一起绘制。

其 id 同时也是数据通道标识。

当图表类型注册完成后，它会自动出现在 Workspace 的样式下拉菜单中。

如果图表类型提供 dataEngine，对应数据会被推送到该图层的数据通道中，不需要额外连线。

这是一种很有层次的扩展方式。

开发者可以定义数据如何变化。

可以定义画面如何绘制。

而 Workspace 能够自动将图表类型呈现在用户可以选择的样式入口中。

一套由多层构成的图表系统

Vela 的包结构体现了它对分层的强调。

@luxalgo/vela

这是 headless chart 核心。

它包含数据模型、引擎、绘图、Provider 与原生渲染器。

@luxalgo/vela/workspace

这是完整图表应用层。

它可以创建单图或多图网格，提供共享顶部栏、状态栏、底部栏、对象树、快捷键操作、同步组和统一状态文档。

@luxalgo/vela/ui

这是 Workspace 使用的组件工具包。

它包含设计令牌、覆盖层界面能力、表单原语与 KeymapManager。

@luxalgo/vela/plugin

这是扩展 SDK。

它面向图表类型、渲染层与原生指标扩展。

@luxalgo/vela/providers/*

这是数据提供方集合。

README 中列出了 Binance、Coinbase 与 Hyperliquid Provider，并允许开发者注册自己的 Provider。

这样的结构不是简单把功能拆成多个包。

它表达的是一组可以独立更换的层。

数据层可以替换。

脚本层可以替换。

渲染层可以替换。

而核心仍然负责维持图表系统的统一组织。

架构记录，保留每一项重要选择的原因

Vela 在仓库中维护 Architecture Decision Records。

这些 ADR 用于记录库为什么以当前方式构建。

每份 ADR 聚焦一项架构决策，记录推动决策的因素、最终选择、接受的权衡，以及这项决定所形成的不变量。

README 中列出的架构方向包括：

• 中性模型作为跨层交换媒介
• 核心拥有市场数据
• 不提供默认脚本引擎
• 通过导入访问控制保证分层
• 核心拥有用户绘图
• Workspace 组合图表，界面元素是活动单元格的投影

这些记录说明，Vela 并不把可替换层当作一句口号。

它试图持续维护核心与数据提供方、脚本引擎、渲染器之间的边界。

对于一个需要不断扩展的图表库来说，边界是否清晰，会直接影响未来添加新能力时是否会牵动整个系统。

开发与测试

如果希望从源码运行或参与开发，可以执行：

npm install
npm run playground
npm test
npm run build

其中：

npm run playground

会启动 Vite playground，地址为：

http://localhost:5190

测试使用 Vitest。

构建通过 tsup 输出到 dist 目录。

这条开发路径保持了清晰的节奏：安装依赖、启动演示环境、运行测试、构建产物。

Apache License 2.0 与署名水印

Vela 采用 Apache License 2.0。

同时，项目的 NOTICE 文件增加了署名要求。根据 README 的说明，重新分发时需要包含该 NOTICE。

每张图表默认会渲染一个小型 Vela™ 署名水印。

开发者可以重新设计它的样式或位置，以适配自己的界面。

如果希望关闭图表水印，可以使用：

chart.renderer.set('attribution', false);

但关闭后，需要在同一个页面或屏幕的其他可见位置提供等价署名，也就是可见的 Vela™ 名称，并链接到项目页面。

README 明确指出，不能在没有提供等价可见署名的前提下移除、隐藏或遮挡这一署名。

这让许可要求成为产品界面设计的一部分，而不只是放在代码仓库角落的一段文本。

图表不是一个孤立组件，而是一套可演化的能力层

一张金融图表真正复杂的地方，不在于能否画出价格。

而在于它是否能持续容纳变化。

新的数据源。

新的指标。

新的脚本语言。

新的图表类型。

新的渲染层。

新的工作区布局。

新的交互方式。

新的持久化状态。

Vela 的设计正是围绕这种变化展开。

它提供无界面核心，让代码能够完全控制图表。

它提供 Workspace，让完整图表应用能够快速启动。

它提供原生 WebGL2 渲染与 Canvas 2D 后备。

它提供数据 Provider、内置指标、脚本引擎接口、插件 SDK 和浏览器构建产物。

它也通过架构记录，持续强调核心、数据、脚本与渲染之间应当保持的边界。

对于需要在 Web 中构建金融图表体验的开发者来说，Vela 不只是一个绘图工具。

它更像是一套能够承接产品化需求、允许持续替换与扩展的图表系统。