*自 V2.66.0 私有化版本开始支持

用户可以上传自定义组件，在组件面板区域快速使用自定义组件。本文将为您具体介绍自定义组件的开发与使用。

2.1 组件添加

（1)点击顶部操作栏上的「自定义组件管理」按钮打开对话框

(2)选择需要添加的组件

(3)点击添加，出现添加成功的消息

(4)此时在左下角的组件里能够看到组件已被添加,可点击进行使用。

2.2 样式配置面板

用户可通过右侧样式配置面板对自定义组件进行相关设置，如：X、Y表示该组件在画布中的相对位置、不透明度、超出区块部分不显示；针对文本类自定义组件，可调整文本样式（字体、颜色、居中、间距）；图表异常信息提示（背景颜色、字体、大小、颜色）。

2.3 交互配置面板

自定义组件支持单击/双击/加载完成触发交互事件，流程如下：
（1）交互面板中新建交互
（2）选择所需的事件类型
（3）针对该事件设置所需的响应
自定义组件支持：打开链接、切换面板页面、设置元素属性、切换面板状态、变更轮播状态、地图钻取、设置筛选项、等待、引发事件、修改变量、刷新数据、刷新所有可视化内容、触发UE动作 响应。具体交互配置操作可参见：数字大屏交互配置--智能数据洞察-火山引擎数字大屏交互配置--智能数据洞察-火山引擎

3.1 环境准备与工具包安装

3.1.1 环境准备

1. 进入 Node.js 官网 ，下载并安装对应操作系统的 Node.js。注意，需使用 14.21.3 以上的版本。

Tips: 如果你已经安装过 Node.js ，推荐使用版本管理工具如 nvm 等进行管理。

2. 安装成功后，在系统 CLI 执行 node -v 和 npm -v 命令，查看 Node 和 NPM 版本，确保环境满足要求。

3.1.2 安装组件 CLI 工具包

1. 在系统 CLI 中执行以下命令安装工具包

// 版本 v2.66.0 至 v2.68.0 使用以下版本的 CLI
npm install @v-screen/component-cli@0.0.11 -g

// 版本 v2.70.0 及之后 使用以下版本的 CLI
npm install @v-screen/component-cli -g

2. 安装成功后，执行以下命令查看工具包相关信息

vscreen-component -h
// 或者
vcomp -h

3.2 创建组件项目

1. 进入到你希望存放组件的目录，通过系统 CLI 执行以下命令，根据提示创建项目

// 将 hello-world 替换成需要创建的项目名称
vscreen-component create hello-world
// 或者
vcomp create hello-world

2. 进入创建好的项目目录，执行以下命令初始化

npm install

3.3 开发组件

1. 找到 src/components 中对应组件的 Renderer.js 文件进行组件开发，具体请查看文末 开发者参考 部分

import { defineRenderer, EntityElement } from '@v-screen/component'
import { events } from './events'

export const ExampleRenderer1 = defineRenderer(
  class ExampleRenderer1 extends EntityElement {
    static events = events

    render(isFirstRender) {
      super.render(isFirstRender)
      /** 实现组件具体渲染逻辑 */
      if (isFirstRender) {
        const div = document.createElement('div')
        div.innerText = 'Hello World'
        div.style.cssText = `
          color: #ffffff;
          font-size: 24px;
        `

        this.variableContext.div = div
        this.dom.appendChild(div)   
      }
    }

    destroy(scene) {
      /** 实现组件具体销毁逻辑 */
      this.variableContext.div?.destroy()

      super.destroy(scene)
    }
  }
)

3.4 调试组件

1. 当组件开发到一个阶段时，通过系统 CLI 执行以下命令生成构建产物调试链接

npm run dev

◐ 开始构建...
✔ 构建成功！
✔ 调试产物链接已生成：http://localhost:8080/bundle.umd.js

2. 拷贝该链接为{构建产物调试链接}，新建一个用于调试自定义组件的大屏
3. 使用 F12 或 Ctrl+Alt+I 打开开发者工具，打开控制台（console），输入并按下回车

将{组件包名称}替换为你的组件包名称

await _vsdebug.addLibrary("{组件包名称}","{构建产物调试链接}")

4. 此时编辑器左下角组件库中会出现调试的组件

3.5 构建并生成组件包

1. 在组件开发完成之后，通过系统 CLI 执行以下命令进行构建

npm run build

◐ 开始构建...
✔ 构建成功！

2. 确认执行构建命令后，目录下生成了 component.tgz 的文件

3.6 发布组件

您可点击开放平台-插件系统-开发者后台，或访问控制台页面 https://<HOST>/<PATH>/bi/developers/console，通过界面发布一个新插件。 发布一个新插件分为三个步骤。

