Lynx

【注意】Lynx 开源版本暂时不提供 canvas 画布功能，所以暂时不支持 vchart 的渲染，后续版本将会支持，敬请期待，更多功能请查看 lynx 官网

Lynx 是字节开源的高性能跨端框架，基于 Web 技术栈快速构建 Native 视图，Lynx 于 2025-03-05 正式开源；VChart 基于 Lynx 字节内部版本提供了该框架的图表渲染能力支持。

如何获取 VChart

npm 包

你可以直接在 lynx 项目中安装 vchart 依赖包：@visactor/vchart。

手动引入脚本

也可以手动引用 VChart 的 umd 打包产物，你可以通过如下渠道获取：

直接仓库中获取 packages/block-vchart/block/vchart/index.js ，每次发包我们都会进行更新
从如下免费的 CDN 中获取

<!-- unpkg -->
<script src="https://unpkg.com/@visactor/vchart/build/index.min.js"></script>

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/@visactor/vchart/build/index.min.js"></script>

如何使用

下面我们从 js、ttml、ttss 三部分介绍下如何在飞书小组件上使用 VChart。

index.ttml

需要声明三个 canvas，并且注意声明的顺序

bar_hidden_canvas 隐藏的 canvas，在第一个声明，用于内部的一些拾取逻辑
bar_draw_canvas 绘制 canvas，第二个声明
bar_tooltip_canvas 用于绘制 tooltip 的 canvas，跨端环境的 tooltip 使用 canvas 绘制。

<view class="vchart">
  <!-- canvas顺序很重要 -->
  <canvas
    name="bar_hidden_canvas"
    id="bar_hidden_canvas"
    user-interaction-enabled="{{false}}"
    class="cs-canvas cs-canvas-hidden"
  >
  </canvas>
  <canvas
    class="cs-canvas"
    bindtouchstart="bindChartEvent"
    bindtouchmove="bindChartEvent"
    bindtouchend="bindChartEvent"
    name="bar_draw_canvas"
    id="bar_draw_canvas"
  >
  </canvas>
  <canvas
    name="bar_tooltip_canvas"
    id="bar_tooltip_canvas"
    user-interaction-enabled="{{false}}"
    class="cs-tooltip-canvas"
  >
  </canvas>
</view>

index.js

在该文件中创建 VChart 实例，因为 VChart 内部对 lynx 环境进行了兼容，所以在使用上，基本于 PC 端无异，只需要注意两点：

需要在 VChart 的构造函数中声明必要的环境参数

const chartInstance = new VChart(spec, {
  mode: 'lynx', //  Tip: 跨端环境需要手动传入 mode
  // 跨端参数
  modeParams: {
    domref: domRef, // 图表绘制的 canvas 节点
    force: true, // 是否强制使用 canvas 绘制
    canvasIdLists: [`${item.id}_draw_canvas`, `${item.id}_tooltip_canvas`, `${item.id}_hidden_canvas`], // canvasId 列表
    tooltipCanvasId: `${item.id}_tooltip_canvas`, // tooltip canvasId
    freeCanvasIdx: 1 // 自由 canvas 索引
  },
  dpr: pixelRatio, // Tip: 跨端环境需要手动传入 dpr
  renderCanvas: `${item.id}_draw_canvas` // 声明用于绘制的 canvasId
});

在事件上，需要用户自己在 canvas（用于绘制的 canvas）元素上绑定事件，然后在事件监听函数中手动得分发事件来触发 VChart 内部的事件。

bindChartEvent(event) {
  const id = event.target.id.split("_")[0];
  const targetChart = this.data.chartList.find(x => x.id === id);
  const chartInstance = targetChart?.chart;
  if (chartInstance) {
    event.target = chartInstance.getCanvas(); // Tip: 必须设置
    chartInstance.getStage().window.dispatchEvent(event);
  }
},

下面是 index.js 相关的完成代码：

import barSpec from './data/bar';
import VChart, { registerLynxEnv } from '@visactor/vchart';
import mapJson from './data/map-data-china';

Card({
  data: {
    chartList: [
      {
        id: 'bar',
        spec: barSpec,
        chart: undefined
      }
    ]
  },
  onLoad: function () {
    // 如果需要使用地图，需要先注册地图
    VChart.registerMap('china', mapJson, {
      type: 'geojson'
    });
    this.init();
  },

  init() {
    registerLynxEnv();
    this.data.chartList.forEach(item => {
      this.createSelectorQuery()
        .select(`#${item.id}_draw_canvas`)
        .invoke({
          method: 'boundingClientRect',
          success: domRef => {
            if (!domRef) {
              console.error(`未找到 #${item.id} 画布`);
              return;
            }
            domRef.id = item.id;
            const pixelRatio = SystemInfo.pixelRatio;

            const chartInstance = new VChart(item.spec, {
              mode: 'lynx', //  Tip: 跨端环境需要手动传入 mode
              // 跨端参数
              modeParams: {
                domref: domRef, // 图表绘制的 canvas 节点
                force: true, // 是否强制使用 canvas 绘制
                canvasIdLists: [`${item.id}_draw_canvas`, `${item.id}_tooltip_canvas`, `${item.id}_hidden_canvas`], // canvasId 列表
                tooltipCanvasId: `${item.id}_tooltip_canvas`, // tooltip canvasId
                freeCanvasIdx: 1 // 自由 canvas 索引
              },
              dpr: pixelRatio, // Tip: 跨端环境需要手动传入 dpr
              renderCanvas: `${item.id}_draw_canvas` // 声明用于绘制的 canvasId
            });
            item.chart = chartInstance;

            if (item.events) {
              item.events.forEach(event => {
                chartInstance.on(event.type, { source: event.element }, event.handler);
              });
            }
            chartInstance.renderSync();
          },
          fail: res => {
            console.log('res:', res);
          }
        })
        .exec();
    });
  },

  bindChartEvent(event) {
    const id = event.target.id.split('_')[0];
    const targetChart = this.data.chartList.find(x => x.id === id);
    const chartInstance = targetChart?.chart;
    if (chartInstance) {
      event.target = chartInstance.getCanvas(); // Tip: 必须设置
      chartInstance.getStage().window.dispatchEvent(event);
    }
  }
});

