feat: update development doc (#866)

* feat: update development doc * fix: cleanup * fix: remove
2022-09-30 12:41:23 +08:00 · 2022-09-30 12:41:23 +08:00 · 85d8c3ecaf
commit 85d8c3ecaf
parent 794080628b
10 changed files with 268 additions and 103 deletions
--- a/.umirc.ts
+++ b/.umirc.ts
@ -127,7 +127,7 @@ export default defineConfig({
        path: '/manual'
      },
      {
-        title: '开发教程',
+        title: '插件开发',
        path: '/development'
      },
      {
--- a/docs/menus.ts
+++ b/docs/menus.ts
@ -64,11 +64,14 @@ export default {
            // '/development/guide/ui-schema-designer/insert-adjacent',
            '/development/guide/ui-schema-designer/designable',
            '/development/guide/ui-schema-designer/component-library',
-            '/development/guide/ui-schema-designer/collection-manager',
-            '/development/guide/ui-schema-designer/acl',
+            // '/development/guide/ui-schema-designer/collection-manager',
+            // '/development/guide/ui-schema-designer/acl',
+            '/development/guide/ui-schema-designer/x-designer',
+            '/development/guide/ui-schema-designer/x-initializer',
          ],
        },
        '/development/guide/ui-router',
+        '/development/guide/settings-center',
      ],
    },
    {
@ -77,10 +80,13 @@ export default {
      children: ['/development/http-api/index', '/development/http-api/rest-api'],
    },
    {
-      title: 'Test & Build',
-      'title.zh-CN': '测试与构建',
+      title: 'Testing',
+      'title.zh-CN': '单元测试',
      type: 'group',
-      children: ['/development/pre-release/test', '/development/pre-release/build'],
+      children: [
+        '/development/pre-release/test', 
+        // '/development/pre-release/build',
+      ],
    },
  ],
  // {
--- a/docs/zh-CN/development/guide/index.md
+++ b/docs/zh-CN/development/guide/index.md
@ -1,76 +1,71 @@
-# 扩展点索引
+# 概述

-## 内核模块
+## Web Server

-<table>
-  <thead>
-    <tr>
-      <th>扩展点</th>
-      <th>相关介绍</th>
-      <th>相关 API</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td>扩展数据库字段类型</td>
-      <td rowspan="3"><a href="/development/guide/collections-fields">数据表与字段</a></td>
-      <td><a href="/api/database#registerfieldtypes"><code>db.registerFieldType()</code></a></td>
-    </tr>
-    <tr>
-      <td>扩展已有数据库表的字段</td>
-      <td><a href="/api/database#extendcollection"><code>db.extendcollection()</code></a></td>
-    </tr>
-    <tr>
-      <td>扩展查询比较运算符</td>
-      <td><a href="/api/database#registeroperators"><code>db.registerOperators()</code></a></td>
-    </tr>
-    <tr>
-      <td>自定义数据仓库操作</td>
-      <td></td>
-      <td><a href="/api/database#registerrepositories"><code>db.registerRepositories()</code></a></td>
-    </tr>
-    <tr>
-      <td>扩展针对全局资源的操作</td>
-      <td rowspan="3"><a href="/development/guide/resources-actions">资源与操作</a></td>
-      <td><a href="/api/resourcer#registeractions"><code>resourcer.registerActions()</code></a></td>
-    </tr>
-    <tr>
-      <td>扩展针对全局资源的中间件</td>
-      <td><a href="/api/resourcer#use"><code>resourcer.use()</code></a></td>
-    </tr>
-    <tr>
-      <td>自定义资源及操作</td>
-      <td><a href="/api/resourcer#define"><code>resourcer.define()</code></a></td>
-    </tr>
-    <tr>
-      <td>自定义路由与页面</td>
-      <td><a href="/development/guide/ui-router">界面路由</a></td>
-      <td><a href="/api/client/route-switch"><code>RouteSwitch</code></a></td>
-    </tr>
-    <tr>
-      <td>扩展自定义组件</td>
-      <td><a href="/development/guide/ui-schema-designer/extending-schema-components">扩展 Schema 组件</a></td>
-      <td><a href="/api/client/schema-designer/schema-component"><code>SchemaComponent</code></a>
-      </td>
-    </tr>
-    <tr>
-      <td>扩展自定义区块类型</td>
-      <td><a href="/development/guide/ui-schema-designer/designable">Schema 设计能力</a></td>
-      <td><a href="/api/client/schema-designer/schema-initializer"><code>SchemaInitializer</code></a></td>
-    </tr>
-    <tr>
-      <td>多语言扩展</td>
-      <td><a href="/development/guide/i18n">国际化</a></td>
-      <td><a href="/api/server/application#i18n"><code>app.i18n</code></a></td>
-    </tr>
-    <tr>
-      <td>扩展子命令</td>
-      <td><a href="/development/guide/commands">命令行工具</a></td>
-      <td><a href="/api/server/application#cli"><code>app.i18n</code></a></td>
-    </tr>
-  </tbody>
-</table>
+- Collection & Field
+- Resource & Action
+- Middleware
+- Events & Hooks

