快速开始

本文将介绍如何使用easyv官方组件工具包easyv-cli进行开发，它提供一种无需配置的现代化构建方式来快速的进入开发步骤。我们以 React 创建一个可以配置大小和颜色的文字组件为例，下面就开始吧。

说明：开发组件需要具备一些基本的前端知识，比如js、css等。

如果开发的是React组件，需要具备React的基础知识

如果开发的是Vue组件，需要具备Vue的基础知识。

0.环境准备

工具包运行于Node环境，推荐使用最新的node版本，最低要求 Node >= 14 的版本，如果您没有安装NodeJS，可以进入NodeJS官网下载并安装。安装成功后，在命令行操作界面执行node -v和npm -v命令（Mac在terminal中执行，Windows可中可在git bash或powershell中执行），查看Node和npm版本。安装成功后即可开始安装easyv开发者工具了。

如果本机已经存在Node且不想升级或降级，推荐安装nvm来管理多个Node版本管理

1. 安装工具

npm i -g @easyv/cli --registry=https://registry.npmmirror.com

安装完成后，执行 easyv --version 可查看工具包的版本。

如果你已经安装过旧版的 @easyv/cli，执行上述命令将升级到最新版

2. 创建项目

easyv create my-components

执行该命令后，会在命令行所在的目录创造一个文件夹，在安装的最后，您可以选择一种感兴趣的模版，并定义您的组件名称。

2.1.选择框架

目前已支持基于React/Vue的开发方式

如果您在选择框架时遇到依赖缺失的报错，可以通过npm i -g @easyv/react-component-builder或 npm i -g @easyv/vue-builder安装对应框架的构建包。正常情况下，第一次创建项目时会自动安装对应构建包。

2.2.输入组件名称

输入组件名称(以字母开头，数字+字母来定义，加上特殊的前缀，比如公司首字母或个人名称或其他有意义的标识，防止与已有的组件发生名称冲突，例如easyv_text)和别名（中文名，用于组件列表中显示，也需要是平台不重复的名称）

2.3.选择组件模板

若选择了vue框架，模板选项只会有"Vue演示"的选项；React框架下，模板选项有基础的React组件模板，和3D组件模板，如需开发3D组件，可选择"Three Component"模板

至此项目就创建完成了，并初始化创建了一个我的文字组件。

注意:

在window环境执行easyv命令可能会提示ENOENT相关命令不存在，请检查系统环境变量，确保npm的全局文件夹路径被加入到Path中，查看路径命令 npm config get prefix

3. 启动项目

成功创建项目后，输入以下命令来启动项目，控制台上也会输出启动环境的命令提示。为了保持与平台上运行效果一致，请使用 Chrome >= 65 版本进行开发

cd my-components
easyv dev

开发环境默认运行在3005端口，在浏览器中输入地址，打开后是一个组件列表页面，该页面会列出组件目录中的所有组件，点击相应的组件进入开发界面。

我们在创建项目时根据模版生成了一个名称为 我的文字 的组件，蓝色线框展示组件的渲染效果，右侧显示组件的配置和数据信息，每个组件都有位置和尺寸，目前我们还没有任何配置项。

底部的 home按钮返回组件列表，home边上展示组件的名称、ID和版本号，他们被定义在配置文件的base属性中。

4. 文件目录规范

我们先来看一下我们刚刚创建的项目文件目录结构是怎么样的。

所有的组件文件都放在src/components目录下，一个项目目录下可以有多个组件，组件以文件夹为单位，通过以下命令可在项目中新增一个组件：

easyv generate

以组件文件夹（easyv_text）为例，在开发组件时，请遵循以下规范：

- 每个组件必须包含一个index入口文件

- 每个组件必须有config目录，该目录下存放组件的配置文件

.
├── package.json                                    // easyv打包配置
├── src
│   └── components                                  // 组件目录
│       ├── easyv_text                              // 第一个组件
│				│		├── assets                              // 存放静态资源
│				│		├── styles                              // 存放样式文件
│       │   ├── config                              // 组件配置文件目录
│       │   │   ├── main.data.json                  // 数据文件
│       │   │   └── main.json                       // 配置文件
│       │   └── index.jsx                           // 组件入口
│       └── easyv_text1                             // 第二个组件
│						├── assets
│						├── styles 
│           ├── config
│           │   ├── main.data.json
│           │   └── main.json
│           └── index.jsx
└── package-lock.json

package.json: 当前项目名称、版本等基本信息，以及服务器地址、依赖包等内容。
assets: 存放图片、视频、音频等静态资源。
styles: 存放样式文件，应为不需要通过控件来动态配置的静态样式。
index.jsx: 入口文件，接收传入的配置和数据。
main.data.json: 组件的默认展示数据和字段映射，详情查看这里。
main.json: 定义组件的基本信息、配置项、回调、交互等，详情查看这里。

config文件夹下的配置文件类型可以是json，也可以是js。新建项目默认为json，json文件结构更加清晰简洁，js文件可以添加注释，书写js变量、函数等，你可以根据自己的需要选择文件类型。

5. 添加配置

项目已经创建，文件目录结构也已经清楚了，下一步，我们怎么修改组件的文字大小和颜色？

为了让组件的文字大小和颜色支持用户可以动态配置，而不仅仅只是在 index.jsx 文件中写个固定的行内样式，所以必须把这样的内容放在配置项中，这样就可以实现用户自定义样式的需求。

