:::danger 注意：文档尚未完成，可参考开发指南与实验性功能。

:::

简介

CoCo 编辑器有自定义控件功能，开发者可以使用 JavaScript 编写自己的控件，实现特定的功能。

比如实现密码输入框、多行文本输入框、查询天气功能等。

控件完成后也可以投稿至控件商城，参考 控件商城上架标准

自定义控件分为两种类型：

:::color3

可见控件（VisibleWidget）

也就是界面控件，可在舞台显示，一般用于用户交互，比如按钮、输入框、文本等。

文件后缀为 .jsx，比如 text.jsx。

:::

:::color1

不可见控件(InvisibleWidget)

这类控件在舞台不可见，一般用于提供系统（原生）能力，所以也称为功能型控件，比如照相机控件、音频控件等。

文件后缀为.js，比如camera.js。

:::

一个完整的控件大致可用下图概括：

控件类型定义

:::color1 注：字段后标有“*”为可选选项

:::

控件实体定义是一个字典对象，以键值对的方式定义了控件的功能

const types = {
  type: "MY_WIDGET",
  icon: "https://waddle.coco-central.cn/static/img/logo/logo-white.svg",
  title: "我的控件",
  isInvisibleWidget: true,
  isGlobalWidget: true,
  platforms: ["web", "android", "ios"],
  properties: [],
  methods: [],
  events: [],
};

type

定义控件类型名称，作品唯一，标识不同控件

值类型：字符串

icon

定义控件图标，显示在编辑器中

值类型：字符串

title

定义控件名称，显示在编辑器中

值类型：字符串

docs*

isInvisibleWidget

定义是否为不可见控件

值类型：布尔值

isGlobalWidget

定义是否为全局控件

值类型：布尔值

当 isInvisibleWidget 为 false 时，本选项值必须为 false

platforms*

定义控件可用平台，不包含”web”时，编辑器调试会显示“控件暂不支持网页端运行，请打包后使用”的提示，具体是否可用取决于控件的代码实现，而非该选项

值类型：列表

缺省值：["web", "android", "ios"]

properties

定义控件的包含的属性，列表的每一项是字典

值类型：列表

const types = {
  ...
  properties: [
    {
      key: 'property1',
      label: '属性1',
      valueType: 'string',
      editorType: 'string',
      checkType: 'string',
      defaultValue: 'Hello, world!',
      blockOptions: {
        generateBlock: true,
      },
    },
  ],
  ...
};

key

定义控件属性名称，控件唯一，标识不同属性

值类型：字符串

label

定义控件属性标签，显示在积木和属性面板中

值类型：字符串

valueType

定义控件属性数据类型

值类型：字符串或多个下列参考值组成的列表

editorType*

定义控件属性面板中编辑器的类型

值类型：字符串

checkType*

定义控件属性的类型检查

值类型：字符串或多个下列参考值组成的列表

defaultValue

定义控件属性默认值

值类型：valueType

blockOptions*

定义属性，属性积木选项

值类型：字典

generateBlock*

定义是否生成设置、获取属性的积木

值类型：布尔值

method

定义控件的包含的方法，列表的每一项是字典

值类型：列表

const types = {
  ...
  methods: [
    {
      key: 'method1',
      label: '方法1',
      valueType: 'string',
      params: [
        {
        }
      ],
      blockOptions: {
        color: '#FFBB55',
        generateBlock: true,
        space: 16,
      },
    },
  ],
  ...
};

blockOptions*

定义属性，属性积木选项

值类型：字典

color*

定义积木颜色

缺省值：”#FFBB55”

generateBlock*

定义是否生成设置、获取属性的积木

值类型：布尔值

space*

定义在积木盒中与下一块积木的间距

值类型：数字

缺省值：16