自定义组件使用说明

初始化项目

云搭可视化平台提供 Yun Da CLI 命令行工具，用于快速初始化自定义组件项目。

安装

要全局安装 Yun Da CLI，请运行以下命令：

npm install -g git+ssh://git@10.16.3.230:HiBrain4.1/yun-da-cli.git

注意：CLI 工具目前放在内网，所有需要有访问内网 gitlab 的权限

使用

要创建一个新的 Yun Da 项目，请运行以下命令：

yun-da-cli create projectName

将 **projectName **替换为您的项目名称。

更新

安装最新版本

要安装最新版本的 Yun Da CLI，请运行以下命令：

npm install -g git+ssh://git@10.16.3.230:HiBrain4.1/yun-da-cli.git#master

安装指定版本

要安装指定版本的 Yun Da CLI，请先查看所有可用版本

git ls-remote --tags git@10.16.3.230:HiBrain4.1/yun-da-cli.git

然后运行以下命令安装指定版本（例如** 1.2.0**）：

npm install -g git+ssh://git@10.16.3.230:HiBrain4.1/yun-da-cli.git#1.2.0

组件开发规范

目录规范

src
  ├── component
  │   ├── index.js              // 【必选】组件出口文件
  │   ├── config.js             // 【必选】组件配置信息
  │   └── custom-button.vue     // 【必选】渲染组件
  │   └── config-form.vue       // 【必选】组件配置表单
  ├── README.md                 // 【可选】组件说明及 API
  └── package.json              // 【必选】组件 package.json

平台组件 schema 定义

组件自身静态属性

属性	说明	备注
name	组件唯一标识
type	组件的类型，对应编辑器内组件库的一级分类	自定义组件统一为 custom
triggers	组件支持的触发事件，如点击事件、数据更新事件等。用于组件事件模块的配置。	示例: [ { name: 'click', label: '点击', } ]
actions	组件支持的事件动作	示例： [ { name: "show", label: '显示', method: "show" } ]

组件的属性配置信息