我们需要修改config/main.json文件中的 configuration 字段，更详细的配置可参考配置文件一节。

注意：为方便注释，文档中部分配置文件的示例代码使用js(jsx)文件类型，如需使用这些配置文件的代码片段，请将对应json文件的后缀改为js(jsx)，或者使用折叠的"JSON示例"，往后不再赘述。

export default{
	...
  configuration: [
    {
      name: "fontSize",						//控件id,需保证在当前数组的唯一性
      displayName: "文本大小",		  //控件名称，在页面上显示
      type: "number",							//控件类型
      value: 16										//控件默认值
    },
    {
      name: "color",
      displayName: "文本颜色",
      type: "color",
      value: "#00ff00"
    }
  ]
}

{
  ...
  "configuration": [
    {
      "name": "fontSize",						
      "displayName": "文本大小",			
      "type": "number",							
      "value": 16										
    },
    {
      "name": "color",
      "displayName": "文本颜色",
      "type": "color",
      "value": "#00ff00"
    }
  ]
}

上面的代码给configuration添加了两个配置对象，第一个对象使用了数值输入框控件（type 为 number），定义了名为[文本大小]的配置项 (name为该配置的英文名，需要保证当前数组的唯一，displayName为显示的中文名) ，意思是这个文本大小值默认为16。第二个对象使用了颜色选择器控件（type 为 color），定义了名为[文本颜色]的配置项，意思是颜色的默认值为绿色。

很简单吧，现在我们已经添加好了配置项，你可以任意的调整颜色值和字体大小，只是左边主视图的展示效果还没有对应的调整，接着往下看。

6. 关联配置

添加好配置项以后，在组件文件夹下找到入口文件index.jsx，我们先看一下原来的代码

import React from 'react';
import css from './styles/index.module.css';

export default function (props) {
  const { left, top, width, height, id, data } = props;

  // 自定义逻辑
  const styles = {
    position: 'absolute',
    left, 
    top, 
    width, 
    height,
    textAlign: 'center'
  };

  /**
   * 固定格式: 返回的div必须有className/id属性
   */
  
  return (
    <div className="__easyv-component" style={styles} id={id}>
      <img src={require('./assets/logo.png')} />
      <div className={css.title}>{data[0].text}</div>
    </div>
  );
}

原来的模板代码逻辑比较简单，引入了以下几个props

id: 组件的id，每个组件都有自己的唯一id，该id是平台自增生成的，是一个number类型，主要注意的是 该id需要在根节点添加 id={id}的属性，用于平台的查找，不添加，则可能导致不可预期的错误
width: 组件宽度，number类型
height: 组件高度，number类型
left: 距离画布的左边距，number类型
top: 距离画布的右边距，number类型
data: 组件的数据，默认静态数据定义在 main.data.json 文件中，后面还会继续讲到

关于更详细的平台提供给组件的props有哪些，可以查看入口文件

那么我们刚刚修改的配置数据怎么引入呢？也是一样，从props中取，名字跟 main.json中的配置文件一样，叫configuration。只不过有点不同的是，配置文件中，我们需要定义type、displayName等一系列的schema数据，但在平台传给组件的时候，会把它经过一层处理，处理成一个「key: value」 这种对象的形式。具体可以打印一下看看。

如果接收到的configuration的target还是数组，请确认你的开发者工具 @easyv/react-component-builder和@easyv/vue-builder是最新版本，如果不是可以npm i -g @easyv/react-component-builder或 npm i -g @easyv/vue-builder更新到最新。如果是本地部署的客户，发布到平台，发现失效，请确保平台的版本 >= 3.15.0。

看到上面打印的，你可能会有几个疑问。

为什么是一个 Proxy对象？
为什么有一个chart值？

这里解释一下

1.configuration 是一个 Proxy对象，只是在开发阶段，主要是为了规避一些开发者直接修改configuration做一些告警提示，真正发布组件到平台之后，还是一个普通的对象。不管是proxy对象也好，普通对象也好，都不影响你的使用，你只要把它当成一个普通的对象来使用就可以了。

2.为什么多了一个chart值，想必你在 main.json配置文件中一定注意到 width, height的配置项，这个就是props中接收到的width和height的值，但在早期版本中，我们是定义在configuration里面的，跟其他的配置对象一样定义，但后面考虑到比较繁琐，又为了兼容老的版本，所以我们把定义的width，height做了一层转换，转成原来的配置结构，经过解析之后就变成了现在你看到的样子。归结起来，你只要知道它是为了兼容老版本的就行了。你可以忽略。

接下来，我们把刚刚配置的数据添加到style中，为动态配置组件样式，删除之前定义的className，完整的代码如下

import React from "react";
import css from "./styles/index.module.css";

export default function (props) {
  const { left, top, width, height, id, data, configuration } = props;

  // 自定义逻辑
  const styles = {
    position: "absolute",
    left,
    top,
    width,
    height,
    textAlign: "center",
    fontSize: configuration.fontSize,   //值为main.js配置中的控件id
    color: configuration.color,
  };

  // 返回的根节点必须有className/id属性,并赋值为props传入的id,用于平台查找组件
  return (
    <div className="__easyv-component" style={styles} id={id}>
      <img src={require("./assets/logo.png")} />
      <div>{data[0].text}</div>
    </div>
  );
}

效果如下