From 6ad0a5f14cf5c35f6e3daa5fc19a652389f3e28e Mon Sep 17 00:00:00 2001 From: xile611 Date: Mon, 14 Sep 2026 17:40:58 +0800 Subject: [PATCH 1/3] docs: clarify Lynx integration scope and requirements --- .../lynx.md | 285 ++---------------- .../react-lynx.md | 6 +- .../lynx.md | 285 ++---------------- .../react-lynx.md | 6 +- 4 files changed, 64 insertions(+), 518 deletions(-) diff --git a/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md b/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md index 8dc2175950..a18ef7a8ac 100644 --- a/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md +++ b/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md @@ -1,284 +1,55 @@ # Lynx -**[Note] The open-source version of Lynx currently does not provide canvas functionality, so VChart rendering is not supported at this time. Future versions will support this feature. Stay tuned, [see the Lynx official website for more features](https://lynxjs.org/)** +Lynx is a high-performance cross-platform framework open-sourced by ByteDance for building native views with web technologies. VChart provides a rendering adapter for ByteDance's internal Lynx environment. -Lynx is a high-performance cross-platform framework open-sourced by ByteDance, enabling the rapid construction of Native views based on the Web technology stack. Lynx was officially open-sourced on March 5, 2025. VChart provides chart rendering capabilities for this framework based on the internal version of Lynx at ByteDance. +## Scope -## How to get VChart +**Based on public documentation and source code reviewed on September 14, 2026, open-source native Lynx does not yet publicly provide the Canvas integration required by this guide.** Installing `@visactor/vchart` does not add Canvas support to the host runtime. For updates, see the [official Lynx documentation](https://lynxjs.org/) and the [Lynx charting discussion](https://github.com/lynx-family/lynx/issues/6230#issuecomment-4729040590). -### npm package +This guide describes environment registration and parameters on the VChart side for internal Lynx hosts that already provide Canvas support. Canvas creation, view binding, templates, lifecycle hooks, and event integration depend on the documentation for the specific host and version. This page does not provide a complete example verified in a host runtime. -You can install the vchart dependency package directly in the lynx project: `@visactor/vchart`. +For the internal ReactLynx component wrapper, see the [ReactLynx guide](/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx). It depends on the internal `@dp/lynx-vchart` package and also requires Canvas support from the host. -### Manually import script +## Get VChart -You can also manually reference VChart's umd packaged product, which you can obtain through the following channels: +Install VChart in a project that meets the host requirements above: -1. Obtain [packages/block-vchart/block/vchart/index.js](https://github.com/VisActor/VChart/blob/main/packages/block-vchart/block/vchart/index.js), we will update it every time we send a package -2. Get it from the following free CDN - -```html - - - - - -``` - -## how to use - -Below we will introduce how to use VChart on Feishu widgets from three parts: `js`, `ttml`, and `ttss`. - -### index.ttml - -Three canvases need to be declared, and pay attention to the order of declaration. - -- `bar_hidden_canvas` hidden canvas, declared in the first, is used for some internal picking logic -- `bar_draw_canvas` draws canvas, the second statement -- `bar_tooltip_canvas` is used to draw the canvas of the tooltip. The tooltip of the cross-end environment is drawn using the canvas. - -```html - - - - - - - - - +```bash +npm install @visactor/vchart ``` -### index.js +## VChart Environment Integration -Create a VChart instance in this file. Because VChart is internally compatible with the lynx environment, its use is basically the same as on the PC. You only need to pay attention to two points: +### Register the Environment -1. Necessary environment parameters need to be declared in the constructor of VChart +Register the Lynx environment before creating a chart: ```ts -const chartInstance = new VChart(spec, { - mode: 'lynx', // Tip: Cross-end environment needs to manually pass in mode - // Cross-end parameters - modeParams: { - domref: domRef, // Canvas node for chart drawing - force: true, // Whether to force the use of canvas for drawing - canvasIdLists: [`${item.id}_draw_canvas`, `${item.id}_tooltip_canvas`, `${item.id}_hidden_canvas`], // canvasId list - tooltipCanvasId: `${item.id}_tooltip_canvas`, // tooltip canvasId - freeCanvasIdx: 1 // Free canvas index - }, - dpr: pixelRatio, // Tip: Cross-end environment needs to manually pass in dpr - renderCanvas: `${item.id}_draw_canvas` // Declare the canvasId used for drawing -}); -``` - -2. Regarding events, users need to bind events to the canvas (canvas used for drawing) element themselves, and then manually dispatch events in the event listening function to trigger events inside VChart. +import { registerLynxEnv } from '@visactor/vchart'; -```ts -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: Must be set - chartInstance.getStage().window.dispatchEvent(event); - } -}, +registerLynxEnv(); ``` -The following is the completed code related to index.js: - -```ts -import barSpec from './data/bar'; -import VChart, { registerLynxEnv } from '@visactor/vchart'; -import mapJson from './data/map-data-china'; +This call registers the Lynx rendering adapter required by VChart. It does not install or enable the host's Canvas component. -Card({ - data: { - chartList: [ - { - id: 'bar', - spec: barSpec, - chart: undefined - } - ] - }, - onLoad: function () { - // 如果需要使用地图，需要先注册地图 - VChart.registerMap('china', mapJson, { - type: 'geojson' - }); - this.init(); - }, +### Initialization Parameters - 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; +The following parameters describe the VChart side of the integration. Their values must come from a host with a working Canvas integration. - 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; +| Configuration | Description | +| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Constructor option `mode` | Set to `'lynx'`. | +| Constructor option `renderCanvas` | The canvas instance or identifier supplied by the host, used to bind the drawing canvas for this chart. | +| Chart spec `width` and `height` | The chart's drawing dimensions in the host. | +| Constructor option `dpr` | The host's device pixel ratio. | +| Constructor option `modeParams` | Host environment capabilities such as `pixelRatio`, `lynx` / `runtime`, or `canvasFactory`. These capabilities should apply to multiple charts in the same environment. | - 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(); - }); - }, +For new integrations, use `renderCanvas`, the chart dimensions, and `dpr` to specify each chart's canvas information, without depending on `domref`, `canvasIdLists`, or `freeCanvasIdx` from older examples. Those parameters cannot supply Canvas support to the host. - 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); - } - } -}); -``` +Interaction also requires canvas event integration for the specific host. After integration, verify initial rendering and touch interaction in that host and version; environment registration alone does not verify that the integration works. ## On-Demand Loading -Lynx-VChart inherently supports on-demand loading. There are two ways to achieve on-demand loading with VChart: - -- Use the `` tag to implement custom on-demand loading. - -The `` component and the `` component are almost identical in usage. The only difference is that users need to import the `VChart` constructor class from `@viasctor/vchart/esm/core`, register the required charts and components as described in this document, and pass them to ``. - -- Use semantic tags, all of which support on-demand loading by default. The default registered components for each type of semantic tag are as follows: - -> Supported from version **0.0.12** - -| Chart | Category | Additional Registered Components | -| -------------------------- | ---------------- | ------------------------------------- | -| `` | Cartesian Charts | `registerLabel` | -| `` | Cartesian Charts | `registerLabel`, `registerTotalLabel` | -| `` | Cartesian Charts | `registerLabel`, `registerTotalLabel` | -| `` | Cartesian Charts | `registerLabel`, `registerTotalLabel` | -| `` | Cartesian Charts | `registerLabel`, | -| `` | Cartesian Charts | `registerLabel` | -| `` | Cartesian Charts | `registerLabel` | -| `` | Cartesian Charts | `registerLabel` | -| `` | Cartesian Charts | `registerLabel` | -| `` | Cartesian Charts | `registerLabel` | -| `` | Cartesian Charts | `registerLabel` | -| `` | Cartesian Charts | `registerLabel` | -| `` | Cartesian Charts | `registerLabel` | -| `` | Cartesian Charts | `registerLabel`, `registerTotalLabel` | -| `` | Polar Charts | `registerLabel` | -| `` | Polar Charts | `registerLabel` | -| `` | Polar Charts | `registerLabel`, `registerIndicator` | -| `` | General Charts | `registerLabel`, `registerIndicator` | -| `` | General Charts | `registerLabel`, `registerIndicator` | -| `` | General Charts | None | -| `` | General Charts | `registerLabel` | -| `` | General Charts | `registerLabel` | -| `` | General Charts | None | -| `` | General Charts | `registerLabel` | -| `` | General Charts | None | -| `` | General Charts | None | -| `` | General Charts | None | -| `` | General Charts | None | -| `` | General Charts | None | -| `` | General Charts | None | -| `` | General Charts | `registerIndicator` | - -For Cartesian charts, the default registered components are as follows: - -- `registerCartesianLinearAxis` -- `registerCartesianBandAxis` -- `registerCartesianTimeAxis` -- `registerCartesianLogAxis` -- `registerCartesianCrossHair` -- `registerBrush` -- `registerContinuousLegend` -- `registerDataZoom` -- `registerDiscreteLegend` -- `registerCustomMark` -- `registerAllMarks` -- `registerMarkArea` -- `registerMarkLine` -- `registerMarkPoint` -- `registerScrollBar` -- `registerTitle` -- `registerTooltip` -- `registerCanvasTooltipHandler` - -For Polar charts, the default registered components are as follows: - -- `registerPolarLinearAxis` -- `registerPolarBandAxis` -- `registerPolarCrossHair` -- `registerBrush` -- `registerContinuous Legend` -- `registerDataZoom` -- `registerDiscreteLegend` -- `registerCustomMark` -- `registerAllMarks` -- `registerScrollBar` -- `registerTitle` -- `registerTooltip` -- `registerCanvasTooltipHandler` - -For General charts, the default registered components are as follows: - -- `registerDiscreteLegend` -- `registerContinuousLegend` -- `registerCustomMark` -- `registerAllMarks` -- `registerTitle` -- `registerTooltip` -- `registerCanvasTooltipHandler` - -When using semantic tags, if you need components that are not loaded by default, you only need to register the missing components. - -[Note]: If there is an error similar to "No matching export in..." when using Lynx, please upgrade the version of Lynx or configure resolve.enable INodeCache to false +For registering individual charts and components, see the [on-demand loading guide](/vchart/guide/tutorial_docs/Load_on_Demand). In Lynx, also call `registerLynxEnv()` and use components suitable for native Canvas environments, such as Canvas Tooltip. -For reference on on-demand loading of VChart, see [related documentation](/vchart/guide/tutorial_docs/Load_on_Demand). +Tags such as `` belong to the internal ReactLynx component wrapper. See the [ReactLynx guide](/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx) for their usage. diff --git a/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md b/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md index bd7f04c934..71444a63db 100644 --- a/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md +++ b/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md @@ -1,8 +1,10 @@ # ReactLynx -**[Note] The open-source version of Lynx currently does not provide canvas functionality, so vchart rendering is not supported at the moment. It will be supported in future versions, so stay tuned. [For more features, please visit the Lynx official website](https://lynxjs.org/)** +Lynx is a high-performance cross-platform framework open-sourced by ByteDance, and ReactLynx provides React syntax support. This guide describes the chart component wrapper for ByteDance's internal ReactLynx 3.0 environment. It depends on the internal `@dp/lynx-vchart` package and Canvas support from the host. -Lynx is ByteDance's open-source high-performance cross-platform framework, which quickly builds native views based on the web technology stack. Lynx was officially open-sourced on March 5, 2025. ReactLynx is the React syntax version of Lynx. VChart, based on ByteDance's internal version ReactLynx3.0, provides chart rendering capabilities. +**Based on public documentation and source code reviewed on September 14, 2026, open-source native Lynx does not yet publicly provide the Canvas integration required by this guide.** Installing a chart package does not add Canvas support to the host, and the internal components in this guide cannot be used directly as an integration for open-source ReactLynx. For updates, see the [official Lynx documentation](https://lynxjs.org/) and the [Lynx charting discussion](https://github.com/lynx-family/lynx/issues/6230#issuecomment-4729040590). + +The host and component package versions must match the internal integration documentation. For environment registration and parameters when using `@visactor/vchart` directly, see the [Lynx guide](/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx). ## How to get Lynx-VChart diff --git a/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md b/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md index 01317d1654..633db4745b 100644 --- a/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md +++ b/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md @@ -1,284 +1,55 @@ # Lynx -**【注意】Lynx 开源版本暂时不提供 canvas 画布功能，所以暂时不支持 vchart 的渲染，后续版本将会支持，敬请期待，[更多功能请查看 lynx 官网](https://lynxjs.org/)** +Lynx 是字节跳动开源的高性能跨端框架，基于 Web 技术栈构建原生视图。VChart 提供了面向字节内部 Lynx 环境的渲染适配。 -Lynx 是字节开源的高性能跨端框架，基于 Web 技术栈快速构建 Native 视图，Lynx 于 2025-03-05 正式开源；VChart 基于 Lynx 字节内部版本提供了该框架的图表渲染能力支持。 +## 适用范围 -## 如何获取 VChart +**根据截至 2026-09-14 的公开文档和源码核查，开源原生 Lynx 尚未公开提供本文所需的 Canvas 接入能力。** 安装 `@visactor/vchart` 不会为宿主补充 Canvas 能力。开源进展请参考 [Lynx 官方文档](https://lynxjs.org/)及 [Lynx 图表需求讨论](https://github.com/lynx-family/lynx/issues/6230#issuecomment-4729040590)。 -### npm 包 +本文说明 VChart 侧的环境注册和参数要求，适用于已经具备 Canvas 能力的内部 Lynx 宿主。宿主的画布创建、视图绑定、模板、生命周期和事件接入方式，需要以对应宿主及版本的接入文档为准。本页不提供经过宿主运行验证的完整示例。 -你可以直接在 lynx 项目中安装 vchart 依赖包：`@visactor/vchart`。 +如果使用内部 ReactLynx 组件封装，请参阅 [ReactLynx 文档](/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx)。该封装依赖内部包 `@dp/lynx-vchart`，同样需要宿主提供 Canvas 能力。 -### 手动引入脚本 +## 获取 VChart -也可以手动引用 VChart 的 umd 打包产物，你可以通过如下渠道获取： +在满足上述宿主要求的项目中安装： -1. 直接仓库中获取 [packages/block-vchart/block/vchart/index.js](https://github.com/VisActor/VChart/blob/main/packages/block-vchart/block/vchart/index.js) ，每次发包我们都会进行更新 -2. 从如下免费的 CDN 中获取 - -```html - - - - - -``` - -## 如何使用 - -下面我们从 `js`、`ttml`、`ttss` 三部分介绍下如何在飞书小组件上使用 VChart。 - -### index.ttml - -需要声明三个 canvas，并且注意声明的顺序 - -- `bar_hidden_canvas` 隐藏的 canvas，在第一个声明，用于内部的一些拾取逻辑 -- `bar_draw_canvas` 绘制 canvas，第二个声明 -- `bar_tooltip_canvas` 用于绘制 tooltip 的 canvas，跨端环境的 tooltip 使用 canvas 绘制。 - -```html - - - - - - - - - +```bash +npm install @visactor/vchart ``` -### index.js +## VChart 环境适配 -在该文件中创建 VChart 实例，因为 VChart 内部对 lynx 环境进行了兼容，所以在使用上，基本于 PC 端无异，只需要注意两点： +### 注册环境 -1. 需要在 VChart 的构造函数中声明必要的环境参数 +创建图表前注册 Lynx 环境： ```ts -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 -}); -``` - -2. 在事件上，需要用户自己在 canvas（用于绘制的 canvas） 元素上绑定事件，然后在事件监听函数中手动得分发事件来触发 VChart 内部的事件。 +import { registerLynxEnv } from '@visactor/vchart'; -```ts -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); - } -}, +registerLynxEnv(); ``` -下面是 index.js 相关的完成代码： - -```ts -import barSpec from './data/bar'; -import VChart, { registerLynxEnv } from '@visactor/vchart'; -import mapJson from './data/map-data-china'; +此调用注册 VChart 所需的 Lynx 渲染适配，不负责安装或启用宿主的 Canvas 组件。 -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; +以下是 VChart 侧的参数要求；具体值需由已完成接入的宿主提供。 - 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; +| 配置位置 | 说明 | +| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | +| 构造选项 `mode` | 设置为 `'lynx'`。 | +| 构造选项 `renderCanvas` | 指定宿主提供的画布实例或标识，用于绑定当前图表的绘制画布。 | +| 图表 spec 的 `width`、`height` | 提供图表在宿主中的绘制尺寸。 | +| 构造选项 `dpr` | 提供宿主的设备像素比。 | +| 构造选项 `modeParams` | 传入宿主提供的环境能力，如 `pixelRatio`、`lynx` / `runtime` 或 `canvasFactory`；这些能力应适用于同一环境中的多个图表。 | - 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(); - }); - }, +新接入应通过 `renderCanvas`、图表尺寸和 `dpr` 指定单个图表的画布信息，不依赖旧示例中的 `domref`、`canvasIdLists` 或 `freeCanvasIdx`。这些旧参数不能替代宿主的 Canvas 能力。 - 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 按需加载的时候，有两种办法： - -- 使用 `` 标签，实现自定义的按需加载 - -``组件和``组件使用方法基本完全相同，唯一差异点为，需要用户从 `@viasctor/vchart/esm/core` 引用 `VChart` 构造类，根据本文描述，注册需要的图表和组件，并传入给 ``; - -- 使用语义化标签，所有的语义化标签默认支持按需加载，其中各种语义化标签默认注册的内容如下： - -> 自**0.0.12**版本开始支持 - -| 图表 | 分类 | 额外注册的组件 | -| -------------------------- | -------------- | ------------------------------------- | -| `` | 直角坐标系图表 | `registerLabel` | -| `` | 直角坐标系图表 | `registerLabel`, `registerTotalLabel` | -| `` | 直角坐标系图表 | `registerLabel`, `registerTotalLabel` | -| `` | 直角坐标系图表 | `registerLabel`, `registerTotalLabel` | -| `` | 直角坐标系图表 | `registerLabel`, | -| `` | 直角坐标系图表 | `registerLabel` | -| `` | 直角坐标系图表 | `registerLabel` | -| `` | 直角坐标系图表 | `registerLabel` | -| `` | 直角坐标系图表 | `registerLabel` | -| `` | 直角坐标系图表 | `registerLabel` | -| `` | 直角坐标系图表 | `registerLabel` | -| `` | 直角坐标系图表 | `registerLabel` | -| `` | 直角坐标系图表 | `registerLabel` | -| `` | 直角坐标系图表 | `registerLabel`, `registerTotalLabel` | -| `` | 极坐标系图表 | `registerLabel` | -| `` | 极坐标系图表 | `registerLabel` | -| `` | 极坐标系图表 | `registerLabel`, `registerIndicator` | -| `` | 通用图表 | `registerLabel`, `registerIndicator` | -| `` | 通用图表 | `registerLabel`, `registerIndicator` | -| `` | 通用图表 | 无 | -| `` | 通用图表 | `registerLabel` | -| `` | 通用图表 | `registerLabel` | -| `` | 通用图表 | 无 | -| `` | 通用图表 | `registerLabel` | -| `` | 通用图表 | 无 | -| `` | 通用图表 | 无 | -| `` | 通用图表 | 无 | -| `` | 通用图表 | 无 | -| `` | 通用图表 | 无 | -| `` | 通用图表 | 无 | -| `` | 通用图表 | `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 的图表和组件按需注册方式请参阅[按需加载教程](/vchart/guide/tutorial_docs/Load_on_Demand)。在 Lynx 中使用时，还需要调用 `registerLynxEnv()`，并使用适合原生 Canvas 环境的组件，例如 Canvas Tooltip。 -VChart 按需引用参考[相关文档](/vchart/guide/tutorial_docs/Load_on_Demand) +`` 等标签属于内部 ReactLynx 组件封装，其用法请参阅 [ReactLynx 文档](/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx)。 diff --git a/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md b/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md index e20b3fddb2..37bfad9eb4 100644 --- a/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md +++ b/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md @@ -1,8 +1,10 @@ # ReactLynx -**【注意】Lynx 开源版本暂时不提供 canvas 画布功能，所以暂时不支持 vchart 的渲染，后续版本将会支持，敬请期待，[更多功能请查看 lynx 官网](https://lynxjs.org/)** +Lynx 是字节跳动开源的高性能跨端框架，ReactLynx 提供 React 语法支持。本文介绍面向字节内部 ReactLynx 3.0 环境的图表组件封装，依赖内部包 `@dp/lynx-vchart` 和宿主提供的 Canvas 能力。 -Lynx 是字节开源的高性能跨端框架，基于 Web 技术栈快速构建 Native 视图，Lynx 于 2025-03-05 正式开源，ReactLynx 是 Lynx 的 React 语法版本 ；VChart 基于字节内部版本 ReactLynx3.0 ，提供了图表渲染能力支持。 +**根据截至 2026-09-14 的公开文档和源码核查，开源原生 Lynx 尚未公开提供本文所需的 Canvas 接入能力。** 安装图表包不会为宿主补充 Canvas 能力，本文中的内部组件也不能直接作为开源 ReactLynx 的接入方案。开源进展请参考 [Lynx 官方文档](https://lynxjs.org/)及 [Lynx 图表需求讨论](https://github.com/lynx-family/lynx/issues/6230#issuecomment-4729040590)。 + +宿主和组件包的版本需与内部接入文档匹配。直接使用 `@visactor/vchart` 的环境注册和参数要求，请参阅 [Lynx 文档](/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx)。 ## 如何获取 Lynx-VChart From 697e3d6bc68355952e1452425d994c032e3bb9f6 Mon Sep 17 00:00:00 2001 From: xile611 Date: Tue, 15 Sep 2026 11:52:05 +0800 Subject: [PATCH 2/3] test: fix crosshair mock return type --- .../__tests__/unit/component/crosshair/crosshair-util.test.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/vchart/__tests__/unit/component/crosshair/crosshair-util.test.ts b/packages/vchart/__tests__/unit/component/crosshair/crosshair-util.test.ts index 3641ce7567..02f28aee58 100644 --- a/packages/vchart/__tests__/unit/component/crosshair/crosshair-util.test.ts +++ b/packages/vchart/__tests__/unit/component/crosshair/crosshair-util.test.ts @@ -19,7 +19,7 @@ describe('crosshair utils', () => { const axis = { getScale: () => ({ type: 'linear', scale }), getLayoutStartPoint: () => ({ x: 0, y: 0 }), - getVRenderComponents: () => [], + getVRenderComponents: (): [] => [], getSpec: () => ({}), getOrient: () => orient, getRegions: () => [ From 943dd248493155265df603a5c14b9abc3b0f1c58 Mon Sep 17 00:00:00 2001 From: xile611 Date: Tue, 15 Sep 2026 14:00:26 +0800 Subject: [PATCH 3/3] docs: restore Lynx usage examples and narrow scope changes --- .../lynx.md | 287 ++++++++++++++++-- .../react-lynx.md | 6 +- .../lynx.md | 287 ++++++++++++++++-- .../react-lynx.md | 6 +- 4 files changed, 522 insertions(+), 64 deletions(-) diff --git a/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md b/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md index a18ef7a8ac..d0667f513c 100644 --- a/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md +++ b/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md @@ -1,55 +1,286 @@ # Lynx -Lynx is a high-performance cross-platform framework open-sourced by ByteDance for building native views with web technologies. VChart provides a rendering adapter for ByteDance's internal Lynx environment. +**[Scope] This guide retains integration instructions for ByteDance's internal Lynx environment. Based on public information reviewed on September 14, 2026, open-source native Lynx does not yet publicly provide the Canvas integration required here. Installing VChart does not add this capability to the host. For updates, see the [official Lynx documentation](https://lynxjs.org/) and the [charting discussion](https://github.com/lynx-family/lynx/issues/6230#issuecomment-4729040590).** -## Scope +Lynx is a high-performance cross-platform framework open-sourced by ByteDance, enabling the rapid construction of Native views based on the Web technology stack. Lynx was officially open-sourced on March 5, 2025. VChart provides chart rendering capabilities for this framework based on the internal version of Lynx at ByteDance. -**Based on public documentation and source code reviewed on September 14, 2026, open-source native Lynx does not yet publicly provide the Canvas integration required by this guide.** Installing `@visactor/vchart` does not add Canvas support to the host runtime. For updates, see the [official Lynx documentation](https://lynxjs.org/) and the [Lynx charting discussion](https://github.com/lynx-family/lynx/issues/6230#issuecomment-4729040590). +## How to get VChart -This guide describes environment registration and parameters on the VChart side for internal Lynx hosts that already provide Canvas support. Canvas creation, view binding, templates, lifecycle hooks, and event integration depend on the documentation for the specific host and version. This page does not provide a complete example verified in a host runtime. +### npm package -For the internal ReactLynx component wrapper, see the [ReactLynx guide](/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx). It depends on the internal `@dp/lynx-vchart` package and also requires Canvas support from the host. +You can install the vchart dependency package directly in the lynx project: `@visactor/vchart`. -## Get VChart +### Manually import script -Install VChart in a project that meets the host requirements above: +You can also obtain the VChart UMD bundle and load it using a method supported by the internal host. The HTML tags below show browser usage and cannot be copied directly into a native Lynx project: -```bash -npm install @visactor/vchart +1. Obtain [build/index.min.js](https://unpkg.com/@visactor/vchart/build/index.min.js) from the `@visactor/vchart` package +2. Get it from the following free CDN + +```html + + + + + ``` -## VChart Environment Integration +## How to Use + +The following historical `ttml` and `js` examples are retained for internal Lynx hosts. `Card(...)`, `SystemInfo`, and the Canvas bridge depend on the specific internal host; they are not general-purpose APIs for open-source ReactLynx. + +These examples have not been verified with the current VChart version and a specific host version. Check the versions and host APIs before using them. The `domref`, `canvasIdLists`, and `freeCanvasIdx` parameters belong to the older integration and should not be treated as the integration contract for newer versions. -### Register the Environment +### index.ttml + +Three canvases need to be declared, and pay attention to the order of declaration. + +- `bar_hidden_canvas` hidden canvas, declared in the first, is used for some internal picking logic +- `bar_draw_canvas` draws canvas, the second statement +- `bar_tooltip_canvas` is used to draw the canvas of the tooltip. The tooltip of the cross-end environment is drawn using the canvas. + +```html + + + + + + + + + +``` -Register the Lynx environment before creating a chart: +### index.js + +This historical example creates a VChart instance in this file and illustrates two parts of the integration: environment parameters and events. + +1. Necessary environment parameters need to be declared in the constructor of VChart ```ts -import { registerLynxEnv } from '@visactor/vchart'; +const chartInstance = new VChart(spec, { + mode: 'lynx', // Tip: Cross-end environment needs to manually pass in mode + // Cross-end parameters + modeParams: { + domref: domRef, // Canvas node for chart drawing + force: true, // Whether to force the use of canvas for drawing + canvasIdLists: [`${item.id}_draw_canvas`, `${item.id}_tooltip_canvas`, `${item.id}_hidden_canvas`], // canvasId list + tooltipCanvasId: `${item.id}_tooltip_canvas`, // tooltip canvasId + freeCanvasIdx: 1 // Free canvas index + }, + dpr: pixelRatio, // Tip: Cross-end environment needs to manually pass in dpr + renderCanvas: `${item.id}_draw_canvas` // Declare the canvasId used for drawing +}); +``` + +2. Regarding events, users need to bind events to the canvas (canvas used for drawing) element themselves, and then manually dispatch events in the event listening function to trigger events inside VChart. -registerLynxEnv(); +```ts +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: Must be set + chartInstance.getStage().window.dispatchEvent(event); + } +}, ``` -This call registers the Lynx rendering adapter required by VChart. It does not install or enable the host's Canvas component. +The following is the index.js example: -### Initialization Parameters +```ts +import barSpec from './data/bar'; +import VChart, { registerLynxEnv } from '@visactor/vchart'; +import mapJson from './data/map-data-china'; -The following parameters describe the VChart side of the integration. Their values must come from a host with a working Canvas integration. +Card({ + data: { + chartList: [ + { + id: 'bar', + spec: barSpec, + chart: undefined + } + ] + }, + onLoad: function () { + // Register the map before using a map chart + VChart.registerMap('china', mapJson, { + type: 'geojson' + }); + this.init(); + }, -| Configuration | Description | -| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Constructor option `mode` | Set to `'lynx'`. | -| Constructor option `renderCanvas` | The canvas instance or identifier supplied by the host, used to bind the drawing canvas for this chart. | -| Chart spec `width` and `height` | The chart's drawing dimensions in the host. | -| Constructor option `dpr` | The host's device pixel ratio. | -| Constructor option `modeParams` | Host environment capabilities such as `pixelRatio`, `lynx` / `runtime`, or `canvasFactory`. These capabilities should apply to multiple charts in the same environment. | + init() { + registerLynxEnv(); + this.data.chartList.forEach(item => { + this.createSelectorQuery() + .select(`#${item.id}_draw_canvas`) + .invoke({ + method: 'boundingClientRect', + success: domRef => { + if (!domRef) { + console.error(`Canvas #${item.id} was not found`); + return; + } + domRef.id = item.id; + const pixelRatio = SystemInfo.pixelRatio; -For new integrations, use `renderCanvas`, the chart dimensions, and `dpr` to specify each chart's canvas information, without depending on `domref`, `canvasIdLists`, or `freeCanvasIdx` from older examples. Those parameters cannot supply Canvas support to the host. + const chartInstance = new VChart(item.spec, { + mode: 'lynx', // Tip: Pass mode explicitly in cross-platform environments + // Cross-platform parameters + modeParams: { + domref: domRef, // Canvas node used to draw the chart + force: true, // Whether to force Canvas rendering + canvasIdLists: [`${item.id}_draw_canvas`, `${item.id}_tooltip_canvas`, `${item.id}_hidden_canvas`], // Canvas ID list + tooltipCanvasId: `${item.id}_tooltip_canvas`, // tooltip canvasId + freeCanvasIdx: 1 // Index of the first canvas available for internal use + }, + dpr: pixelRatio, // Tip: Pass dpr explicitly in cross-platform environments + renderCanvas: `${item.id}_draw_canvas` // Canvas ID used for drawing + }); + item.chart = chartInstance; -Interaction also requires canvas event integration for the specific host. After integration, verify initial rendering and touch interaction in that host and version; environment registration alone does not verify that the integration works. + 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: Must be set + chartInstance.getStage().window.dispatchEvent(event); + } + } +}); +``` ## On-Demand Loading -For registering individual charts and components, see the [on-demand loading guide](/vchart/guide/tutorial_docs/Load_on_Demand). In Lynx, also call `registerLynxEnv()` and use components suitable for native Canvas environments, such as Canvas Tooltip. +The `` and semantic tags below belong to the internal `@dp/lynx-vchart` component wrapper and require the corresponding internal ReactLynx host. See the [ReactLynx guide](/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx) for usage. The historical loading methods and registration lists are retained below; check them against the wrapper version you use. + +- Use the `` tag to implement custom on-demand loading. + +The `` component and the `` component are almost identical in usage. The only difference is that users need to import the `VChart` constructor class from `@visactor/vchart/esm/core`, register the required charts and components as described in this document, and pass them to ``. + +- Use semantic tags, all of which support on-demand loading by default. The default registered components for each type of semantic tag are as follows: + +> Historical record: supported by the component wrapper from **0.0.12**. This version does not refer to VChart or the Lynx engine. + +| Chart | Category | Additional Registered Components | +| -------------------------- | ---------------- | ------------------------------------- | +| `` | Cartesian Charts | `registerLabel` | +| `` | Cartesian Charts | `registerLabel`, `registerTotalLabel` | +| `` | Cartesian Charts | `registerLabel`, `registerTotalLabel` | +| `` | Cartesian Charts | `registerLabel`, `registerTotalLabel` | +| `` | Cartesian Charts | `registerLabel`, | +| `` | Cartesian Charts | `registerLabel` | +| `` | Cartesian Charts | `registerLabel` | +| `` | Cartesian Charts | `registerLabel` | +| `` | Cartesian Charts | `registerLabel` | +| `` | Cartesian Charts | `registerLabel` | +| `` | Cartesian Charts | `registerLabel` | +| `` | Cartesian Charts | `registerLabel` | +| `` | Cartesian Charts | `registerLabel` | +| `` | Cartesian Charts | `registerLabel`, `registerTotalLabel` | +| `` | Polar Charts | `registerLabel` | +| `` | Polar Charts | `registerLabel` | +| `` | Polar Charts | `registerLabel`, `registerIndicator` | +| `` | General Charts | `registerLabel`, `registerIndicator` | +| `` | General Charts | `registerLabel`, `registerIndicator` | +| `` | General Charts | None | +| `` | General Charts | `registerLabel` | +| `` | General Charts | `registerLabel` | +| `` | General Charts | None | +| `` | General Charts | `registerLabel` | +| `` | General Charts | None | +| `` | General Charts | None | +| `` | General Charts | None | +| `` | General Charts | None | +| `` | General Charts | None | +| `` | General Charts | None | +| `` | General Charts | `registerIndicator` | + +For Cartesian charts, the default registered components are as follows: + +- `registerCartesianLinearAxis` +- `registerCartesianBandAxis` +- `registerCartesianTimeAxis` +- `registerCartesianLogAxis` +- `registerCartesianCrossHair` +- `registerBrush` +- `registerContinuousLegend` +- `registerDataZoom` +- `registerDiscreteLegend` +- `registerCustomMark` +- `registerAllMarks` +- `registerMarkArea` +- `registerMarkLine` +- `registerMarkPoint` +- `registerScrollBar` +- `registerTitle` +- `registerTooltip` +- `registerCanvasTooltipHandler` + +For Polar charts, the default registered components are as follows: + +- `registerPolarLinearAxis` +- `registerPolarBandAxis` +- `registerPolarCrossHair` +- `registerBrush` +- `registerContinuousLegend` +- `registerDataZoom` +- `registerDiscreteLegend` +- `registerCustomMark` +- `registerAllMarks` +- `registerScrollBar` +- `registerTitle` +- `registerTooltip` +- `registerCanvasTooltipHandler` + +For General charts, the default registered components are as follows: + +- `registerDiscreteLegend` +- `registerContinuousLegend` +- `registerCustomMark` +- `registerAllMarks` +- `registerTitle` +- `registerTooltip` +- `registerCanvasTooltipHandler` + +When using semantic tags, if you need components that are not loaded by default, you only need to register the missing components. + +[Historical troubleshooting note]: Earlier internal integration documentation suggested upgrading Lynx or setting `resolve.enableINodeCache` to `false` for "No matching export in ..." errors. The build tool and applicable versions for this advice have not been verified. Check the documentation for your toolchain before applying it; this is not a general configuration option for open-source Lynx. -Tags such as `` belong to the internal ReactLynx component wrapper. See the [ReactLynx guide](/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx) for their usage. +For reference on on-demand loading of VChart, see [related documentation](/vchart/guide/tutorial_docs/Load_on_Demand). diff --git a/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md b/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md index 71444a63db..bb19791752 100644 --- a/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md +++ b/docs/assets/guide/en/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md @@ -1,10 +1,8 @@ # ReactLynx -Lynx is a high-performance cross-platform framework open-sourced by ByteDance, and ReactLynx provides React syntax support. This guide describes the chart component wrapper for ByteDance's internal ReactLynx 3.0 environment. It depends on the internal `@dp/lynx-vchart` package and Canvas support from the host. +**[Scope] This guide covers the internal `@dp/lynx-vchart` package and its corresponding internal ReactLynx host at ByteDance. Based on public information reviewed on September 14, 2026, open-source native Lynx does not yet publicly provide the Canvas integration required here. Installing a chart package does not add this capability to the host. For updates, see the [official Lynx documentation](https://lynxjs.org/) and the [charting discussion](https://github.com/lynx-family/lynx/issues/6230#issuecomment-4729040590).** -**Based on public documentation and source code reviewed on September 14, 2026, open-source native Lynx does not yet publicly provide the Canvas integration required by this guide.** Installing a chart package does not add Canvas support to the host, and the internal components in this guide cannot be used directly as an integration for open-source ReactLynx. For updates, see the [official Lynx documentation](https://lynxjs.org/) and the [Lynx charting discussion](https://github.com/lynx-family/lynx/issues/6230#issuecomment-4729040590). - -The host and component package versions must match the internal integration documentation. For environment registration and parameters when using `@visactor/vchart` directly, see the [Lynx guide](/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx). +Lynx is ByteDance's open-source high-performance cross-platform framework, which quickly builds native views based on the web technology stack. Lynx was officially open-sourced on March 5, 2025. ReactLynx is the React syntax version of Lynx. VChart, based on ByteDance's internal version ReactLynx3.0, provides chart rendering capabilities. ## How to get Lynx-VChart diff --git a/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md b/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md index 633db4745b..fe1d29ebfa 100644 --- a/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md +++ b/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx.md @@ -1,55 +1,286 @@ # Lynx -Lynx 是字节跳动开源的高性能跨端框架，基于 Web 技术栈构建原生视图。VChart 提供了面向字节内部 Lynx 环境的渲染适配。 +**【适用范围】本文保留的是字节内部 Lynx 环境的接入说明。根据截至 2026-09-14 的公开资料核查，开源原生 Lynx 尚未公开提供本文所需的 Canvas 接入能力；安装 VChart 不会为宿主补充该能力。开源进展请参考 [Lynx 官方文档](https://lynxjs.org/)及[图表需求讨论](https://github.com/lynx-family/lynx/issues/6230#issuecomment-4729040590)。** -## 适用范围 +Lynx 是字节开源的高性能跨端框架，基于 Web 技术栈快速构建 Native 视图，Lynx 于 2025-03-05 正式开源；VChart 基于 Lynx 字节内部版本提供了该框架的图表渲染能力支持。 -**根据截至 2026-09-14 的公开文档和源码核查，开源原生 Lynx 尚未公开提供本文所需的 Canvas 接入能力。** 安装 `@visactor/vchart` 不会为宿主补充 Canvas 能力。开源进展请参考 [Lynx 官方文档](https://lynxjs.org/)及 [Lynx 图表需求讨论](https://github.com/lynx-family/lynx/issues/6230#issuecomment-4729040590)。 +## 如何获取 VChart -本文说明 VChart 侧的环境注册和参数要求，适用于已经具备 Canvas 能力的内部 Lynx 宿主。宿主的画布创建、视图绑定、模板、生命周期和事件接入方式，需要以对应宿主及版本的接入文档为准。本页不提供经过宿主运行验证的完整示例。 +### npm 包 -如果使用内部 ReactLynx 组件封装，请参阅 [ReactLynx 文档](/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx)。该封装依赖内部包 `@dp/lynx-vchart`，同样需要宿主提供 Canvas 能力。 +你可以直接在 lynx 项目中安装 vchart 依赖包：`@visactor/vchart`。 -## 获取 VChart +### 手动引入脚本 -在满足上述宿主要求的项目中安装： +也可以获取 VChart 的 UMD 打包产物，并按内部宿主支持的方式加载。下面的 HTML 标签展示浏览器中的引用方式，原生 Lynx 项目不能直接照搬： -```bash -npm install @visactor/vchart +1. 获取 `@visactor/vchart` 包中的 [build/index.min.js](https://unpkg.com/@visactor/vchart/build/index.min.js) 构建产物 +2. 从如下免费的 CDN 中获取 + +```html + + + + + ``` -## VChart 环境适配 +## 如何使用 + +以下保留内部 Lynx 宿主的历史 `ttml` 和 `js` 接入示例。`Card(...)`、`SystemInfo` 及画布桥接依赖对应内部宿主，不是开源 ReactLynx 的通用 API。 + +这些示例尚未针对当前 VChart 与具体宿主版本完成运行验证，使用前需核对版本及宿主 API。示例中的 `domref`、`canvasIdLists` 和 `freeCanvasIdx` 是旧接入参数，不应直接作为新版本接入契约。 -### 注册环境 +### index.ttml + +需要声明三个 canvas，并且注意声明的顺序 + +- `bar_hidden_canvas` 隐藏的 canvas，在第一个声明，用于内部的一些拾取逻辑 +- `bar_draw_canvas` 绘制 canvas，第二个声明 +- `bar_tooltip_canvas` 用于绘制 tooltip 的 canvas，跨端环境的 tooltip 使用 canvas 绘制。 + +```html + + + + + + + + + +``` -创建图表前注册 Lynx 环境： +### index.js + +此历史示例在该文件中创建 VChart 实例，展示环境参数和事件接入两个部分： + +1. 需要在 VChart 的构造函数中声明必要的环境参数 ```ts -import { registerLynxEnv } from '@visactor/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 +}); +``` + +2. 在事件上，需要用户自己在 canvas（用于绘制的 canvas） 元素上绑定事件，然后在事件监听函数中手动分发事件来触发 VChart 内部的事件。 -registerLynxEnv(); +```ts +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); + } +}, ``` -此调用注册 VChart 所需的 Lynx 渲染适配，不负责安装或启用宿主的 Canvas 组件。 +下面是 index.js 示例代码： -### 初始化参数 +```ts +import barSpec from './data/bar'; +import VChart, { registerLynxEnv } from '@visactor/vchart'; +import mapJson from './data/map-data-china'; -以下是 VChart 侧的参数要求；具体值需由已完成接入的宿主提供。 +Card({ + data: { + chartList: [ + { + id: 'bar', + spec: barSpec, + chart: undefined + } + ] + }, + onLoad: function () { + // 如果需要使用地图，需要先注册地图 + VChart.registerMap('china', mapJson, { + type: 'geojson' + }); + this.init(); + }, -| 配置位置 | 说明 | -| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | -| 构造选项 `mode` | 设置为 `'lynx'`。 | -| 构造选项 `renderCanvas` | 指定宿主提供的画布实例或标识，用于绑定当前图表的绘制画布。 | -| 图表 spec 的 `width`、`height` | 提供图表在宿主中的绘制尺寸。 | -| 构造选项 `dpr` | 提供宿主的设备像素比。 | -| 构造选项 `modeParams` | 传入宿主提供的环境能力，如 `pixelRatio`、`lynx` / `runtime` 或 `canvasFactory`；这些能力应适用于同一环境中的多个图表。 | + 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; -新接入应通过 `renderCanvas`、图表尺寸和 `dpr` 指定单个图表的画布信息，不依赖旧示例中的 `domref`、`canvasIdLists` 或 `freeCanvasIdx`。这些旧参数不能替代宿主的 Canvas 能力。 + 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); + } + } +}); +``` ## 按需加载 -VChart 的图表和组件按需注册方式请参阅[按需加载教程](/vchart/guide/tutorial_docs/Load_on_Demand)。在 Lynx 中使用时，还需要调用 `registerLynxEnv()`，并使用适合原生 Canvas 环境的组件，例如 Canvas Tooltip。 +以下 `` 和语义化标签属于内部包 `@dp/lynx-vchart` 的组件封装，使用前需具备对应内部 ReactLynx 宿主；完整用法参考 [ReactLynx 文档](/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx)。下面保留该封装的历史按需加载方式及注册清单，需与实际使用的封装版本核对： + +- 使用 `` 标签，实现自定义的按需加载 + +``组件和``组件使用方法基本完全相同，唯一差异点为，需要用户从 `@visactor/vchart/esm/core` 引用 `VChart` 构造类，根据本文描述，注册需要的图表和组件，并传入给 ``; + +- 使用语义化标签，所有的语义化标签默认支持按需加载，其中各种语义化标签默认注册的内容如下： + +> 历史记录：该组件封装自 **0.0.12** 版本开始支持；此版本号不指 VChart 或 Lynx 引擎。 + +| 图表 | 分类 | 额外注册的组件 | +| -------------------------- | -------------- | ------------------------------------- | +| `` | 直角坐标系图表 | `registerLabel` | +| `` | 直角坐标系图表 | `registerLabel`, `registerTotalLabel` | +| `` | 直角坐标系图表 | `registerLabel`, `registerTotalLabel` | +| `` | 直角坐标系图表 | `registerLabel`, `registerTotalLabel` | +| `` | 直角坐标系图表 | `registerLabel`, | +| `` | 直角坐标系图表 | `registerLabel` | +| `` | 直角坐标系图表 | `registerLabel` | +| `` | 直角坐标系图表 | `registerLabel` | +| `` | 直角坐标系图表 | `registerLabel` | +| `` | 直角坐标系图表 | `registerLabel` | +| `` | 直角坐标系图表 | `registerLabel` | +| `` | 直角坐标系图表 | `registerLabel` | +| `` | 直角坐标系图表 | `registerLabel` | +| `` | 直角坐标系图表 | `registerLabel`, `registerTotalLabel` | +| `` | 极坐标系图表 | `registerLabel` | +| `` | 极坐标系图表 | `registerLabel` | +| `` | 极坐标系图表 | `registerLabel`, `registerIndicator` | +| `` | 通用图表 | `registerLabel`, `registerIndicator` | +| `` | 通用图表 | `registerLabel`, `registerIndicator` | +| `` | 通用图表 | 无 | +| `` | 通用图表 | `registerLabel` | +| `` | 通用图表 | `registerLabel` | +| `` | 通用图表 | 无 | +| `` | 通用图表 | `registerLabel` | +| `` | 通用图表 | 无 | +| `` | 通用图表 | 无 | +| `` | 通用图表 | 无 | +| `` | 通用图表 | 无 | +| `` | 通用图表 | 无 | +| `` | 通用图表 | 无 | +| `` | 通用图表 | `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` + +使用语义化标签的时候，如果用到其他没有默认加载的组件，只需要注册未加载的组件即可； + +【历史排错记录】：旧版内部接入文档曾建议在“No matching export in ...”报错时升级 Lynx，或将 `resolve.enableINodeCache` 设为 `false`。该建议所属的构建工具及适用版本尚未核实，使用前需核对对应工具链文档，不能将其作为开源 Lynx 的通用配置。 -`` 等标签属于内部 ReactLynx 组件封装，其用法请参阅 [ReactLynx 文档](/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx)。 +VChart 按需引用参考[相关文档](/vchart/guide/tutorial_docs/Load_on_Demand) diff --git a/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md b/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md index 37bfad9eb4..df6a087a42 100644 --- a/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md +++ b/docs/assets/guide/zh/tutorial_docs/Cross-terminal_and_Developer_Ecology/react-lynx.md @@ -1,10 +1,8 @@ # ReactLynx -Lynx 是字节跳动开源的高性能跨端框架，ReactLynx 提供 React 语法支持。本文介绍面向字节内部 ReactLynx 3.0 环境的图表组件封装，依赖内部包 `@dp/lynx-vchart` 和宿主提供的 Canvas 能力。 +**【适用范围】本文介绍的是内部包 `@dp/lynx-vchart` 及其对应的字节内部 ReactLynx 宿主。根据截至 2026-09-14 的公开资料核查，开源原生 Lynx 尚未公开提供本文所需的 Canvas 接入能力；安装图表包不会为宿主补充该能力。开源进展请参考 [Lynx 官方文档](https://lynxjs.org/)及[图表需求讨论](https://github.com/lynx-family/lynx/issues/6230#issuecomment-4729040590)。** -**根据截至 2026-09-14 的公开文档和源码核查，开源原生 Lynx 尚未公开提供本文所需的 Canvas 接入能力。** 安装图表包不会为宿主补充 Canvas 能力，本文中的内部组件也不能直接作为开源 ReactLynx 的接入方案。开源进展请参考 [Lynx 官方文档](https://lynxjs.org/)及 [Lynx 图表需求讨论](https://github.com/lynx-family/lynx/issues/6230#issuecomment-4729040590)。 - -宿主和组件包的版本需与内部接入文档匹配。直接使用 `@visactor/vchart` 的环境注册和参数要求，请参阅 [Lynx 文档](/vchart/guide/tutorial_docs/Cross-terminal_and_Developer_Ecology/lynx)。 +Lynx 是字节开源的高性能跨端框架，基于 Web 技术栈快速构建 Native 视图，Lynx 于 2025-03-05 正式开源，ReactLynx 是 Lynx 的 React 语法版本 ；VChart 基于字节内部版本 ReactLynx3.0 ，提供了图表渲染能力支持。 ## 如何获取 Lynx-VChart