diff --git a/docs/config/navbar.js b/docs/config/navbar.js index efbe88ec0..0f0486398 100644 --- a/docs/config/navbar.js +++ b/docs/config/navbar.js @@ -21,6 +21,12 @@ module.exports = { position: 'left', label: 'API', }, + { + type: 'doc', + docId: 'specs/lowcode-spec', + position: 'left', + label: '协议', + }, { type: 'doc', docId: 'faq/index', diff --git a/docs/config/sidebars.js b/docs/config/sidebars.js index fc14767a3..e2de2d49c 100644 --- a/docs/config/sidebars.js +++ b/docs/config/sidebars.js @@ -33,6 +33,12 @@ module.exports = { dirName: 'api', }, ], + specs: [ + { + type: 'autogenerated', + dirName: 'specs', + }, + ], faq: [ { type: 'autogenerated', diff --git a/docs/docs/api/common.md b/docs/docs/api/common.md index 886ae925a..46b4d7f03 100644 --- a/docs/docs/api/common.md +++ b/docs/docs/api/common.md @@ -42,6 +42,20 @@ common.utils.startTransaction(() => { }, TransitionType.repaint); ``` +### createIntl +i18n相关工具 +*引擎版本 >= 1.0.17 +```typescript +import { common } from '@alilc/lowcode-engine'; +import enUS from './en-US.json'; +import zhCN from './zh-CN.json'; + +const { intl, getLocale, setLocale } = common.utils.createIntl({ + 'en-US': enUS, + 'zh-CN': zhCN, +}); + +``` ## designerCabin ### isSettingField 是否是 SettingField 实例 diff --git a/specs/assets-spec.md b/docs/docs/specs/assets-spec.md similarity index 94% rename from specs/assets-spec.md rename to docs/docs/specs/assets-spec.md index ab0e1abc0..5c7df0163 100644 --- a/specs/assets-spec.md +++ b/docs/docs/specs/assets-spec.md @@ -1,8 +1,12 @@ +--- +title: 《低代码引擎资产包协议规范》 +sidebar_position: 2 +--- # 《低代码引擎资产包协议规范》 -# 1 介绍 +## 1 介绍 -## 1.1 本协议规范涉及的问题域 +### 1.1 本协议规范涉及的问题域 - 定义本协议版本号规范 - 定义本协议中每个子规范需要被支持的 Level @@ -12,16 +16,16 @@ - 定义低代码资产包协议组件描述资源加载规范（A） - 定义低代码资产包协议组件在面板展示规范（AA） -## 1.2 协议草案起草人 +### 1.2 协议草案起草人 - 撰写：金禅、璿玑、彼洋 - 审阅：力皓、絮黎、光弘、戊子、潕量、游鹿 -## 1.3 版本号 +### 1.3 版本号 1.1.0 -## 1.4 协议版本号规范（A） +### 1.4 协议版本号规范（A） 本协议采用语义版本号，版本号格式为 `major.minor.patch` 的形式。 @@ -29,7 +33,7 @@ - minor 是小版本号：用于发布向下兼容的协议功能新增 - patch 是补丁号：用于发布向下兼容的协议问题修正 -## 1.5 协议中子规范 Level 定义 +### 1.5 协议中子规范 Level 定义 | 规范等级 | 实现要求 | | -------- | ------------------------------------------------------------ | @@ -37,19 +41,19 @@ | AA | 推荐规范，由低代码引擎官方插件、setter 支持。 | | AAA | 参考规范，需由基于引擎的上层搭建平台支持，实现可参考该规范。 | -## 1.6 名词术语 +### 1.6 名词术语 - **资产包**: 低代码引擎加载资源的动态数据集合，主要包含组件及其依赖的资源、组件低代码描述、动态插件/设置器资源等。 -## 1.7 背景 +### 1.7 背景 根据低代码引擎的实现，一个组件要在引擎上渲染和配置，需要提供组件的 umd 资源以及组件的`低代码描述`，并且组件通常都是以集合的形式被引擎消费的；除了组件之外，还有组件的依赖资源、引擎的动态插件/设置器等资源也需要注册到引擎中；因此我们定义了“低代码资产包”这个数据结构，来描述引擎所需加载的动态资源的集合。 -## 1.8 受众 +### 1.8 受众 本协议适用于使用“低代码引擎”构建搭建平台的开发者，通过本协议的定义来进行资源的分类和加载。阅读及使用本协议，需要对低代码搭建平台的交互和实现有一定的了解，对前端开发相关技术栈的熟悉也会有帮助，协议中对通用的前端相关术语不会做进一步的解释说明。 -# 2 协议结构 +## 2 协议结构 协议最顶层结构如下，包含 7 方面的描述内容： @@ -61,7 +65,7 @@ - setters { Array } 设计器中设置器描述协议列表 - extConfig { Object } 平台自定义扩展字段 -## 2.1 version（A） +### 2.1 version（A） 定义当前协议 schema 的版本号； @@ -69,7 +73,7 @@ | ---------- | ------ | ---------- | -------- | ------ | | version | String | 协议版本号 | - | 1.1.0 | -## 2.2 packages（A） +### 2.2 packages（A） 定义低代码编辑器中加载的资源列表，包含公共库和组件(库) cdn 资源等； @@ -81,18 +85,18 @@ | packages[].version | npm 包版本号 | String | A | 组件资源版本号 | | packages[].type | 资源包类型 | String | AA | 取值为: proCode（源码）、lowCode（低代码，默认为 proCode | | packages[].schema | 低代码组件 schema 内容 | object | AA | 取值为: proCode（源码）、lowCode（低代码） | -| packages[].deps | 当前资源包的依赖资源的唯一标识列表 | Array | A | 唯一标识为 id 或者 package 对应的值 | +| packages[].deps | 当前资源包的依赖资源的唯一标识列表 | Array | A | 唯一标识为 id 或者 package 对应的值 | | packages[].library | 作为全局变量引用时的名称，用来定义全局变量名 | String | A | 低代码引擎通过该字段获取组件实例 | -| packages[].editUrls | 组件编辑态视图打包后的 CDN url 列表，包含 js 和 css | Array | A | 低代码引擎编辑器会加载这些 url | -| packages[].urls | 组件渲染态视图打包后的 CDN url 列表，包含 js 和 css | Array | AA | 低代码引擎渲染模块会加载这些 url | +| packages[].editUrls | 组件编辑态视图打包后的 CDN url 列表，包含 js 和 css | Array | A | 低代码引擎编辑器会加载这些 url | +| packages[].urls | 组件渲染态视图打包后的 CDN url 列表，包含 js 和 css | Array | AA | 低代码引擎渲染模块会加载这些 url | | packages[].advancedEditUrls | 组件多个编辑态视图打包后的 CDN url 列表集合，包含 js 和 css | Object | AAA | 上层平台根据特定标识提取某个编辑态的资源，低代码引擎编辑器会加载这些资源，优先级高于 packages[].editUrls | | packages[].advancedUrls | 组件多个端的渲染态视图打包后的 CDN url 列表集合，包含 js 和 css | Object | AAA | 上层平台根据特定标识提取某个渲染态的资源， 低代码引擎渲染模块会加载这些资源，优先级高于 packages[].urls | | packages[].external | 当前资源在作为其他资源的依赖，在其他依赖打包时时是否被排除了(同 webpack 中 external 概念) | Boolean | AAA | 某些资源会被单独提取出来，是其他依赖的前置依赖，根据这个字段决定是否提前加载该资源 | -| packages[].loadEnv | 指定当前资源加载的环境 | Array | AAA | 主要用于指定 external 资源加载的环境，取值为 design(设计态)、runtime(预览态)中的一个或多个 | +| packages[].loadEnv | 指定当前资源加载的环境 | Array | AAA | 主要用于指定 external 资源加载的环境，取值为 design(设计态)、runtime(预览态)中的一个或多个 | | packages[].exportSourceId | 标识当前 package 内容是从哪个 package 导出来的 | String | AAA | 此时 urls 无效 | | packages[].exportSourceLibrary | 标识当前 package 是从 window 上的哪个属性导出来的 | String | AAA | exportSourceId 的优先级高于exportSourceLibrary ,此时 urls 无效 | | packages[].async | 标识当前 package 资源加载在 window.library 上的是否是一个异步对象 | Boolean | A | async 为 true 时，需要通过 await 才能拿到真正内容 | -| packages[].exportMode | 标识当前 package 从其他 package 的导出方式 | String | A | 目前只支持 `"functionCall"`, exportMode等于 `"functionCall"` 时，当前package 的内容以函数的方式从其他 package 中导出，具体导出接口如: (library: string, packageName: string, isRuntime?: boolean) => any | Promise, library 为当前 package 的 library, packageName 为当前的包名，返回值为当前 package 的导出内容 | +| packages[].exportMode | 标识当前 package 从其他 package 的导出方式 | String | A | 目前只支持 `"functionCall"`, exportMode等于 `"functionCall"` 时，当前package 的内容以函数的方式从其他 package 中导出，具体导出接口如: (library: string, packageName: string, isRuntime?: boolean) => any | Promise, library 为当前 package 的 library, packageName 为当前的包名，返回值为当前 package 的导出内容 | 描述举例: @@ -294,14 +298,14 @@ } ``` -## 2.3 components （A） +### 2.3 components （A） 定义资产包中包含的所有组件的低代码描述的集合，分为“ComponentDescription”和“RemoteComponentDescription”(详见 2.6 TypeScript 定义)： - ComponentDescription: 符合“组件描述协议”的数据，详见物料规范中`2.2.2 组件描述协议`部分； - RemoteComponentDescription 是将一个或多个 ComponentDescription 构建打包的 js 资源的描述，在浏览器中加载该资源后可获取到其中包含的每个组件的 ComponentDescription 的具体内容； -## 2.4 sort （AA） +### 2.4 sort （AA） 定义组件列表分组 @@ -310,7 +314,7 @@ | sort.groupList | String[] | 组件分组，用于组件面板 tab 展示 | - | ['精选组件', '原子组件'] | | sort.categoryList | String[] | 组件面板中同一个 tab 下的不同区间用 category 区分，category 的排序依照 categoryList 顺序排列 | - | ['通用', '数据展示', '表格类', '表单类'] | -## 2.5 plugins (AAA) +### 2.5 plugins (AAA) 自定义设计器插件列表 @@ -325,7 +329,7 @@ | plugins[].keywords | String[] | 插件检索关键字 | - | - | | plugins[].reference | Reference | 插件引用的资源包信息 | - | - | -## 2.6 setters (AAA) +### 2.6 setters (AAA) 自定义设置器列表 @@ -340,11 +344,11 @@ | setters[].keywords | String[] | 设置器检索关键字 | - | - | | setters[].reference | Reference | 设置器引用的资源包信息 | - | - | -## 2.7 extConfig (AAA) +### 2.7 extConfig (AAA) 定义平台相关的扩展内容，用于存放平台自身实现的一些私有协议, 以允许存量平台能够平滑地迁移至标准协议。 extConfig 是一个 key-value 结构的对象，协议不会规定 extConfig 中的字段名称以及类型, 完全自定义 -## 2.8 TypeScript 定义 +### 2.8 TypeScript 定义 _组件低代码描述相关部分字段含义详见物料规范中`2.2.2 组件描述协议`部分；_ @@ -463,7 +467,7 @@ export interface Package { */ exportName?: string; /** - * 标识当前 package 资源加载在 window.library 上的是否是一个异步对象 + * 标识当前 package 资源加载在 window.library 上的是否是一个异步对象 */ async?: boolean; /** @@ -471,11 +475,11 @@ export interface Package { */ exportMode?: string; /** - * 标识当前 package 内容是从哪个 package 导出来的 + * 标识当前 package 内容是从哪个 package 导出来的 */ exportSourceId?: string; /** - * 标识当前 package 是从 window 上的哪个属性导出来的 + * 标识当前 package 是从 window 上的哪个属性导出来的 */ exportSourceLibrary?: string; } @@ -684,4 +688,4 @@ export interface ComponentSchema { ``` -`ComponentSchema` 的定义见[低代码业务组件描述](./1.material-spec.md#221-组件规范) +`ComponentSchema` 的定义见[低代码业务组件描述](./material-spec.md#221-组件规范) diff --git a/specs/lowcode-spec.md b/docs/docs/specs/lowcode-spec.md similarity index 97% rename from specs/lowcode-spec.md rename to docs/docs/specs/lowcode-spec.md index 043ad81bf..e1d57daa0 100644 --- a/specs/lowcode-spec.md +++ b/docs/docs/specs/lowcode-spec.md @@ -1,6 +1,13 @@ +--- +title: 《低代码引擎搭建协议规范》 +sidebar_position: 0 +--- # 《低代码引擎搭建协议规范》 -## 1.1 本协议规范涉及的问题域 + +## 1 介绍 + +### 1.1 本协议规范涉及的问题域 - 定义本协议版本号规范 - 定义本协议中每个子规范需要被支持的 Level @@ -12,17 +19,17 @@ - 定义搭建基础协议无障碍访问规范（AAA） -## 1.2 协议草案起草人 +### 1.2 协议草案起草人 - 撰写：月飞、康为、林熠 - 审阅：大果、潕量、九神、元彦、戊子、屹凡、金禅、前道、天晟、戊子、游鹿、光弘、力皓 -## 1.3 版本号 +### 1.3 版本号 1.0.0 -## 1.4 协议版本号规范（A） +### 1.4 协议版本号规范（A） 本协议采用语义版本号，版本号格式为 `major.minor.patch` 的形式。 @@ -31,7 +38,7 @@ - patch 是补丁号：用于发布向下兼容的协议问题修正 -## 1.5 协议中子规范 Level 定义 +### 1.5 协议中子规范 Level 定义 | 规范等级 | 实现要求 | | -------- | ---------------------------------------------------------------------------------- | @@ -40,9 +47,9 @@ | AAA | 参考规范，根据业务场景实际诉求实现；是集团层面鼓励的技术实现引导。 | -## 1.6 名词术语 +### 1.6 名词术语 -### 1.6.1 物料系统名词 +#### 1.6.1 物料系统名词 - **基础组件（Basic Component）**：前端领域通用的基础组件，阿里巴巴前端委员会官方指定的基础组件库是 Fusion Next/AntD。 - **图表组件（Chart Component）**：前端领域通用的图表组件，有代表性的图表组件库有 BizCharts。 @@ -54,7 +61,7 @@ - **模板（Template）**：特定垂直业务领域内的业务组件、区块可组合为单个页面，或者是再配合路由组合为多个页面集，统称为模板。 -### 1.6.2 低代码搭建系统名词 +#### 1.6.2 低代码搭建系统名词 - **搭建编辑器**：使用可视化的方式实现页面搭建，支持组件 UI 编排、属性编辑、事件绑定、数据绑定，最终产出符合搭建基础协议规范的数据。 - **属性面板**：低代码编辑器内部用于组件、区块、页面的属性编辑、事件绑定、数据绑定的操作面板。 @@ -69,7 +76,7 @@ - **数据绑定**：是指为某个组件的某个属性绑定用于该属性使用的数据。 - **生命周期**: 一般指某个对象的生老病死，本文中指某个实体（组件、容器、区块等等）的创建、加载、显示、销毁等关键生命阶段的统称。 -## 1.7 背景 +### 1.7 背景 - **协议目标**： 通过约束低代码引擎的搭建协议规范，让上层低代码编辑器的产出物（低代码业务组件、区块、应用）保持一致性，可跨低代码研发平台进行流通而提效，亦不阻碍集团业务间融合的发展。  - **协议通**： @@ -83,19 +90,19 @@ - 事件描述，包含统一事件上下文、统一搭建 API； - **物料通**：指在相同领域内的不同搭建产品，可直接使用的物料。比如模版、区块、组件； -## 1.8 受众 +### 1.8 受众 本协议适用于所有使用低代码搭建平台来开发页面或组件的开发者，以及围绕此协议的相关工具或工程化方案的开发者。阅读及使用本协议，需要对低代码搭建平台的交互和实现有一定的了解，对前端开发相关技术栈的熟悉也会有帮助，协议中对通用的前端相关术语不会做进一步的解释说明。 -## 1.9 使用范围 +### 1.9 使用范围 本协议描述的是低代码搭建平台产物（应用、页面、区块、组件）的 schema 结构，以及实现其数据状态更新（内置 api)、能力扩展、国际化等方面完整，只在低代码搭建场景下可用； -## 1.10 协议目标 +### 1.10 协议目标 一套面向开发者的 schema 规范，用于规范化约束搭建编辑器的输出，以及渲染模块和出码模块的输入，将搭建编辑器、渲染模块、出码模块解耦，保障搭建编辑器、渲染模块、出码模块的独立升级。 -## 1.11 设计说明 +### 1.11 设计说明 - **语义化**：语义清晰，简明易懂，可读性强。 - **渐进性描述**：搭建的本质是通过 源码组件 进行嵌套组合，从小往大、依次组合生成 组件、区块、页面，最终通过云端构建生成 应用 的过程。因此在搭建基础协议中，我们需要知道如何去渐进性的描述组件、区块、页面、应用这 4 个实体概念。 @@ -105,7 +112,7 @@ - **支持国际化&无障碍访问标准的实现** -# 2 协议结构 +## 2 协议结构 协议最顶层结构如下： @@ -249,7 +256,7 @@ } ``` -## 2.1 协议版本号（A） +### 2.1 协议版本号（A） 定义当前协议 schema 的版本号，不同的版本号对应不同的渲染 SDK，以保障不同版本搭建协议产物的正常渲染； @@ -267,7 +274,7 @@ } ``` -## 2.2 组件映射关系（A） +### 2.2 组件映射关系（A） 协议中用于描述 componentName 到公域组件映射关系的规范。 @@ -358,7 +365,7 @@ import { Input as CustomInput } from '@ali/custom/lib/input'; ``` -## 2.3 组件树描述（A） +### 2.3 组件树描述（A） 协议中用于描述搭建出来的组件树结构的规范，整个组件树的描述由**组件结构**&**容器结构**两种结构嵌套构成。 @@ -371,13 +378,13 @@ import { Input as CustomInput } from '@ali/custom/lib/input'; - 组件结构：转换成一个 .jsx 文件内 React Class 类 render 函数返回的 **jsx** 代码。 - 容器结构：将转换成一个标准文件，如 React 的 jsx 文件， export 一个 React Class，包含生命周期定义、自定义方法、事件属性绑定、异步数据请求等。 -### 2.3.1 基础结构描述 (A) +#### 2.3.1 基础结构描述 (A) 此部分定义了组件结构、容器结构的公共基础字段。 > 阅读时可先跳到后续章节，待需要时回来参考阅读 -#### 2.3.1.1 Props 结构描述 +##### 2.3.1.1 Props 结构描述 | 参数 | 说明 | 类型 | 支持变量 | 默认值 | 备注 | | ----------- | ------------ | ------ | -------- | ------ | ------------------------------------- | @@ -388,7 +395,7 @@ import { Input as CustomInput } from '@ali/custom/lib/input'; | extendProps | 组件继承属性 | 变量 | ✅ | - | 仅支持变量绑定，常用于继承属性对象 | | ... | 组件私有属性 | - | - | - | | -#### 2.3.1.2 css/less/scss 样式描述 +##### 2.3.1.2 css/less/scss 样式描述 | 参数 | 说明 | 类型 | 支持变量 | 默认值 | | ------------- | -------------------------------------------------------------------------- | ------ | -------- | ------ | @@ -402,14 +409,14 @@ import { Input as CustomInput } from '@ali/custom/lib/input'; } ``` -#### 2.3.1.3 ComponentDataSource 对象描述 +##### 2.3.1.3 ComponentDataSource 对象描述 | 参数 | 说明 | 类型 | 支持变量 | 默认值 | 备注 | | ----------- | ---------------------- | -------------------------------------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------- | | list[] | 数据源列表 | Array\<**ComponentDataSourceItem**\> | - | - | 成为为单个请求配置, 内容定义详见 [ComponentDataSourceItem 对象描述](#2314-componentdatasourceitem-对象描述) | | dataHandler | 所有请求数据的处理函数 | Function | - | - | 详见 [dataHandler Function 描述](#2317-datahandler-function 描述) | -#### 2.3.1.4 ComponentDataSourceItem 对象描述 +##### 2.3.1.4 ComponentDataSourceItem 对象描述 | 参数 | 说明 | 类型 | 支持变量 | 默认值 | 备注 | | -------------- | ---------------------------- | ---------------------------------------------------- | -------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | @@ -446,7 +453,7 @@ try { - dataHandler 会有默认值，考虑到返回结果入参都是 response 完整对象，默认值会返回 `response.data`，errorHandler 没有默认值 -#### 2.3.1.5 ComponentDataSourceItemOptions 对象描述 +##### 2.3.1.5 ComponentDataSourceItemOptions 对象描述 | 参数 | 说明 | 类型 | 支持变量 | 默认值 | 备注 | | ------- | ------------ | ------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------- | @@ -459,7 +466,7 @@ try { -#### 2.3.1.6 ComponentLifeCycles 对象描述 +##### 2.3.1.6 ComponentLifeCycles 对象描述 生命周期对象，schema 面向多端，不同 DSL 有不同的生命周期方法： @@ -499,14 +506,14 @@ try { ``` -#### 2.3.1.7 dataHandler Function 描述 +##### 2.3.1.7 dataHandler Function 描述 - 参数：为 dataMap 对象，包含字段如下： - key: 数据 id - value: 单个请求结果 - 返回值：数据对象 data，将会在渲染引擎和 schemaToCode 中通过调用 `this.setState(...)` 将返回的数据对象生效到 state 中；支持返回一个 Promise，通过 `resolve（返回数据）`，常用于串行发送请求场景。 -#### 2.3.1.8 ComponentPropDefinition 对象描述 +##### 2.3.1.8 ComponentPropDefinition 对象描述 | 参数 | 说明 | 类型 | 支持变量 | 默认值 | 备注 | | ------------ | ---------- | -------------- | -------- | --------- | ----------------------------------------------------------------------------------------------------------------- | @@ -530,7 +537,7 @@ try { }, ``` -### 2.3.2 组件结构描述（A） +#### 2.3.2 组件结构描述（A） 对应生成源码开发体系中 render 函数返回的 jsx 代码，主要描述有以下属性： @@ -576,7 +583,7 @@ try { ``` -### 2.3.3 容器结构描述 (A)  +#### 2.3.3 容器结构描述 (A)  容器是一类特殊的组件，在组件能力基础上增加了对生命周期对象、自定义方法、样式文件、数据源等信息的描述。包含**低代码业务组件容器 Component**、**区块容器 Block**、**页面容器 Page** 3 种。主要描述有以下属性： @@ -731,11 +738,11 @@ try { } ``` -### 2.3.4 属性值类型描述（A） +#### 2.3.4 属性值类型描述（A） 在上述**组件结构**和**容器结构**描述中，每一个属性所对应的值，除了传统的 JS 值类型（String、Number、Object、Array、Boolean）外，还包含有**节点类型**、**事件函数类型**、**变量类型**等多种复杂类型；接下来将对于复杂类型的详细描述方式进行详细介绍。 -#### 2.3.4.1 节点类型（A） +##### 2.3.4.1 节点类型（A） 通常用于描述组件的某一个属性为 **ReactNode** 或 **Function-Return-ReactNode** 的场景。该类属性的描述均以 **JSSlot** 的方式进行描述，详细描述如下： @@ -799,7 +806,7 @@ try { ``` -#### 2.3.4.2 事件函数类型（A） +##### 2.3.4.2 事件函数类型（A） 协议内的事件描述，主要包含**容器结构**的**生命周期**和**自定义方法**，以及**组件结构**的**事件函数类属性**三类。所有事件函数的描述，均以 **JSFunction** 的方式进行描述，保留与原组件属性、生命周期（React / 小程序）一致的输入参数，并给所有事件函数 binding 统一一致的上下文（当前组件所在容器结构的 **this** 对象）。 @@ -861,7 +868,7 @@ try { } ``` -#### 2.3.4.3 变量类型（A） +##### 2.3.4.3 变量类型（A） 在上述**组件结构** 或**容器结构**中，有多个属性的值类型是支持变量类型的，通常会通过变量形式来绑定某个数据，所有的变量表达式均通过 JSExpression 表达式，上下文与事件函数描述一致，表达式内通过 **this** 对象获取上下文； @@ -952,7 +959,7 @@ try { } ``` -#### 2.3.4.4 国际化多语言类型（AA） +##### 2.3.4.4 国际化多语言类型（AA） 协议内的一些文本值内容，我们希望是和协议全局的国际化多语言语料是关联的，会按照全局国际化语言环境的不同使用对应的语料。所有国际化多语言值均以 **i18n** 结构描述。这样可以更为清晰且结构化得表达使用场景。 @@ -1020,11 +1027,11 @@ type Ti18n = { ``` -### 2.3.5 上下文 API 描述（A） +#### 2.3.5 上下文 API 描述（A） 在上述**事件类型描述**和**变量类型描述**中，在函数或 JS 表达式内，均可以通过 **this** 对象获取当前组件所在容器（React Class）的实例化对象，在搭建场景下的渲染模块和出码模块实现上，统一约定了该实例化 **this** 对象下所挂载的最小 API 集合，以保障搭建协议具备有一致的**数据流**和**事件上下文**。  -#### 2.3.5.1 容器 API： +##### 2.3.5.1 容器 API： | 参数 | 说明 | 类型 | 备注 | | ----------------------------------- | --------------------------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------- | @@ -1083,7 +1090,7 @@ this.setState((prevState) => ({ count: prevState.count + 1 })); 备注： 如果组件没有在区块容器内，而是直接在页面内，那么 `this === this.page` -#### 2.3.5.2 循环数据 API +##### 2.3.5.2 循环数据 API 获取在循环场景下的数据对象。举例：上层组件设置了 loop 循环数据，且设置了 `loopArgs：["item", "index"]`，当前组件的属性表达式或绑定的事件函数中，可以通过 this 上下文获取所在循环的数据环境；默认值为 `['item','index']` ，如有多层循环，需要自定义不同 loopArgs，同样通过 `this[自定义循环别名]` 获取对应的循环数据和序号； @@ -1093,7 +1100,7 @@ this.setState((prevState) => ({ count: prevState.count + 1 })); | this.item | 获取当前 index 对应的循环体数据； | Any | - | | this.index | 当前物料在循环体中的 index | Number | - | -## 2.4 工具类扩展描述（AA） +### 2.4 工具类扩展描述（AA） 用于描述物料开发过程中，自定义扩展或引入的第三方工具类（例如：lodash 及 moment），增强搭建基础协议的扩展性，提供通用的工具类方法的配置方案及调用 API。 @@ -1168,7 +1175,7 @@ export const recordEvent = function(logkey, gmkey, gokey, reqMethod) { } ``` -## 2.5 国际化多语言支持（AA） +### 2.5 国际化多语言支持（AA） 协议中用于描述国际化语料和组件引用国际化语料的规范，遵循集团国际化中台关于国际化语料规范定义。 @@ -1237,34 +1244,34 @@ export const recordEvent = function(logkey, gmkey, gokey, reqMethod) { } ``` -## 2.6 应用范围内的全局常量（AA） +### 2.6 应用范围内的全局常量（AA） 用于描述在整个应用内通用的全局常量，比如请求 API 的域名、环境等。 -## 2.7 应用范围内的全局样式（AA） +### 2.7 应用范围内的全局样式（AA） 用于描述在应用范围内的全局样式，比如 reset.css 等。 -## 2.8 当前应用配置信息（AA） +### 2.8 当前应用配置信息（AA） 用于描述当前应用的配置信息，比如当前应用的路由模式、Shell/Layout、主题等。 > 注意：该字段为扩展字段，消费方式由各自场景自己决定，包括运行时和出码。 -## 2.9 当前应用元数据信息（AA） +### 2.9 当前应用元数据信息（AA） 用于描述当前应用的元数据信息，比如当前应用的名称、Git 信息、版本号等等。 > 注意：该字段为扩展字段，消费方式由各自场景自己决定，包括运行时和出码。 -## 2.10 当前应用的公共数据源（AA） +### 2.10 当前应用的公共数据源（AA） 用于描述当前应用的公共数据源，数据结构跟容器结构里的 ComponentDataSource 保持一致。 在运行时 / 出码使用时，API 和应用级数据源 API 保持一致，都是 `this.dataSourceMap['globalDSName'].load()` -# 3 应用描述 +## 3 应用描述 -## 3.1 文件目录 +### 3.1 文件目录 以下是推荐的应用目录结构，与标准源码 build-scripts 对齐，这里的目录结构是帮助理解应用级协议的设计，不做强约束 @@ -1312,17 +1319,17 @@ export const recordEvent = function(logkey, gmkey, gokey, reqMethod) { └── .stylelintrc.js ``` -## 3.2 应用级别 APIs +### 3.2 应用级别 APIs > 下文中 `xxx` 代指任意 API -### 3.2.1 路由 Router API +#### 3.2.1 路由 Router API - this.location.`xxx` - this.history.`xxx` - this.match.`xxx` -### 3.2.2 应用级别的公共函数或第三方扩展 +#### 3.2.2 应用级别的公共函数或第三方扩展 - this.utils.`xxx` -### 3.2.3 国际化相关 API +#### 3.2.3 国际化相关 API | API | 函数签名 | 说明 | | -------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------ | | this.i18n | (i18nKey: string, params?: { [paramName: string]: string; }) => string | i18nKey 是语料的标识符，params 可选，是用来做模版字符串替换的。返回语料字符串 | diff --git a/specs/material-spec.md b/docs/docs/specs/material-spec.md similarity index 97% rename from specs/material-spec.md rename to docs/docs/specs/material-spec.md index 1d2375a11..f7687114b 100644 --- a/specs/material-spec.md +++ b/docs/docs/specs/material-spec.md @@ -1,8 +1,12 @@ +--- +title: 《低代码引擎物料协议规范》 +sidebar_position: 1 +--- # 《低代码引擎物料协议规范》 -# 1 介绍 +## 1 介绍 -## 1.1 本协议规范涉及的问题域 +### 1.1 本协议规范涉及的问题域 - 定义本协议版本号规范 - 定义本协议中每个子规范需要被支持的 Level @@ -14,16 +18,16 @@ - 定义中后台物料无障碍访问规范（AAA） -## 1.2 协议草案起草人 +### 1.2 协议草案起草人 - 撰写：九神、大果、元彦、戊子、林熠、屹凡、金禅 - 审阅：潕量、月飞、康为、力皓、荣彬、暁仙、度城、金禅、戊子、林熠、絮黎 -## 1.3 版本号 +### 1.3 版本号 1.0.0 -## 1.4 协议版本号规范（A） +### 1.4 协议版本号规范（A） 本协议采用语义版本号，版本号格式为 `major.minor.patch` 的形式。 @@ -32,7 +36,7 @@ - patch 是补丁号：用于发布向下兼容的协议问题修正 -## 1.5 协议中子规范 Level 定义 +### 1.5 协议中子规范 Level 定义 | 规范等级 | 实现要求 | | -------- | ---------------------------------------------------------------------------------- | @@ -41,26 +45,26 @@ | AAA | 参考规范，根据业务场景实际诉求实现；是集团层面鼓励的技术实现引导。 | -## 1.6 名词术语 +### 1.6 名词术语 - **物料**：能够被沉淀下来直接使用的前端能力，一般表现为业务组件、区块、模板。 - **业务组件（Business Component）**：业务领域内基于基础组件之上定义的组件，可能会包含特定业务域的交互或者是业务数据，对外仅暴露可配置的属性，且必须发布到公域（如阿里 NPM）；在同一个业务域内可以流通，但不需要确保可以跨业务域复用。 - **低代码业务组件（Low-Code Business Component）**：通过低代码编辑器搭建而来，有别于源码开发的业务组件，属于业务组件中的一种类型，遵循业务组件的定义；同时低代码业务组件还可以通过低代码编辑器继续多次编辑。 - **区块（Block）**：通过低代码搭建的方式，将一系列业务组件、布局组件进行嵌套组合而成，不对外提供可配置的属性。可通过区块容器组件的包裹，实现区块内部具备有完整的样式、事件、生命周期管理、状态管理、数据流转机制。能独立存在和运行，可通过复制 schema 实现跨页面、跨应用的快速复用，保障功能和数据的正常。 - **模板（Template）**：特定垂直业务领域内的业务组件、区块可组合为单个页面，或者是再配合路由组合为多个页面集，统称为模板。 -## 1.7 物料规范背景 +### 1.7 物料规范背景 目前集团业务融合频繁，而物料规范的不统一给业务融合带来额外的高成本，另一方面集团各个 BU 的前端物料也存在不同程度的重复建设。我们期望通过集团层面的物料通不阻碍业务融合的发展，同时通过集团层面的物料流通来提升物料丰富度，通过丰富物料的复用来提效中后台系统研发，同时也能给新业务场景提供高质量的启动物料。 -## 1.8 物料规范定义 +### 1.8 物料规范定义 - **源码物料规范**：一套面向开发者的目录规范，用于规范化约束开发过程中的代码、文档、接口规范，以方便物料在集团内的流通。 - **搭建物料规范**：一套面向开发者的 Schema 规范，用于规范化约束开发过程中的代码、文档、接口规范，以方便物料在集团内的流通。 -# 2. 物料规范 - 业务组件规范 +## 2. 物料规范 - 业务组件规范 -## 2.1 源码规范 +### 2.1 源码规范 -### 2.1.1 目录规范（A） +#### 2.1.1 目录规范（A） ``` @@ -229,7 +233,7 @@ ReactDOM.render(
``` ~~~ -### 2.1.2 API 规范（A) +#### 2.1.2 API 规范（A) API 是组件的属性解释，给开发者作为组件属性配置的参考。为了保持 API 的一致性，我们制定这个 API 命名规范。对于业界通用的，约定俗成的命名，我们遵循社区的约定。对于业界有多种规则难以确定的，我们确定其中一种，大家共同遵守。 @@ -327,7 +331,7 @@ true 表示触发规则都会关闭，false 表示触发规则不会关闭。 **xxxProps 例子**： 比如 `Search` 组件由 `Input` 和 `Button` 构成，`Button` 的属性通过 `buttonProps` 传递给内部的 `Button`。`` -### 2.1.3 入库方式 (A) +#### 2.1.3 入库方式 (A) 入库是指：发布组件，并且存储到集团物料中心，方便统一管理和流通。 @@ -347,7 +351,7 @@ $ iceworks sync ``` -### 2.1.4 国际化多语言支持规范（AA） +#### 2.1.4 国际化多语言支持规范（AA） 文件命名采取 [bcp47](https://tools.ietf.org/html/bcp47) 规范 @@ -444,7 +448,7 @@ export default ConfigProvider.config(BizHello, { }); ``` -### 2.1.5 主题切换规范（AA） +#### 2.1.5 主题切换规范（AA） 业务组件中如果有自定义的需要跟随主题色的 UI，一定要引入变量的形式，增加组件的流通性。 @@ -461,7 +465,7 @@ export default ConfigProvider.config(BizHello, { ``` -### 2.1.6 [Deprecated]支持转设计稿（AAA） +#### 2.1.6 [Deprecated]支持转设计稿（AAA） 对接 sketch 插件（FusionCool）的目的是为了让开发产出的业务组件能够直接给设计师使用，用法类似现在 Fusion Next 基础组件。 @@ -495,7 +499,7 @@ export default { api 属性标准参考 [https://fusion.design/help.html#/dev-biz](https://fusion.design/help.html#/dev-biz) -### 2.1.7 无障碍访问规范(AAA) +#### 2.1.7 无障碍访问规范(AAA) 无障碍需要符合 [WCAG 2.1 A级标准](https://www.w3.org/TR/WCAG21/)，可参考 [W3C 无障碍最佳实践](https://www.w3.org/TR/wai-aria-practices-1.1/)、[Fusion 无障碍指引 2.3.1](https://alibaba-fusion.github.io/next/part1/basics.html) 章节等。 @@ -537,9 +541,9 @@ component - 传参数 - 有些组件需要根据具体的业务，实现不同的可访问性，这里为开发者内置一些参数，想使用无障碍的时候，用户只需要根据现有的需求，选择对应的内置参数，例如设置 aria-label，以下组件需要用户传参数才支持无障碍组件如下：`NumberPicker`、`Transfer` -## 2.2 低代码规范 +### 2.2 低代码规范 -### 2.2.1 组件规范 +#### 2.2.1 组件规范 通过低代码编辑器搭建而来，有别于源码开发的业务组件，属于业务组件中的一种类型，遵循业务组件的定义；同时低代码业务组件还可以通过低代码编辑器继续多次编辑。 @@ -594,10 +598,10 @@ component } ``` -### 2.2.2 组件描述协议 +#### 2.2.2 组件描述协议 对源码组件在低代码搭建平台中使用时所具备的配置能力和交互行为进行规范化描述，让不同平台对组件接入的实现保持一致，让组件针对不同的搭建平台接入时可以使用一份统一的描述内容，让组件在不同的业务中流通成为可能。 -#### 2.2.2.1 协议结构 +##### 2.2.2.1 协议结构 单个组件描述内容为 json 结构，主要包含以下三部分内容，分别为： @@ -607,7 +611,7 @@ component 整体结构概览: [http://lowcode-engine.cn/doc?url=sde3wf](http://lowcode-engine.cn/doc?url=sde3wf) -#### 2.2.2.2 基础信息（A） +##### 2.2.2.2 基础信息（A） | 字段 | 字段描述 | 字段类型 | 允许空 | | ----------------- | --------------------- | ------------------------- | ------ | @@ -633,7 +637,7 @@ component | priority | 用于描述组件在同一 category 中的排序 | String | 否 | -#### 2.2.2.3 组件属性信息 props (A) +##### 2.2.2.3 组件属性信息 props (A) 描述组件属性信息，通常包含名称、类型、描述、默认值 4 项内容。 @@ -804,7 +808,7 @@ export default class FusionForm extends PureComponent { ``` -#### 2.2.2.4 编辑体验增强 configure +##### 2.2.2.4 编辑体验增强 configure 推荐用于优化搭建产品的编辑体验，定制编辑能力的配置信息，通过能力抽象分类，主要包含如下几个维度的配置项： @@ -818,7 +822,7 @@ export default class FusionForm extends PureComponent { | 【已废弃】experimental (AAA) | 将引擎的一些实验性特性放在这个配置里 | Object | 用户可以提前体验这些特性 | -##### 2.2.2.4.1 属性面板配置 props (A) +###### 2.2.2.4.1 属性面板配置 props (A) props 数组下对象字段描述： @@ -842,7 +846,7 @@ props 数组下对象字段描述： 根据属性值类型 propType，确定对应控件类型 (setter) ，详见 [https://lowcode-engine.cn/docV2/grfylu](https://lowcode-engine.cn/docV2/grfylu) -##### 2.2.2.4.2 通用扩展面板支持性配置 supports (AA) +###### 2.2.2.4.2 通用扩展面板支持性配置 supports (AA) 样式配置面板能力描述，描述是否支持行业样式编辑、是否支持类名设置等。 @@ -865,7 +869,7 @@ props 数组下对象字段描述： ``` -##### 2.2.2.4.3 组件能力配置 component +###### 2.2.2.4.3 组件能力配置 component 与组件相关的能力、约束、行为等描述，有些信息可从组件视图实例上直接获取，包含如下字段： @@ -914,7 +918,7 @@ props 数组下对象字段描述： } ``` -##### 2.2.2.4.4 高级功能配置 advanced (AAA) +###### 2.2.2.4.4 高级功能配置 advanced (AAA) 组件在低代码引擎设计器中的事件回调和 hooks 等高级功能配置，包含如下字段： @@ -963,7 +967,7 @@ props 数组下对象字段描述： } ``` -#### 2.2.2.5 TypeScript 定义 +##### 2.2.2.5 TypeScript 定义 ```TypeScript @@ -1196,9 +1200,9 @@ export interface ComponentDescription { // 组件描述协议，通过 npm 中 } ``` -### 2.2.3 资产包协议 +#### 2.2.3 资产包协议 -#### 2.2.3.1 协议结构 +##### 2.2.3.1 协议结构 协议最顶层结构如下，包含 5 方面的描述内容： @@ -1207,7 +1211,7 @@ export interface ComponentDescription { // 组件描述协议，通过 npm 中 - components { Array } 所有组件的描述协议列表 - sort { Object } 用于描述组件面板中的 tab 和 category -#### 2.2.3.2 version（A） +##### 2.2.3.2 version（A） 定义当前协议 schema 的版本号； @@ -1215,7 +1219,7 @@ export interface ComponentDescription { // 组件描述协议，通过 npm 中 | ---------- | ------ | ---------- | -------- | ------ | | version | String | 协议版本号 | - | 1.0.0 | -#### 2.2.3.3 packages（A） +##### 2.2.3.3 packages（A） 定义低代码编辑器中加载的资源列表，包含公共库和组件(库) cdn 资源等； @@ -1288,11 +1292,11 @@ export interface ComponentDescription { // 组件描述协议，通过 npm 中 } ``` -#### 2.2.3.4 components （A） +##### 2.2.3.4 components （A） 定义所有组件的描述协议列表，组件描述协议遵循本规范章节 2.2.2 的定义； -#### 2.2.3.5 sort （A） +##### 2.2.3.5 sort （A） 定义组件列表分组 @@ -1301,7 +1305,7 @@ export interface ComponentDescription { // 组件描述协议，通过 npm 中 | sort.groupList | String[] | 组件分组，用于组件面板 tab 展示 | - | ['精选组件', '原子组件'] | | sort.categoryList | String[] | 组件面板中同一个 tab 下的不同区间用 category 区分，category 的排序依照 categoryList 顺序排列 | - | ['通用', '数据展示', '表格类', '表单类'] | -#### 2.2.3.6 TypeScript 定义 +##### 2.2.3.6 TypeScript 定义 ```TypeScript export interface ComponentSort { @@ -1326,13 +1330,13 @@ export interface RemoteComponentDescription { } ``` -# 3 物料规范-区块规范 +## 3 物料规范-区块规范 -## 3.1 源码规范 +### 3.1 源码规范 英文 block, 可复用的代码片段，每个区块对应一个 npm。 -### 3.1.1 目录 (A) +#### 3.1.1 目录 (A) ```html @@ -1352,7 +1356,7 @@ block/ ``` -### 3.1.2 package.json (A) +#### 3.1.2 package.json (A) ```json @@ -1370,9 +1374,9 @@ block/ } ``` -### 3.1.3 html2sketch (3A) +#### 3.1.3 html2sketch (3A) -#### 3.1.3.1 package.json 内 blockConfig 结构 +##### 3.1.3.1 package.json 内 blockConfig 结构 ```json { @@ -1400,7 +1404,7 @@ block/ } ``` -## 3.2 低代码规范 +### 3.2 低代码规范 由业务组件、布局组件进行嵌套组合而成。不对外提供可配置的属性。可通过**区块容器组件**的包裹，实现容器内部具备有完整的样式、事件、生命周期管理、状态管理、数据流转机制。能独立存在和运行，可实现跨页面、跨应用的快速复用，保障功能和数据的正常。 @@ -1479,11 +1483,11 @@ block/ } ``` -# 4 物料规范 - 模板规范 +## 4 物料规范 - 模板规范 -## 4.1 源码规范 +### 4.1 源码规范 -### 4.1.1 目录规范（A） +#### 4.1.1 目录规范（A） 与标准源码 build-scripts 对齐 @@ -1642,9 +1646,9 @@ a { } ``` -### 4.1.2 html2sketch (AAA) +#### 4.1.2 html2sketch (AAA) -#### 4.1.2.1 package.json 内 scaffoldConfig 结构 +##### 4.1.2.1 package.json 内 scaffoldConfig 结构 ```json { diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 68728ca21..04c99067e 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -65,45 +65,6 @@ const config = { navbar, footer: { // style: 'dark', - links: [ - {}, - { - title: '低代码引擎协议栈', - items: [ - { - label: '《低代码引擎搭建协议规范》', - href: 'https://lowcode-engine.cn/lowcode', - }, - { - label: '《低代码引擎物料协议规范》', - href: 'https://lowcode-engine.cn/material', - }, - { - label: '《低代码引擎资产包协议规范》', - href: 'https://lowcode-engine.cn/assets', - }, - ], - }, - {}, - { - title: '案例产品', - items: [ - { - label: '钉钉宜搭', - href: 'https://www.aliwork.com/', - }, - { - label: 'Parts 造物', - href: 'https://parts.lowcode-engine.cn/', - }, - { - label: 'UIPaaS 低代码平台孵化器', - href: 'https://uipaas.net', - }, - ], - }, - {}, - ], copyright: `Copyright © ${new Date().getFullYear()} 阿里巴巴集团, Inc. Built with Docusaurus.`, }, // 主题切换 diff --git a/docs/package.json b/docs/package.json index 8bbab34d8..81b032d17 100644 --- a/docs/package.json +++ b/docs/package.json @@ -1,6 +1,6 @@ { "name": "@alilc/lowcode-engine-docs", - "version": "0.0.1-beta.4", + "version": "1.0.0", "description": "低代码引擎版本化文档", "license": "MIT", "files": [