工程结构与配置说明

2.1 环境准备

前置条件

• Node.js 10.0.0 以上（npm >= 6.x）

• 推荐 IDE：VS Code

• 推荐插件：TypeScript、LESS

安装 CLI 工具

官方资料统一建议使用：

npm i @grapecity/wyn-visual-tools -g

该工具用于：

• 初始化工程：wyn-visual-tools init

• 启动开发服务：wyn-visual-tools develop

• 打包发布：wyn-visual-tools package

自行开发的定位说明

当现成插件无法满足业务需求时，客户可通过官方 CLI 与 Visual API 完成自定义可视化插件开发。

2.2 初始化工程

初始化命令

wyn-visual-tools init

CLI 会引导输入工程名称，并自动安装依赖。也可按通用 npm 方式自行初始化。

主指南中的手动初始化示例

mkdir 插件名称
cd 插件名称
npm init -y
npm install --save-dev typescript webpack webpack-cli ts-loader
npm install --save-dev less less-loader css-loader mini-css-extract-plugin
npm install --save-dev @babel/core babel-loader
npm install --save-dev terser-webpack-plugin css-minimizer-webpack-plugin

初始化后典型工程结构

• assets：图片资源，打包后可转为 base64 使用

• i18nResources：国际化资源

• node_modules：项目依赖

• src/visual.ts：插件入口与主实现

• style：LESS / CSS

• capabilities.json：数据绑定、属性、动作、分析等静态能力

• package.json / package-lock.json：npm 配置

• tsconfig.json：TypeScript 配置

• visual.d.ts：API 类型声明

• visual.json：插件元信息

• webpack.config.js：构建配置

界面位置说明

• 原始项目结构截图用于展示：wyn-visual-tools init 后，工程目录已经具备开发插件所需的标准文件骨架。

2.3 开发调试流程

第一步：启用开发者模式

系统管理员进入：

「系统管理 > 系统设置 > 仪表板设置 > 通用」

将“启用开发者模式”设置为“是”。

第二步：启动开发服务

wyn-visual-tools develop

• 默认本地端口：3000

• 可通过 -p 修改端口号

• 原始资料特别说明：当前开发工具不支持在 HTTPS 站点上使用

第三步：在设计器中添加开发工具组件

1. 打开仪表板设计器。

2. 拖拽“开发工具”组件到设计区。

3. 在开发工具属性设置中可修改端口号。

4. 点击开发工具操作栏上的“刷新”按钮，即可重新加载本地自定义插件。

第四步：迭代开发

开发时通常按以下顺序进行：

1. 配置 visual.json

2. 配置 capabilities.json

3. （可选）加入 i18nResources

4. （可选）加入 assets

5. 通过 visual.ts 与 Visual API 实现视觉与交互逻辑

6. 刷新开发工具，查看设计器中的实时效果

7. 更新 package.json 中的版本号

2.4 从零开发一个 ECharts Demo

Demo 文档给出了一个从零构建示例插件的实操路径。其核心顺序如下。

1）初始化并安装 ECharts

wyn-visual-tools init
npm install echarts
npm install @types/echarts --save-dev
wyn-visual-tools develop

2）在 src/visual.ts 中初始化图表实例

• 导入 ECharts

• 在构造器中创建 ECharts 实例

3）先渲染一个 mock chart

• 新增 render 方法

• 在 update 中调用 render

• 先使用模拟数据完成最小可运行图表

4）增加数据绑定

• 在 capabilities.json 中增加数据绑定定义

• 在 update 中把 dataViews 转换为 ECharts 所需的数据结构

5）增加尺寸响应

• 在 onResize 中调用图表 resize 或重新渲染

6）增加自定义属性

• 在 capabilities.json 中新增属性

• 在 render 中读取 options.properties 并应用到图表配置

7）增加标题与交互支持

• 打开标题功能

• 增加交互或 action 支持，例如聚焦、过滤、排名

8）销毁实例

• 在 onDestroy 中销毁 ECharts 实例，避免内存泄漏

Demo 附件说明（必须保留）

Demo 原文引用了以下外部附件/文件，但当前目录中未直接提供实体文件：

1. visual.ts

   • 来源文件：2e773bc0-2f5c-421e-930c-6517a08a83bf.md

   • 用途：展示将 dataViews 转换为 ECharts 数据结构的代码示例

   • 本文已纳入的文字化范围：初始化图表、读取数据视图、映射数据结构、在 update 中刷新图表

2. visual (1).ts

   • 来源文件：2e773bc0-2f5c-421e-930c-6517a08a83bf.md

   • 用途：展示在 render 中消费自定义属性的代码示例

   • 本文已纳入的文字化范围：读取属性、动态修改图表配置、结合属性控制渲染

3. SimpleEcharts.zip

   • 来源文件：2e773bc0-2f5c-421e-930c-6517a08a83bf.md

   • 用途：完整示例工程压缩包

   • 本文已纳入的文字化范围：工程初始化、ECharts 接入、数据绑定、属性、action、发布上传流程

界面位置说明

• 原始截图按步骤展示了：初始化后的工程结构、visual.ts 中创建图表实例、mock chart 效果、数据绑定界面、自定义属性界面、添加 action 的界面，以及最终发布前的命名设置界面。

2.5 打包、上传、发布与验证

开发构建

npm run compile
npm run dev

生产构建

npm run release

官方推荐打包方式

wyn-visual-tools package

官方资料明确强调：

• .viz 是 Wyn 可视化插件的分发格式。

• wyn-visual-tools package 会自动处理 visual info、assets、icon、i18n、release 构建，并生成最终 .viz 文件。

• 不要手动用 ZIP 方式打包插件。

发布闭环

1. 本地完成开发与调试。

2. 更新版本号。

3. 运行 wyn-visual-tools package。

4. 生成 .viz 文件。

5. 上传至门户或管理后台。

6. 在设计器中拖拽使用并做最终验证。