@cloudbase/weda-ui 3.5.2-mp → 3.5.3

package/README.md

@@ -1 +1,227 @@
-# mp
+# 腾讯云微搭低代码-官方组件库
+
+包含微搭低代码平台基础的源码组件和基于源码组件开发的低码组件。
+
+微搭组件库使用各平台/框架标准的组件格式，通过类型文件描述好组件的行为、出参、入参及元数据等信息和微搭平台做对接。当前支持在小程序和 web 平台上使用。
+
+**多平台原生实现**
+
+为了保证良好的性能，当前微搭平台没有对小程序和 web 做跨端的自动适配。目前采用多平台原生实现。
+
+## 项目目录
+
+```
+.
+├── .storybook              # storybook 配置目录
+├── cloudbaserc.json        # 组件库配置
+├── lowcode-comps           # 低码组件内容
+└── src
+    ├── test                # 测试目录
+    ├── configs             # 组件类型声明目录
+    │   ├── actions         # 组件库方法类型声明
+    │   ├── components      # 组件类型声明
+    │   └── index.ts        # 组件类型声明入口
+    ├── mp                  # 小程序组件
+    │   ├── actions         # 小程序组件方法实现
+    │   ├── components      # 小程序组件实现
+    │   └── index.json      # 小程序组件入口
+    ├── stories             # 组件 story / 测试
+    └── web                 # web 组件
+        ├── actions         # web 组件方法实现
+        ├── components      # web 组件实现
+        └── index.js        # web 组件入口
+├── cloudbaserc.json        # 组件库配置文件
+```
+
+## 开发
+
+组件库开发前置依赖：
+
+1. 进入组件库根目录，安装依赖： `npx npm@6 i` 使用 `npm@6` 安装依赖可能会有依赖冲突问题，可以使用 `npm i --legacy-peer-deps` 来解决。用 npm@6 是为了跟构建保持一致
+2. 安装云开发命令行工具：`npm i -g @cloudbase/cli` or `yarn global add @cloudbase/cli`
+3. 登录云开发命令行：`tcb login` 并输入密码
+4. 在腾讯云微搭低码控制台创建组件库，库名应该和 cloudbaserc.json 配置的 `name` 中一致（默认是`weda`）
+
+> 下面的内容是源码组件库的开发文档，低码组件库开发请查看[lowcode-comps 下的文档](lowcode-comps/README.md)
+
+### 编写组件
+
+首先请阅读 [组件标准化开发原则](https://tapd.woa.com/TCB_new/markdown_wikis/show/#1220422223002427443)
+
+编写能在低码平台运行的组件需要各自平台的**标准组件源码**和**组件描述**。具体可参考 [实现自定义 button 组件 | 云开发 CloudBase - 一站式后端云服务](https://docs.cloudbase.net/lowcode/custom-components/quick-start/comp)
+
+#### 处理组件通用属性
+
+对于每个组件，除了自己定义的属性生效外，在微搭平台运行时有可能会有些公共属性从平台传入。对于小程序平台组件默认情况下不需要处理这些通用属性，对于 react 组件可以额外的将通用的属性透传到具体实现的节点中。
+如：
+
+```js
+export default function Container({ children, events, ...args }) {
+  return <div {...args}>{children}</div>;
+}
+```
+
+公共属性包括：
+
+- className: 当用户选择了给组件添加自定义样式类时 `className` 属性会被传入，实现组件时需要注意和已有节点上的 classname 做融合。
+- style: 用户指定了样式时，该属性会被传入。会传入适应平台的内容：小程序组件中会传入普通的字符串样式；react 组件中是对象格式。
+- events: 当组件配置里申明了组件事件后，平台运行时会传入对应的事件方法，组件需要在合适的时候触发这些方法。
+
+具体的对于编写每个平台的组件时有些地方需要注意的：
+
+小程序：
+
+默认情况下，定义的[小程序组件]会有个容器节点来包裹自定义组件的内容，公共属性会自动添加到容器节点上，组件内部不用处理。有不希望组件存在容器节点的时候，可以在小程序组件构造方法里使用 `virtualHost` 选项来忽略容器节点，这时组件的内部节点将会直接暴露出来，这时候需要自行处理 `style`, `className` 等公共属性。
+
+```js
+Component({
+  options: {
+    virtualHost: true,
+  },
+  properties: {
+    className: {
+      type: String,
+      value: '',
+    },
+    style: {
+      type: String,
+      value: '',
+    },
+  },
+});
+```
+
+默认情况下，[小程序组件]的样式只受到组件内部的 wxss 的影响（详情查看[微信官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/wxml-wxss.html#%E7%BB%84%E4%BB%B6%E6%A0%B7%E5%BC%8F%E9%9A%94%E7%A6%BB))。
+当我们需要组件的样式也受外部影响时，可以在组件配置文件里增加 `styleIsolation` 配置:
+
+```json
+{
+  "component": true,
+  "styleIsolation": "shared"
+}
+```
+
+React:
+
+```js
+export default function Container({ children, events, ...args }) {
+  return (
+    <div onClick={events.tap} {...args}>
+      {children}
+    </div>
+  );
+}
+```
+
+#### 编写组件描述文件
+
+当前编写的组件都是各个平台的标准组件，他们和微搭低码平台需要一个配置来互相连接起来。
+
+组件配置默认存放在 `src/configs` 目录下。
+
+#### 组件代码模版生成
+
+可以通过 `npm run new` 生成上述文件
+
+### 调试组件库
+
+#### 本地预览
+
+对于 web 组件，我们在模板中集成了 [storybook] 的使用环境。编写 [story] 即可简单的在本地预览组件效果。具体步骤：
+
+1. 编写 [story]，story 是 storybook 的组件状态单元，描述了组件在一组特定状态下的行为。
+2. 当你为组件编写了足够多的用例后，你可以运行 `npm run storybook` 命令来互动预览本地组件。
+
+#### 应用编辑器中调试 web 组件
+
+如果 web 端的组件依赖运行态环境才能预览实际效果，可以在应用编辑器中预览
+
+[如何在应用编辑器中直接调试本地官方组件](https://tapd.woa.com/TCB_new/markdown_wikis/show/#1220422223002491961)
+
+#### 调试小程序组件
+
+如果要测试组件小程序端的效果, 可执行`tcb lowcode publish` 发布到自己账号下，然后新建一个应用来测试
+
+### 组件自动化测试
+
+#### 单元测试
+
+微搭官方组件库需要单元测试覆盖率达到 80% 以上才能发布，我们集成进了 jest 和 小程序模拟器来协助组件的多端测试。
+
+编写完测试用例后运行 `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/>
+
+#### E2E 测试
+
+组件最终使用过程中因为有构建代码生成和运行、编辑态代码等外部因素，容易出现开发没问题，发布之后才发现问题。而且现网用户用法千奇百怪，一些非预期用法也可能会新版本发布后出现问题。所以用配合 render 使用 E2E 自动化测试，以用户通过编辑器生成的 CALS 和组件 dependencies 作为输入，渲染输出可以执行的应用，以覆盖最终用户态的状态。
+
+E2E 测试采用 Cypress 来进行，相比 Jest 模拟 dom，更适合对实际的样式和运行效果进行测试，推荐复杂一点的组件都要写 E2E 测试。
+
+请参考 [组件库 E2E 测试](https://tapd.woa.com/TCB_new/markdown_wikis/show/#1220422223002369725) 和 [测试用例创建指北](https://tapd.woa.com/TCB_new/markdown_wikis/show/#1220422223002370781)
+
+- 执行 `npm run test:e2e-component` 可以执行组件级别的 E2E 测试
+- 执行 `npm run test:manual-e2e-cals` 可以手动可视化运行应用级别的 E2E 测试
+
+### 编写组件文档
+
+组件库对外的文档统一发布技术文档站：https://docs.cloudbase.net/lowcode/components/
+
+组件上线前需要提前准备好文档，具体可以参考 https://tapd.woa.com/TCB_new/markdown_wikis/show/#1220422223002472151
+
+研发同学可以在代码仓库中编写代码的同时进行文档的编写，文档放置在 `src/docs/compsdocs/` 目录中
+
+完整的文档示例可参考 [按钮组件文档](https://docs.cloudbase.net/lowcode/components/wedaUI/src/docs/compsdocs/show/WdButton) ，文档源码存放在 `/src/docs/compsdocs/show/WdButton.mdx`
+
+### 发布组件库
+
+#### 个人账号
+
+组件开发完成后，提交组件到微搭低代码平台，该操作会将组件发布在自己的个人账号下，可以在应用中预览
+
+```
+tcb lowcode publish
+```
+
+然后进入到编辑器的组件库列表中，再次点击发布，即可在自己的账号下的应用中使用
+
+#### 正式发布
+
+如果需要发布官方组件库，需要在提交 MR 通过后，通过流水线发布 <http://tencent.coding.woa.com/p/CloudBase/ci/job/292970/build/current>
+
+## 常见问题
+
+- 办公网络下执行 `tcb lowcode publish` 出现网络异常报错：建议切换 iOA 到 PAC 模式
+
+## 参考信息
+
+组件开发更多信息请[参考文档](https://docs.cloudbase.net/lowcode/custom-components/quick-start/comps.html)。
+
+### 编辑器协议机制
+
+- [组件内模板机制](https://tapd.woa.com/TCB_new/markdown_wikis/show/#1220422223002353133) :组件可自带默认结构、属性、事件
+- [单组件升级机制](https://tapd.woa.com/TCB_new/markdown_wikis/show/#1220422223002411487) : 针对不再兼容的组件可以引导进行迁移
+- [编辑器检查机制](https://tapd.woa.com/TCB_new/markdown_wikis/show/#1220422223002459983) : 可在发布应用前进行检查
+- [样式配置属性屏蔽 (inlineStyleForm)](https://tapd.woa.com/TCB_new/markdown_wikis/show/#1220422223002470249) :组件可以屏蔽无关样式配置
+- [右侧面板提示 (panelTips)](https://tapd.woa.com/TCB_new/markdown_wikis/show/#1220422223002460139) : 可在右侧编辑区提示相关信息
+- [组件相对位置限制 (positionConstraint)](https://tapd.woa.com/TCB_new/markdown_wikis/show/#1220422223002466153):组件可以针对可以放入的组件进行限制
+- [自定义组件 id 名 (componentName)](https://tapd.woa.com/TCB_new/markdown_wikis/show/#1220422223002474643)
+- [搜索关键词 (keyWords)](https://tapd.woa.com/TCB_new/markdown_wikis/show/#1220422223002460167)
+- [微搭编辑器组件显示隐藏](https://tapd.woa.com/TCB_new/markdown_wikis/show/#1220422223002271581)
+
+### 运行时框架接口
+
+如果在组件中使用低码应用运行时框架提供的工具方法或者数据源相关能力的时候，可参考 [API 列表](https://docs.cloudbase.net/lowcode/api/api-referrence)
+
+### 其他
+
+- [腾讯云微搭低代码](https://cloud.tencent.com/product/weda)
+- [小程序组件](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/)
+- [react](https://reactjs.org/)
+- [storybook](https://storybook.js.org/)
+- [story](https://storybook.js.org/docs/react/get-started/whats-a-story)

package/dist/configs/actions/showMessage.json

@@ -0,0 +1,45 @@
+{
+    "$schema": "https://comp-public-1303824488.cos.ap-shanghai.myqcloud.com/schema/lcds_action.json",
+    "data": {
+        "properties": {
+            "title": {
+                "title": "标题",
+                "type": "string",
+                "default": "提示的内容"
+            },
+            "icon": {
+                "title": "图标",
+                "type": "string",
+                "default": "success",
+                "x-component": "radio",
+                "enum": [
+                    {
+                        "label": "success",
+                        "value": "success"
+                    },
+                    {
+                        "label": "loading",
+                        "value": "loading"
+                    },
+                    {
+                        "label": "error",
+                        "value": "error"
+                    },
+                    {
+                        "label": "none",
+                        "value": "none"
+                    }
+                ]
+            },
+            "duration": {
+                "title": "提示的延迟时间",
+                "type": "number",
+                "default": 1500
+            }
+        }
+    },
+    "meta": {
+        "title": "showMessage",
+        "description": "信息提示"
+    }
+}

package/dist/configs/actions/showModal.json

@@ -0,0 +1,69 @@
+{
+    "$schema": "https://comp-public-1303824488.cos.ap-shanghai.myqcloud.com/schema/lcds_action.json",
+    "data": {
+        "properties": {
+            "title": {
+                "title": "标题",
+                "default": "弹窗标题",
+                "x-props": {
+                    "data-hidebind-variable": true
+                },
+                "type": "string"
+            },
+            "content": {
+                "title": "内容",
+                "default": "请输入弹窗内容",
+                "x-props": {
+                    "data-hidebind-variable": true
+                },
+                "type": "string"
+            },
+            "showCancel": {
+                "title": "是否显示取消按钮",
+                "type": "boolean",
+                "x-props": {
+                    "data-hidebind-variable": true
+                },
+                "default": true
+            },
+            "cancelText": {
+                "type": "string",
+                "title": "取消按钮的文字",
+                "description": "最多 4 个字符",
+                "x-props": {
+                    "data-hidebind-variable": true
+                },
+                "default": "取消"
+            },
+            "cancelColor": {
+                "title": "取消按钮的文字颜色",
+                "type": "color",
+                "x-props": {
+                    "data-hidebind-variable": true
+                },
+                "default": "#000000"
+            },
+            "confirmText": {
+                "type": "string",
+                "title": "确认按钮的文字",
+                "x-props": {
+                    "data-hidebind-variable": true
+                },
+                "description": "最多 4 个字符",
+                "default": "确认"
+            },
+            "confirmColor": {
+                "title": "确认按钮的文字颜色",
+                "type": "color",
+                "x-props": {
+                    "data-hidebind-variable": true
+                },
+                "default": "#576B95"
+            }
+        }
+    },
+    "meta": {
+        "title": "showModal",
+        "description": "showModal 弹窗"
+    }
+}

package/dist/configs/actions/showToast.json

@@ -0,0 +1,50 @@
+{
+    "$schema": "https://comp-public-1303824488.cos.ap-shanghai.myqcloud.com/schema/lcds_action.json",
+    "data": {
+        "properties": {
+            "title": {
+                "title": "标题",
+                "type": "string",
+                "default": "提示的内容",
+                "x-props": {
+                    "data-hidebind-variable": true
+                }
+            },
+            "icon": {
+                "title": "图标",
+                "type": "string",
+                "default": "success",
+                "x-component": "radio",
+                "x-props": {
+                    "data-hidebind-variable": true
+                },
+                "enum": [
+                    {
+                        "label": "success",
+                        "value": "success"
+                    },
+                    {
+                        "label": "loading",
+                        "value": "loading"
+                    },
+                    {
+                        "label": "none",
+                        "value": "none"
+                    }
+                ]
+            },
+            "duration": {
+                "title": "提示的延迟时间",
+                "type": "number",
+                "default": 1500,
+                "x-props": {
+                    "data-hidebind-variable": true
+                }
+            }
+        }
+    },
+    "meta": {
+        "title": "showToast",
+        "description": "自定义提示"
+    }
+}

package/dist/configs/components/auth.json

@@ -0,0 +1,17 @@
+{
+    "$schema": "https://comp-public-1303824488.cos.ap-shanghai.myqcloud.com/schema/lcds_component.json",
+    "data": {
+        "properties": {}
+    },
+    "events": [],
+    "meta": {
+        "name": "Auth",
+        "title": "登录",
+        "description": "登录组件",
+        "icon": "./auth.svg",
+        "category": "开放能力",
+        "categoryOrder": 1,
+        "componentOrder": 1,
+        "visible": []
+    }
+}

package/dist/configs/components/button.d.ts

@@ -0,0 +1,76 @@
+/// <reference types="react" />
+import { Static } from '../type-utils';
+import type { Simplify } from 'type-fest';
+declare const data: import("@sinclair/typebox").TObject<{
+    text: import("@sinclair/typebox").TString;
+    size: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<"default" | "mini" | "large">>;
+    type: import("@sinclair/typebox").TUnsafe<"primary" | "default" | "warn">;
+    loading: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    disabled: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    formType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<"button" | "submit" | "reset">>;
+    openType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<"" | "contact" | "share" | "launchApp" | "openSetting" | "feedback">>;
+    contentSlot: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<import("react").ReactNode>>;
+    categoryId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TNumber>>;
+    sessionFrom: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    sendMessageTitle: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    sendMessagePath: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    sendMessageImg: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    showMessageCard: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    appParameter: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type DataType = Simplify<Static<typeof data>>;
+declare const config: {
+    readonly $schema: "https://comp-public-1303824488.cos.ap-shanghai.myqcloud.com/schema/lcds_component.json";
+    readonly data: import("@sinclair/typebox").TObject<{
+        text: import("@sinclair/typebox").TString;
+        size: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<"default" | "mini" | "large">>;
+        type: import("@sinclair/typebox").TUnsafe<"primary" | "default" | "warn">;
+        loading: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        disabled: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        formType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<"button" | "submit" | "reset">>;
+        openType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<"" | "contact" | "share" | "launchApp" | "openSetting" | "feedback">>;
+        contentSlot: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnsafe<import("react").ReactNode>>;
+        categoryId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TNumber>>;
+        sessionFrom: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        sendMessageTitle: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        sendMessagePath: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        sendMessageImg: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        showMessageCard: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        appParameter: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>;
+    readonly events: readonly [{
+        readonly title: "点击";
+        readonly name: "tap";
+    }, {
+        readonly title: "获取手机号";
+        readonly name: "getPhoneNumber";
+        readonly 'x-platforms': readonly ["MP"];
+    }, {
+        readonly title: "打开客服会话";
+        readonly name: "contact";
+        readonly 'x-platforms': readonly ["MP"];
+    }, {
+        readonly title: "获取用户信息";
+        readonly name: "getUserInfo";
+        readonly 'x-platforms': readonly ["MP"];
+    }, {
+        readonly title: "打开App";
+        readonly name: "launchApp";
+        readonly 'x-platforms': readonly ["MP"];
+    }, {
+        readonly title: "打开授权设置";
+        readonly name: "openSetting";
+        readonly 'x-platforms': readonly ["MP"];
+    }];
+    readonly meta: {
+        readonly name: "Button";
+        readonly title: "按钮";
+        readonly description: "按钮组件";
+        readonly icon: "//imgcache.qq.com/qcloud/lowcode/static/ide/left-material-icon/Button.svg";
+        readonly category: "展示";
+        readonly categoryOrder: 1;
+        readonly componentOrder: 1;
+        readonly visible: readonly [];
+    };
+};
+export default config;