1. 完善组件信息

2.可见性设置

公开：所有人都可以在组件市场中访问到该组件
部分项目：选择部分项目后，需要输入可见项目。设置的可见项目可以在组件市场中访问到该组件
不公开：设置为不公开后组件市场中找不到该组件

3. 上传组件文件

将构建并生产的组件包 component.tgz 上传，点击发布，即可在列表中看到组件发布成功的状态

3.7 更新组件

后续如果需要更新组件版本，点击列表中的查看按钮在组件详情中操作。先点击左侧的【版本管理】进入版本操作页面，点击右上角的【创建版本】按钮：

在创建版本弹窗中填写新的版本号和更新说明、上传新的组件包，点击确定后新的组件发布成功。

本章内容为您介绍组件包相关概念，帮助您更好地进行组件开发。

组件包结构

一个开发并构建完成的组件包结构如下：

.
├── src                                                    // 源码目录
│   ├── components                                         // 组件目录
│   │    ├── Component1                                   // 组件1目录
│   │    │    ├── attributes.js                          // 组件1属性配置声明
│   │    │    ├── description.js                         // 组件1描述声明及属性预设值
│   │    │    ├── events.js                              // 组件1事件配置声明
│   │    │    ├── index.js                               // 组件1入口文件
│   │    │    └── Renderer.js                            // 组件1实现
│   │    ├── ...
│   │    ├── ComponentN
│   │    │    └── ...
│   │    └── index.js                                     // 组件入口文件
│   └── index.js                                           // 组件包入口文件
├── component.tgz                                           // 组件包打包产物
├── package-lock.json
├── package.json
├── LICENSE
└── README.md

1.属性配置

以「日期选择器」组件为例，属性配置是控制组件样式如何呈现的声明

通过声明，可以控制组件样式配置部分的布局及对应的设置控件。

布局

组件的样式配置布局以 Panel 为布局单位，在 Panel 内声明控件占位大小进行排布。

占位单位

占位单位共 3 种

1. Large - 占满 1 行

2. Medium - 占据 1 行的 1/2

3. Small - 占据 1 行的 1/4

占位类型

占位可分为 2 种

1. 控件占位 - 控件实际的占位
2. 间隔占位 - 控件留白的占位

设置控件

设置控件分为 2 个部分

基础控件

基础控件共有 9 种

复杂控件

复杂控件共有 8 种

2.预设值

预设值用于配置组件创建时的默认表现

编辑空间

决定组件可在哪个编辑空间下被创建，默认为当前页面

组件基本属性

包含组件宽度、高度和宽高比锁定等

组件样式

给 属性配置 声明的部分填充预设值

组件内置数据

组件可以提供对外可用的数据，如文本组件的文本，日期选择器的日期等

数据分析

组件可以使用数据分析功能进行数据获取、处理与展示

3.事件交互配置

组件可以声明支持的事件并控制事件触发的形式，所有组件默认支持单击、双击和加载完成。

4.数据分析配置

组件可以声明数据分析所需要的配置以及配置的形式、限制等，如：

具体请查看下方API参考文档。

数据大屏自定义组件 - API 参考文档.pdf

未知大小

5.筛选器

组件可以被声明为支持成为筛选器，存在声明的组件，在选中状态下，可以在筛选面板点击成为筛选器，并选择在指定交互动作之后需要联动的组件。

6.组件实现

组件的开发，主要的部分是实现组件的渲染，简单来说，就是实现一个 render 方法，平台会在初始化和更新的时候进行调用。

组件渲染

组件渲染使用到的技术就是单纯的 JavaScript + WebAPI ，组件拥有一个 DOM 容器属性 dom ，所有的渲染最终由该容器在初次渲染时进行挂载，并且可以将渲染的元素存储在 variableContext 的属性中，后续的更新只需要从其中取出相应的元素进行修改即可。

class ElementRenderer extends EntityElement {
//......
    render(isFirstRender) {
        super.render(isFirstRender)

        if (isFirstRender) {
            /** 实现组件初次渲染的逻辑 */
            const div = document.createElement('div')
            div.innerText = 'Hello World'
            div.style.cssText = `
                color: #ffffff;
                font-size: 24px;
            `
            
            this.variableContext.div = div
            this.dom.appendChild(div)   
        }
 
        const { div } = this.variableContext
        /** 实现组件更新的逻辑 */
        // ......
    }
// ......
}

框架支持

*自 v2.70.0 私有化版本开始支持。
目前支持使用 React 和 Vue 进行开发，可在通过 CLI 创建组件包时进行选择。