-## 内置插件
+**Samples**

-TODO
+- samples/shop-modeling
+- samples/shop-actions
+- samples/ratelimit
+- samples/model-hooks
+
+## UI Schema Designer
+
+平台最核心的功能，用于可视化配置页面。
+
+- 扩展各种供 UI 设计器使用的 Schema 组件
+- 各种 x-designer 和 x-initializer
+
+**Samples**
+
+- samples/custom-block
+- samples/custom-action
+- samples/custom-field
+- samples/custom-x-designer
+- samples/custom-x-initializer
+
+## UI Router
+
+用于自定义页面，包括：
+
+- routes config
+- route components
+
+**Samples**
+
+- samples/custom-page
+
+## Settings Center
+
+由插件提供的系统级配置的能力
+
+- plugin settings tabs
+
+**Samples**
+
+- samples/custom-settings-center-page
+
+## I18n
+
+国际化
+
+- I18n
+
+**Samples**
+
+- samples/shop-i18n
+
+## Devtools
+
+- Commands
+- Migrations
+
+**Samples**
+
+- samples/custom-command
+- samples/custom-migration
--- a/docs/zh-CN/development/guide/pm-built-in.jpg
+++ b/docs/zh-CN/development/guide/pm-built-in.jpg
--- a/docs/zh-CN/development/guide/settings-center.md
+++ b/docs/zh-CN/development/guide/settings-center.md
@ -0,0 +1,33 @@
+# Settings Center
+
+<img src="./settings-tab.jpg" style="max-width: 100%;"/>
+
+## 示例
+
+```tsx | pure
+import { SettingsCenterProvider } from '@nocobase/client';
+import React, { useContext } from 'react';
+
+const HelloTab => () => <div>Hello Tab</div>;
+
+export default React.memo((props) => {
+  return (
+    <SettingsCenterProvider
+      settings={{
+        'sample-hello': {
+          title: 'Hello',
+          icon: 'ApiOutlined',
+          tabs: {
+            tab1: {
+              title: 'Hello Tab',
+              component: HelloTab,
+            },
+          },
+        },
+      }}
+    >{props.children}</SettingsCenterProvider>
+  );
+});
+```
+
+完整示例查看 [samples/hello](https://github.com/nocobase/nocobase/tree/develop/packages/samples/hello)。
--- a/docs/zh-CN/development/guide/settings-tab.jpg
+++ b/docs/zh-CN/development/guide/settings-tab.jpg
--- a/docs/zh-CN/development/guide/ui-schema-designer/x-designer.md
+++ b/docs/zh-CN/development/guide/ui-schema-designer/x-designer.md
@ -0,0 +1,61 @@
+# x-designer 组件
+
+## 内置 x-designer 组件
+
+- Action.Designer
+- Calendar.Designer
+- Filter.Action.Designer
+- Form.Designer
+- FormItem.Designer
+- FormV2.Designer
+- FormV2.ReadPrettyDesigner
+- DetailsDesigner
+- G2Plot.Designer
+- Kanban.Designer
+- Kanban.Card.Designer
+- Markdown.Void.Designer
+- Menu.Designer
+- TableV2.Column.Designer
+- TableV2.ActionColumnDesigner
+- TableBlockDesigner
+- TableSelectorDesigner
+- Tabs.Designer
+
+## 替换
+
+```tsx | pure
+import React, { useContext } from 'react';
+import { useFieldSchema } from '@formily/react';
+import {
+  SchemaComponentOptions,
+  GeneralSchemaDesigner,
+  SchemaSettings,
+  useCollection
+} from '@nocobase/client';
+import React from 'react';
+
+const CustomActionDesigner = () => {
+  const { name, title } = useCollection();
+  const fieldSchema = useFieldSchema();
+  return (
+    <GeneralSchemaDesigner title={title || name}>
+      <SchemaSettings.Remove
+        removeParentsIfNoChildren
+        breakRemoveOn={{
+          'x-component': 'Grid',
+        }}
+      />
+    </GeneralSchemaDesigner>
+  );
+};
+
+export default React.memo((props) => {
+  return (
+    <SchemaComponentOptions
+      components={{
+        'Action.Designer': CustomActionDesigner,
+      }}
+    >{props.children}</SchemaComponentOptions>
+  );
+});
+```
--- a/docs/zh-CN/development/guide/ui-schema-designer/x-initializer.md
+++ b/docs/zh-CN/development/guide/ui-schema-designer/x-initializer.md
@ -0,0 +1,39 @@
+# x-initializer 组件
+
+## 内置 x-initializer 组件
+
+- BlockInitializers
+- CalendarActionInitializers
+- CreateFormBlockInitializers
+- CustomFormItemInitializers
+- DetailsActionInitializers
+- FormActionInitializers
+- FormItemInitializers
+- KanbanActionInitializers
+- ReadPrettyFormActionInitializers
+- ReadPrettyFormItemInitializers
+- RecordBlockInitializers
+- RecordFormBlockInitializers
+- SubTableActionInitializers
+- TableActionColumnInitializers
+- TableActionInitializers
+- TableColumnInitializers
+- TableSelectorInitializers
+- TabPaneInitializers
+
+## 替换
+
+```tsx |pure
+import React, { useContext } from 'react';
+import { SchemaInitializerContext } from '@nocobase/client';
+
+export default React.memo((props) => {
+  const items = useContext(SchemaInitializerContext);
+  const BlockInitializers = {};
+  return (
+    <SchemaInitializerContext.Provider value={{ ...items, BlockInitializers }}>
+      {props.children}
+    </SchemaInitializerContext.Provider>
+  );
+});
+```
--- a/docs/zh-CN/development/index.md
+++ b/docs/zh-CN/development/index.md
@ -1,33 +1,34 @@
-# 概述
+# 介绍

-## 基本概念
+NocoBase 采用微内核架构，各类功能以插件形式扩展，所以微内核架构也叫插件化架构，由内核和插件两部分组成。内核提供了最小功能的 WEB 服务器，还提供了各种插件化接口；插件是按功能划分的各种独立模块，通过接口适配，具有可插拔的特点。插件化的设计降低了模块之间的耦合度，提高了复用率。随着插件库的不断扩充，常见的场景只需要组合插件即可完成基础搭建。例如 NocoBase 的无代码平台，就是由各种插件组合起来。

-## 特性
+<img src="./guide/pm-built-in.jpg"/>

-NocoBase 的核心是一个基于微内核、插件化设计的开发框架。在此基础上天然的支持任意的扩展开发。
+## 插件管理器
+
+NocoBase 提供了强大的插件管理器用于管理插件，开发可以通过 CLI 的方式管理插件，也可以通过界面激活、禁用已添加的插件。如：
+
+```bash
+# 创建插件
+yarn pm create hello
+# 注册插件
+yarn pm add hello
+# 激活插件
+yarn pm enable hello
+# 禁用插件
+yarn pm disable hello
+# 删除插件
+yarn pm remove hello
+```
+
+更多插件示例，查看 [packages/samples](https://github.com/nocobase/nocobase/tree/main/packages/samples)。

 ## 扩展能力

-基于 NocoBase 的微内核设计，在很多模块都考虑相应的可扩展性，并向外部暴露了一些扩展点，几乎覆盖全部的应用生命周期，在具体业务中可以根据需求基于众多扩展点进行相应的扩展。详情参考 [扩展索引](/development/guide)。
+无论是通用性的功能，还是个性化定制，都建议以插件的形式编写，NocoBase 的扩展性体现在方方面面：

-## 插件生命周期
+- 可以是用户直观可见的界面相关的页面模块、区块类型、操作类型、字段类型等
+- 也可以是用于增强或限制 HTTP API 的过滤器、校验器、访问限制等
+- 也可以是更底层的数据表、迁移、事件、命令行等功能的增强

-### 下载
-
-### 注册
-
-### 安装
-
-### 启用
-
-### 加载
-
-### 停用
-
-### 卸载
-
-## 学习路线
-
-1. 编写第一个插件
-2. 数据表建模
-3. 
+不仅如此，更多扩展介绍请查看[扩展点索引]()章节。
--- a/docs/zh-CN/development/learning-guide.md
+++ b/docs/zh-CN/development/learning-guide.md
@ -0,0 +1,30 @@
+# 学习路线指南
+
+## 1. 从安装 NocoBase 开始
+
+NocoBase 支持三种安装方式：
+
+- Docker 安装（推荐）
+- create-nocobase-app 安装
+- Git 源码安装
+
+## 2. 了解 NocoBase CLI
+
+NocoBase CLI 旨在帮助你开发、构建和部署 NocoBase 应用。
+
+最常用的命令包括：
+
+- `yarn nocobase install`
+- `yarn nocobase upgrade`
+- `yarn dev`
+- `yarn test`
+- `yarn start`
+- `yarn build`
+- `yarn pm <method> <plugin>`
+
+## 3. 了解插件管理器
+
+```bash
+yarn pm <method> <plugin>
+```
+