@cloudbase/weda-ui v3.5.1

腾讯云微搭源码组件库

腾讯云微搭低代码平台支持你将自己的组件导入成低码平台可运行的自定义代码组件，本项目即是腾讯云微搭低代码平台的组件库模板，介绍如何编写一个可以在微搭使用的代码组件库。

当前支持小程序组件和 react 组件。

组件库

微搭组件库使用各平台/框架标准的组件格式，通过类型文件描述好组件的行为、出参、入参及元数据等信息和微搭平台做对接。

多平台原生实现

为了保证良好的性能，当前微搭平台没有对小程序和 web 做跨端的自动适配。如果希望你的组件能够运行在多端，需要自行针对小程序和 web 原生实现两套组件。

项目目录

.
├── .storybook              # storybook 配置目录
├── cloudbaserc.json        # 组件库配置
└── src
    ├── test                # 测试目录
    ├── configs             # 组件类型申明目录
    │   ├── actions         # 组件库方法类型申明
    │   ├── components      # 组件目录类型申明
    │   └── index.js        # 组件类型申明的入口
    ├── mp                  # 小程序组件
    │   ├── actions         # 小程序组件方法实现
    │   ├── components      # 小程序组件实现
    │   └── index.json      # 小程序组件入口
    ├── stories             # 组件 story / 测试
    └── web                 # web（react） 组件
        ├── actions         # web 组件方法实现
        ├── components      # web 组件实现
        └── index.js        # web 组件入口

组件库配置

当前使用 cloudbaserc.json 文件来申明组件库配置。

开发

组件库开发前置依赖：

1. 进入组件库更目录，安装依赖： npm i or yarn，使用 npm 安装依赖可能会有依赖冲突问题，可以使用 npm i --legacy-peer-deps 来解决。
2. 安装云开发命令行工具：npm i -g @cloudbase/cli or yarn global add @cloudbase/cli
3. 登录云开发命令行：tcb login 并输入密码
4. 去腾讯云微搭低码控制台创建组件库

编写组件

编写能在低码平台运行的组件需要各自平台的标准组件源码和组件描述。

通用属性

对于每个组件，除了自己定义的属性生效外，在微搭平台运行时有可能会有些公共属性从平台传入。对于小程序平台组件默认情况下不需要处理这些通用属性，对于 react 组件可以额外的将通用的属性透传到具体实现的节点中。 如：

export default function Container({ children, events, ...args }) {
  return <div {...args}>{children}</div>;
}

公共属性包括：

• className: 当用户选择了给组件添加自定义样式类时 className 属性会被传入，实现组件时需要注意和已有节点上的 classname 做融合。
• style: 用户指定了样式时，该属性会被传入。会传入适应平台的内容：小程序组件中会传入普通的字符串样式；react 组件中是对象格式。
• events: 当组件配置里申明了组件事件后，平台运行时会传入对应的事件方法，组件需要在合适的时候触发这些方法。

具体的对于编写每个平台的组件时有些地方需要注意的：

小程序：

默认情况下，定义的小程序组件会有个容器节点来包裹自定义组件的内容，公共属性会自动添加到容器节点上，组件内部不用处理。有不希望组件存在容器节点的时候，可以在小程序组件构造方法里使用 virtualHost 选项来忽略容器节点，这时组件的内部节点将会直接暴露出来，这时候需要自行处理 style, className 等公共属性。

Component({
  options: {
    virtualHost: true,
  },
  properties: {
    className: {
      type: String,
      value: '',
    },
    style: {
      type: String,
      value: '',
    },
  },
});

默认情况下，小程序组件的样式只受到组件内部的 wxss 的影响（详情查看微信官方文档)。 当我们需要组件的样式也受外部影响时，可以在组件配置文件里增加 styleIsolation 配置:

{
  "component": true,
  "styleIsolation": "shared"
}

React:

export default function Container({ children, events, ...args }) {
  return (
    <div onClick={events.tap} {...args}>
      {children}
    </div>
  );
}

运行时框架接口

如果在组件中使用低码应用运行时框架提供的工具方法或者数据源相关能力的时候，可以。。。 //TODO

组件描述

当前编写的组件都是各个平台的标准组件，他们和微搭低码平台需要一个配置来互相连接起来。

组件配置默认存放在 src/configs 目录下。