属性	说明	默认值
title	组件在画布中的图层名称	组件的 label 属性
group	组件所在的屏幕	undefined
display	组件的显隐状态	true
left	组件在画布中的 x 坐标	自由定义像素值
top	组件在画布中的 y 坐标	自由定义像素值
width	组件的宽度	自由定义像素值
height	组件的高度	自由定义像素值
data	组件的数据配置信息	一般配置为静态数据，按如下格式实现 { type: 0, // 数据类型，静态数据 value: '单行文本框', // 数据值（以单行文本框为例） formatter: undefined, // 数据格式化方法 }
events	组件的事件配置	[]
option	除通用属性外，组件的自身的配置信息	Object 类型。数据结构由组件自由定义

开发方式

自定义组件的开发方式完全对齐平台组件，减少在开发这两种组件时的心智负担。

为避免自定义组件和平台组件的 name 属性冲突，自定义组件需要统一使用 **YUN_DA **作为前缀。

组件配置文件

import thumbnail from './image.png'

// 组件支持的触发事件的类型
export const triggers = {
    click: 'click',
    mouseIn: 'mouseover',
    mouseOut: 'mouseOut',
    dataUpdate: 'dataUpdate',
    dblclick: 'dblclick',
}

// 组件支持的触发事件的定义
const triggerConfig = [
    {
        name: triggers.click,
        label: '点击',
    },
]

// 组件的基本信息
export const config = {
    name: '{{projectName}}',
    type: 'custom',
    subType: '',
    triggers: triggerConfig,
    actions: [],
}

// 组件的默认配置
export const defaultProps = {
    title: '自定义组件',
    left: 0,
    top: 0,
    width: 450,
    height: 300,
    group: '',
    display: true,
    // 组件自身的配置
    option: {
        title: '这是一个标题',
        fontSize: 16,
    },
    // 数据
    data: {
        type: 0,
        value: { value: 100 },
        formatter: '',
    },
    // 事件
    events: [],
}

组件开发

<template>
  <div class="container" :style="props.styleProps">
    <span class="title" :style="titleStyle">{{ props.option.title }}</span>
    <div class="card">
      <button type="button" class="custom-button" @click="count++">
        当前记录数 {{ count }}
      </button>
      <p class="description">
        这是一个用于计数的按钮，点击会增加计数
      </p>
    </div>
  </div>
</template>

<script setup>
import { computed, ref, watch } from 'vue';

defineOptions({
  name: "VueButton"
})

const props = defineProps({
  data: {
    type: Object,
    default: () => ({ value: 0 }),
  },
  styleProps: {
    type: Object,
    default: () => ({}),
  },
  option: {
    type: Object,
    default: () => ({ title: "", fontSize: 16 }),
  }

})
const count = ref(props.data.value)

const titleStyle = computed(() => ({ fontSize: props.option.fontSize + 'px' }))

watch(() => props.data, (newValue) => {
  count.value = newValue.value
},{
  deep: true
})

defineExpose({
  count
})
</script>

<style  scoped>
</style>

自定义组件除了会接收特定的 props 外，与平常开发一个 VUE 组件基本一致。

组件配置表单

<!-- 文字配置 -->
<template>
    <div>
        <!-- <el-collapse accordion> -->
            <el-collapse-item title="标题设置" name="title">
                <el-form-item label="标题内容">
                    <el-input v-model="main.activeOption.title"  />
                </el-form-item>
                <el-form-item label="字体大小">
                    <el-input-number v-model="main.activeOption.fontSize" />
                </el-form-item>
            </el-collapse-item>
       <!-- </el-collapse> -->
    </div>
</template>

<script setup>
import { inject } from 'vue';

const main = inject('main')

</script>

<style  scoped>
</style>

自定义组件表单的开发需要遵循以下的规则。

1. 使用 element-plus 作为表单组件库，开发自定义组件的配置表单。
2. 表单的数据通过 inject 的方式注入。表单项通过 v-model 绑定到注入的 main 数据上。

组件导入

// index.js
import configForm from './config-form.vue'
import { config, defaultProps } from './config.js'
import VueButton from './vue-button.vue'

VueButton.config = config
VueButton.defaultProps = defaultProps
VueButton.configForm = configForm

export default VueButton

需要按照以上方式，将组件数据统一导出

注意事项

- 不建议使用全局对象，容易影响其他组件，建议定义在当前组件的作用域下。
- 不建议在组件中引全局 css 样式表，以免造成样式污染。

预览

执行以下命令，可以在本地对自定义组件进行调试预览。

yarn dev

此外，本地开发同样支持可视化配置，配置表单由 config-form.vue 中定义。

构建

执行以下命令，可以在本地对自定义组件进行打包构建，并生成自定义组件压缩包。

yarn package

自定义组件管理平台

通过云搭可视化平台的自定义组件管理界面，可以实现自定义组件的管理。

新建自定义组件

组件标识： 组件的唯一标识，即初始化组件时的项目名称。组件标识全局唯一，不允许重复。

显示名称： 组件在画布中的显示名称

组件包： 通过 yarn package 生成的组件压缩包

---

更新自定义组件

升级自定义组件时，除了需要上传新的组件包之外，还需要更新组件的版本号信息。

注意，组件的版本号不允许重复。

下载

点击下载，可以下载当前最新版本的组件包。组件包中包含全部的项目文件，解压后安装依赖即可运行。

删除

点击删除按钮会删除当前自定义组件。需要注意的是，如果当前组件已经在项目中使用了，不要删除自定义组件，否则会导致自定义组件渲染失败。

使用自定义组件

自定义组件在组件库中，是一个单独的分组，点击对应的自定义组件，即可将组件添加到画布中。

与平台组件相同，自定义组件也支持相关的可视化配置能力，包括属性、数据、事件等的配置。