按需加载

lynx-vchart 本身代码都支持按需加载，当需要 VChart 按需加载的时候，有两种办法：

使用 <VChartSimple /> 标签，实现自定义的按需加载

<VChartSimple />组件和<VChart />组件使用方法基本完全相同，唯一差异点为，需要用户从 @viasctor/vchart/esm/core 引用 VChart 构造类，根据本文描述，注册需要的图表和组件，并传入给 <VChartSimple />;

使用语义化标签，所有的语义化标签默认支持按需加载，其中各种语义化标签默认注册的内容如下：

自0.0.12版本开始支持

图表	分类	额外注册的组件
`<LineChart/>`	直角坐标系图表	`registerLabel`
`<AreaChart/>`	直角坐标系图表	`registerLabel`, `registerTotalLabel`
`<BarChart/>`	直角坐标系图表	`registerLabel`, `registerTotalLabel`
`<Bar3dChart/>`	直角坐标系图表	`registerLabel`, `registerTotalLabel`
`<BoxPlotChart/>`	直角坐标系图表	`registerLabel`,
`<HeatmapChart/>`	直角坐标系图表	`registerLabel`
`<Histogram3dChart/>`	直角坐标系图表	`registerLabel`
`<HistogramChart/>`	直角坐标系图表	`registerLabel`
`<LinearProgressChart/>`	直角坐标系图表	`registerLabel`
`<RangeColumnChart/>`	直角坐标系图表	`registerLabel`
`<RangeColumn3dChart/>`	直角坐标系图表	`registerLabel`
`<ScatterChart/>`	直角坐标系图表	`registerLabel`
`<SequenceChart/>`	直角坐标系图表	`registerLabel`
`<WaterfallChart/>`	直角坐标系图表	`registerLabel`, `registerTotalLabel`
`<RadarChart/>`	极坐标系图表	`registerLabel`
`<RoseChart/>`	极坐标系图表	`registerLabel`
`<CircularProgressChart/>`	极坐标系图表	`registerLabel`, `registerIndicator`
`<Pie3dChart/>`	通用图表	`registerLabel`, `registerIndicator`
`<PieChart/>`	通用图表	`registerLabel`, `registerIndicator`
`<CirclePackingChart/>`	通用图表	无
`<FunnelChart/>`	通用图表	`registerLabel`
`<Funnel3dChart/>`	通用图表	`registerLabel`
`<GaugeChart/>`	通用图表	无
`<MapChart/>`	通用图表	`registerLabel`
`<SankeyChart/>`	通用图表	无
`<SunburstChart/>`	通用图表	无
`<TreemapChart/>`	通用图表	无
`<VennChart/>`	通用图表	无
`<WordCloud3dChart/>`	通用图表	无
`<WordCloudChart/>`	通用图表	无
`<LiquidChart/>`	通用图表	`registerIndicator`

其中，直角坐标系图表默认注册组件如下：

registerCartesianLinearAxis
registerCartesianBandAxis
registerCartesianTimeAxis
registerCartesianLogAxis
registerCartesianCrossHair
registerBrush
registerContinuousLegend
registerDataZoom
registerDiscreteLegend
registerCustomMark
registerAllMarks
registerMarkArea
registerMarkLine
registerMarkPoint
registerScrollBar
registerTitle
registerTooltip
registerCanvasTooltipHandler

极坐标系图表默认注册组件如下：

registerPolarLinearAxis
registerPolarBandAxis
registerPolarCrossHair
registerBrush
registerContinuousLegend
registerDataZoom
registerDiscreteLegend
registerCustomMark
registerAllMarks
registerScrollBar
registerTitle
registerTooltip
registerCanvasTooltipHandler

通用图表默认注册组件如下：

registerDiscreteLegend
registerContinuousLegend
registerCustomMark
registerAllMarks
registerTitle
registerTooltip
registerCanvasTooltipHandler

使用语义化标签的时候，如果用到其他没有默认加载的组件，只需要注册未加载的组件即可；

【注意】：如果使用 lynx 出现报错类似“No matching export in ...”，请升级 lynx 的版本，或者配置 resolve.enableINodeCache 为 false

VChart 按需引用参考相关文档