具体编写配置时可以使用 schema: https://comp-public-1303824488.cos.ap-shanghai.myqcloud.com/schema/lcds_component.json

一个示例：

{
  "$schema": "https://comp-public-1303824488.cos.ap-shanghai.myqcloud.com/schema/lcds_component.json",
  "data": {
    "properties": {
      "text": {
        "title": "文本内容",
        "type": "string",
        "default": "请在此输入内容..",
        "description": "文本内容"
      },
      "maxLines": {
        "title": "最大显示行数",
        "type": "number",
        "description": "显示最大行数",
        "default": 2
      },
      "space": {
        "title": "连续空格",
        "type": "boolean",
        "description": "是否显示连续空格",
        "default": false
      }
    }
  },
  "events": [{ "title": "点击", "name": "tap" }],
  "meta": {
    "title": "文本",
    "description": "文本内容",
    "category": "基础"
  }
}

组件编写完成后，在腾讯云微搭低代码编辑器调试组件库，在当前目录执行：

tcb lowcode debug

组件开发完成后，提交组件到微搭低代码平台：

tcb lowcode publish

组件开发更多信息请参考文档。

事件触发与监听

以上一个章节 组件描述 里声明的 tap 事件为例, 演示如何在源码里触发事件。

• 在 web 组件内部触发事件

export default function Container({ children, events, ...args }) {
  function onClick(e) {
    /**
     * 事件数据, 开发者自定义
     * 监听者可以在回调函数的 event.detail 获取到
     */
    const detail = {
      value: e.target.value,
    };
    /**
     * 事件配置, 目前只有 originEvent
     * 监听者可以在回调函数的 event.originEvent 获取到
     */
    const option = {
      originEvent: e,
    };
    events.tap(detail, option);
  }

  return (
    <div onClick={onClick} {...args}>
      {children}
    </div>
  );
}

• 在小程序组件内部触发事件

  //TODO

• 在低码编辑器里绑定事件

export function handleEvent({ event, data }) {
  // 组件内部抛出的 detail
  console.log(event.detail);
  // 组件内部抛出的 option.originEvent
  console.log(event.originEvent);
}

指定组件入口

指定组件的类型声明入口

使用通用的 import 和 export，在 configs/index.js 里指定入口。

指定组件的 web 实现入口

使用通用的 import 和 export，在 web/index.js 里指定入口。

指定组件的小程序实现入口

使用组件名和组件路径的方式，在 mp/index.json 里指定入口。

• 以小程序自定义组件的方式，实现组件

// 复杂写法, 不推荐
{
  "components": {
    "Button": {
      "type": "custom",
      "path": "components/button/index"
    }
  }
}
// 简单写法, 推荐
{
  "components": {
    "Button": "components/button/index"
  }
}

• 以小程序原生组件的方式，关联组件

{
  "components": {
    "Slot": {
      "type": "native",
      "path": "slot"
    }
  }
}

其他

为了让你的组件开发工作更加便捷和稳定，我们集成了 storybook 及组件测试工具来辅助组件的开发。虽然 storybook 和组件测试不是必须的，我们仍然建议你使用他们来保证组件始终工作正常。

使用 storybook 本地开发

对于 web 组件，我们在模板中集成了 storybook 的使用环境。编写 story 即可简单的在本地预览组件效果。具体步骤：

1. 编写 story，story 是 storybook 的组件状态单元，描述了组件在一组特定状态下的行为。
2. 当你为组件编写了足够多的用例后，你可以运行 npm run storybook 命令来互动预览本地组件。

调试预览小程序组件

对于小程序组件，我们不能直接在浏览器中去预览调试。组件编写完成后需要运行 tcb lowcode debug 打开组件编辑器，通过组件编辑器中 IDE 预览功能来进行微信开发者工具和手机的真实预览。

组件测试

我们建议你为你的定义组件编写必要的测试。我们集成进了 jest 和 小程序模拟器来协助组件的多端测试。 对于 web 组件我们建议利用编写的 story 来进行组件测试。

编写完测试用例后运行 npm test 执行测试命令。

组件测试请参考：

• https://github.com/wechat-miniprogram/miniprogram-simulate
• https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/unit-test.html
• https://jestjs.io/docs/snapshot-testing
• https://storybook.js.org/tutorials/intro-to-storybook/react/en/test/