fix: add protocol docs

NetEase · Sep 2, 2024 · 49c2c25 · 49c2c25
1 parent 12c2b8d
commit 49c2c25
Show file tree

Hide file tree

Showing 4 changed files with 251 additions and 54 deletions.
diff --git a/README.md b/README.md
@@ -4,29 +4,51 @@ This repo is documentation site for [netease/tango](https://github.com/NetEase/t
 
 Site link: <https://netease.github.io/tango-site/>
 
-### Installation
+## Installation
 
-```
-$ yarn
+```bash
+yarn
 ```
 
-### Local Development
+## Local Development
 
-```
-$ yarn start
+```bash
+yarn start
 ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
-### Build
+### i18n
+
+Translate plugin data
+
+```bash
+npm run write-translations -- --locale zh-Hans
+```
+
+Translate docs
 
+```bash
+mkdir -p i18n/zh-Hans/docusaurus-plugin-content-docs/current
+cp -r docs/** i18n/zh-Hans/docusaurus-plugin-content-docs/current
 ```
-$ yarn build
+
+Translate blog
+
+```bash
+mkdir -p i18n/zh-Hans/docusaurus-plugin-content-blog
+cp -r blog/** i18n/zh-Hans/docusaurus-plugin-content-blog
+```
+
+## Build
+
+```bash
+yarn build
 ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
 
-### Deployment
+## Deployment
 
 Using SSH:
 

diff --git a/docs/protocol/prototype.mdx b/docs/protocol/prototype.mdx
@@ -0,0 +1,198 @@
+# 组件配置协议
+
+组件配置协议是附加在组件包上的一层额外描述文件，Tango 设计器将会借助这个配置文件为选中的组件渲染配置面板。
+
+## 组件描述
+
+请参考 [IComponentPrototype](https://netease.github.io/tango/interfaces/_music163_tango_helpers.IComponentPrototype.html)
+
+## 组件属性描述
+
+请参考 [IComponentProps](https://netease.github.io/tango/interfaces/_music163_tango_helpers.IComponentProp.html)
+
+### 嵌套属性
+
+当某个组件属性为嵌套属性时，例如 `<Table scroll={{ x: 800, y: 400 }} />`，此时可以描述如下：
+
+```js
+{
+  name: 'Table',
+  props: [
+    {
+      name: 'scroll',
+      props: [
+        {
+          name: 'x',
+          setter: 'numberSetter',
+        },
+        {
+          name: 'y',
+          setter: 'numberSetter',
+        }
+      ],
+    }
+  ],
+}
+```
+
+### 属性的按需展示
+
+当某个属性依赖某个特定的其他属性值时，可以借助 `getVisible` 实现关联展示控制：
+
+```js
+{
+  name: 'Button',
+  props: [
+    {
+      name: 'shape',
+    },
+    {
+      name: 'buttonType',
+      getVisible: (form) => {
+        // 配置项 buttonType 仅在配置项 shape 的值为 button 时才展示
+        return form.getValue('shape') === 'button';
+      },
+    },
+  ];
+}
+```
+
+### 函数模板
+
+当某个属性为函数类型时，且希望在 eventSetter 中快捷生成函数的模板代码时，可以使用 `template` 属性指定
+
+```js
+{
+  name: 'Button',
+  props: [
+    {
+      name: 'shape',
+    },
+    {
+      name: 'onClick',
+      setter: 'eventSetter',
+      // {{content}} 为插值变量，会被替换为用户输入的内容，或选定的变量
+      template: '(e) => {\n  {{content}}\n}',
+    },
+  ];
+}
+```
+
+### 自定义渲染列表
+
+或某个属性为 renderProps 类型时，可以借助 `options` 属性配置 renderProps 的渲染函数模板
+
+```js
+{
+  name: 'CustomCard',
+  props: [
+    {
+        name: 'renderExtra',
+        title: 'extra自定义渲染',
+        setter: 'renderSetter',
+        options: [
+          {
+            label: '占位空间',
+            value: 'Box',
+            // 自定义渲染代码
+            render: '() => <Box>test</Box>',
+            // 自定义渲染代码需要额外引入的组件
+            relatedImports: ['Box'],
+          },
+          {
+            label: '占位文本',
+            value: 'Text',
+            render: '() => <Text>text</Text>',
+            relatedImports: ['Text'],
+          },
+        ],
+      },
+  ];
+}
+```
+
+### 动态属性的展示
+
+当组件需要依据某个属性值进行动态设置其他属性时，可以借助 `getProp` 实现控制：
+
+```js
+{
+  name: 'FormItem',
+  props: [
+    {
+      name: 'component',
+      title: '控件类型',
+    },
+    {
+      name: 'componentProps',
+      title: '子组件属性',
+      getProp(form) {
+        const type = form.getValue('component');
+        const proto = { ...componentMap[type] };
+        const props = omitProps(proto.props, [
+          'placeholder',
+          'options',
+          'onChange',
+          'defaultValue',
+          'value',
+        ]);
+        return {
+          title: proto.title + '属性',
+          props,
+        };
+      },
+    }
+  ],
+}
+```
+
+### 属性的补全提示
+
+当某个属性在输入时需要进行输入提示时，例如某个函数属性需要提示其签名的模版，则可以借助属性输入提示实现:
+
+```js
+{
+  name: 'TableColumn',
+  props: [
+    {
+      name: 'render',
+      setter: 'expressionSetter',
+      autoCompleteOptions: ['(value, record, index) => { return null; }'],
+    }
+  ],
+}
+```
+
+## 组件拖拽规则描述
+
+请参考 [IComponentDnDRules](https://netease.github.io/tango/interfaces/_music163_tango_helpers.IComponentDndRules.html)
+
+### canDrag/canDrop
+
+在 onDragStart 的时候执行。
+
+```js
+export const Page = {
+  name: 'Page',
+  rules: {
+    canDrag() {
+      return false;
+    },
+  },
+};
+```
+
+### canMoveIn/canMoveOut
+
+在 onDragEnter 的时候执行。
+
+```js
+export const Modal = {
+  name: 'Modal',
+  rules: {
+    canMoveIn(incomingName) {
+      return !(incomingName === Modal.name);
+    },
+  },
+};
+```
diff --git a/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json b/i18n/zh-Hans/docusaurus-plugin-content-docs/current.json
@@ -1,42 +1,26 @@
 {
   "version.label": {
-    "message": "Next",
+    "message": "下一篇",
     "description": "The label for version current"
   },
-  "sidebar.tutorialSidebar.category.boot": {
-    "message": "boot",
-    "description": "The label for category boot in sidebar tutorialSidebar"
-  },
-  "sidebar.tutorialSidebar.category.designer": {
-    "message": "designer",
-    "description": "The label for category designer in sidebar tutorialSidebar"
-  },
-  "sidebar.tutorialSidebar.category.customize": {
-    "message": "customize",
-    "description": "The label for category customize in sidebar tutorialSidebar"
-  },
-  "sidebar.tutorialSidebar.category.deploy": {
-    "message": "deploy",
-    "description": "The label for category deploy in sidebar tutorialSidebar"
-  },
-  "sidebar.tutorialSidebar.category.design": {
-    "message": "design",
-    "description": "The label for category design in sidebar tutorialSidebar"
-  },
-  "sidebar.designer.category.接入指南": {
+  "sidebar.designer.category.Guide": {
     "message": "接入指南",
-    "description": "The label for category 接入指南 in sidebar designer"
+    "description": "The label for category Guide in sidebar designer"
   },
-  "sidebar.designer.category.设计器自定义": {
-    "message": "设计器自定义",
-    "description": "The label for category 设计器自定义 in sidebar designer"
+  "sidebar.designer.category.Customize": {
+    "message": "自定义",
+    "description": "The label for category Customize in sidebar designer"
   },
-  "sidebar.designer.category.设计原理": {
+  "sidebar.designer.category.Design": {
     "message": "设计原理",
-    "description": "The label for category 设计原理 in sidebar designer"
+    "description": "The label for category Design in sidebar designer"
   },
-  "sidebar.designer.category.应用框架": {
+  "sidebar.designer.category.Framework": {
     "message": "应用框架",
-    "description": "The label for category 应用框架 in sidebar designer"
+    "description": "The label for category Framework in sidebar designer"
+  },
+  "sidebar.designer.category.Protocols": {
+    "message": "协议规范",
+    "description": "The label for category Protocols in sidebar designer"
   }
 }
diff --git a/sidebars.ts b/sidebars.ts
@@ -12,14 +12,14 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs';
  */
 const sidebars: SidebarsConfig = {
   // By default, Docusaurus generates a sidebar from the docs folder structure
-  tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }],
+  // tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }],
 
   designer: [
     'intro',
     'designer/quick-start',
     {
       type: 'category',
-      label: '接入指南',
+      label: 'Guide',
       items: [
         'designer/deploy/designer',
         'designer/deploy/component',
@@ -30,7 +30,7 @@ const sidebars: SidebarsConfig = {
     },
     {
       type: 'category',
-      label: '设计器自定义',
+      label: 'Customize',
       items: [
         'designer/customize/panels',
         'designer/customize/tools',
@@ -43,7 +43,7 @@ const sidebars: SidebarsConfig = {
     },
     {
       type: 'category',
-      label: '设计原理',
+      label: 'Design',
       items: [
         'designer/design/overview',
         'designer/design/filesystem',
@@ -53,7 +53,7 @@ const sidebars: SidebarsConfig = {
     },
     {
       type: 'category',
-      label: '应用框架',
+      label: 'Framework',
       items: [
         'boot/intro',
         'boot/app-spec',
@@ -66,20 +66,13 @@ const sidebars: SidebarsConfig = {
       ],
       collapsed: false,
     },
-  ],
-
-  // But you can create a sidebar manually
-  /*
-  tutorialSidebar: [
-    'intro',
-    'hello',
     {
       type: 'category',
-      label: 'Tutorial',
-      items: ['tutorial-basics/create-a-document'],
+      label: 'Protocols',
+      items: [{ type: 'autogenerated', dirName: 'protocol' }],
+      collapsed: false,
     },
   ],
-   */
 };
 
 export default sidebars;