From 296fbd6c08744e50ebc391ea81c6187bb835a8a1 Mon Sep 17 00:00:00 2001 From: chenos Date: Wed, 17 Nov 2021 18:54:32 +0800 Subject: [PATCH] feat(doc): update api doc --- docs/components/index.zh-CN.md | 65 ++++++++++++++- docs/plugins/collections.md | 135 +++++++++++++++++++++++++++++++ docs/plugins/permissions.md | 3 + docs/reference/application.md | 24 +++--- docs/reference/cli.md | 10 +-- docs/reference/client.md | 10 +-- docs/reference/collection.md | 2 +- docs/reference/context.md | 2 +- docs/reference/operators.md | 2 +- docs/reference/plugin-manager.md | 2 +- docs/reference/plugin.md | 2 +- 11 files changed, 230 insertions(+), 27 deletions(-) create mode 100644 docs/plugins/collections.md create mode 100644 docs/plugins/permissions.md diff --git a/docs/components/index.zh-CN.md b/docs/components/index.zh-CN.md index 3f41ab09ed..893fd516f8 100644 --- a/docs/components/index.zh-CN.md +++ b/docs/components/index.zh-CN.md @@ -59,6 +59,64 @@ const SchemaComponent = createSchemaComponent({ /> ``` +SchemaComponent 是通过 Schema 协议渲染的组件，SchemaComponent 可能由多个原子组件组合而成。 + +```ts +interface ISchema { + type: string; + name?: string; + title?: any; + properties?: any; + ['x-component']?: any; + ['x-component-props']?: any; + ['x-decorator']?: any; + ['x-decorator-props']?: any; + ['x-designable-bar']?: any; + ['x-designable-bar-props']?: any; +} +``` + +Schema 组件的完整结构如下： + +
+
+  
+  
+    {...properties}
+  
+
+
+ +DesignableBar 可以用于修改当前 SchemaComponent 的 Schema。可以以任意形态出现，例如： + +
+function DesignableBar() {
+  // 这里是随意写的，当前 schema，可以 update，remove 等等
+  const { schema, update, remove } = useDesignableSchema();
+  return (
+    
+      
+          配置项1
+          配置项2
+          配置项3
+        
+      }>
+        配置
+      
+      
+        配置
+      
+      
+        配置
+      
+    
+  )
+}
+
+ +如果 DesignableBar 只是修改当前层级的参数比较好处理，但是如果修改的是 properties 子节点里的参数，情况会变得比较复杂。 + ## 字段组件 ```ts @@ -82,7 +140,6 @@ const string: FieldOptions = { }, }, properties: { - }, operations: [ { label: '包含', value: '$includes', selected: true }, @@ -92,10 +149,14 @@ const string: FieldOptions = { { label: '非空', value: '$notNull', noValue: true }, { label: '为空', value: '$null', noValue: true }, ], + designableBar: { + key1: {}, + key2: {}, + }, }; const CollectionField = createCollectionField({ - interface: { + interfaces: { string, }, }) diff --git a/docs/plugins/collections.md b/docs/plugins/collections.md new file mode 100644 index 0000000000..05618b48c3 --- /dev/null +++ b/docs/plugins/collections.md @@ -0,0 +1,135 @@ +# @nocobase/plugin-collections + +提供 HTTP API 的方式管理数据表和字段 + +## HTTP API + +### Collections + +```bash +GET /api/collections +POST /api/collections +GET /api/collections/ +PUT /api/collections/ +DELETE /api/collections/ +``` + +### Fields + +```bash +GET /api/collections//fields +POST /api/collections//fields +GET /api/collections//fields/ +PUT /api/collections//fields/ +DELETE /api/collections//fields/ +``` + + + +- 方便开发使用，API Route 上直接暴露的是 collectionName 和 fieldName，这样的可读性更好，但是如果修改了 collectionName 和 fieldName，可能会导致很多不可预知问题，所以要谨慎修改，或者不允许修改。 +- fieldName 只在某 collectionName 下是唯一的。fields 表要为 collectionName 和 fieldName 建立唯一索引。 + + + +## Repository API + +### CollectionRepository.load() + +将符合条件的 collections 配置导入 db.collections + +##### Definition + +```ts +class CollectionRepository extends Repository { + async load(options?: LoadOptions): void; +} +``` + +##### Examples + +```ts +const Collection = db.getCollection('collections'); +await Collection.repository.load({ + filter: {}, +}); +``` + +## Model API + +### CollectionModel.migrate() + +##### Definition + +```ts +class CollectionModel extends Model { + migrate(options?: MigrateOptions): Promise; +} +``` + +##### Examples + +```ts +const collection = await Collection.repository.create({ + name: 'tests', +}); +await collection.migrate(); +``` + +### FieldModel.migrate() + +##### Definition + +```ts +class FieldModel extends Model { + migrate(options?: MigrateOptions): Promise; +} +``` + +##### Examples + +```ts +const Field = db.getCollection('fields'); +const field = await Field.repository.create({ + type: 'string', + name: 'title', + collectionName: 'tests', +}); +await field.migrate(); +``` + +## plugin-collections 和 db.collection() 的区别 + +- plugin-collections 增加了绑定组件的相关参数：interface、uiSchema +- plugin-collections 的配置存储在数据表里，再同步给 db.collection() +- db.collection() 适用于配置较固定的系统表 +- plugin-collections 适用于配置业务表 + +## Examples + + +例子待补充 + + +简单的配置 + +```ts +Collection.repository.create({ + name: 'tests', + fields: [ + { type: 'string', name: 'title' }, + { type: 'text', name: 'content' }, + ], +}); +``` + +带 uiSchema 的配置 + +```ts +Collection.repository.create({ + name: 'tests', + fields: [ + { type: 'string', name: 'title' }, + { type: 'text', name: 'content', uiSchema: {}, interface: 'markdown' }, + ], +}); +``` diff --git a/docs/plugins/permissions.md b/docs/plugins/permissions.md new file mode 100644 index 0000000000..57e50de846 --- /dev/null +++ b/docs/plugins/permissions.md @@ -0,0 +1,3 @@ +# @nocobase/plugin-permissions + + diff --git a/docs/reference/application.md b/docs/reference/application.md index a50a8af716..43b41fc2ba 100644 --- a/docs/reference/application.md +++ b/docs/reference/application.md @@ -31,7 +31,7 @@ app.db.on('xxx', () => { 资源实例 -## app.pm +## app.pm 待完善 插件管理器，详情见 [Plugin Manager](plugin-manager) @@ -71,9 +71,13 @@ app.i18n.t('Hello'); 构造器 -## app.use() +## app.use() 待完善 -中间件 +添加中间件 + +## app.unuse() 待完善 + +移除中间件 ## app.on() @@ -87,11 +91,11 @@ app.i18n.t('Hello'); 等同于 app.db.collection() -## app.actions() +## app.actions() 待完善 等同于 app.resourcer.registerActions() -## app.resource() +## app.resource() 待完善 等同于 app.resourcer.define() @@ -99,19 +103,19 @@ app.i18n.t('Hello'); 等同于 app.cli.parse() -## app.load() +## app.load() 待完善 加载配置 -## app.init() +## app.init() 待完善 初始化 -## app.start() +## app.start() 待完善 启动应用 -## app.stop() +## app.stop() 待完善 停止应用 @@ -121,4 +125,4 @@ app.i18n.t('Hello'); ## app.plugin() -等同于 app.pm.add() \ No newline at end of file +等同于 app.pm.add() diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 07e86d160a..2ff651daf8 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -2,7 +2,7 @@ toc: menu --- -# CLI +# CLI 待完善 这里的 CLI 指的是通过 app.cli 提供的默认的 commands。 @@ -23,18 +23,18 @@ toc: menu - `--force` 删除重建 -## `pm:download` +## `pm:download` 待完善 下载插件 -## `pm:enable` +## `pm:enable` 待完善 激活插件 -## `pm:disable` +## `pm:disable` 待完善 禁用插件 -## `pm:remove` +## `pm:remove` 待完善 移除插件 diff --git a/docs/reference/client.md b/docs/reference/client.md index e845d83561..33319b2ea9 100644 --- a/docs/reference/client.md +++ b/docs/reference/client.md @@ -2,15 +2,15 @@ toc: menu --- -# Client +# Client 待完善 -## APIClient +## APIClient 待完善 -## createRouteSwitch +## createRouteSwitch 待完善 -## createCollectionField +## createCollectionField 待完善 -## createSchemaComponent +## createSchemaComponent 待完善 ## i18n diff --git a/docs/reference/collection.md b/docs/reference/collection.md index 636d6ac5da..f5a0d974d7 100644 --- a/docs/reference/collection.md +++ b/docs/reference/collection.md @@ -2,7 +2,7 @@ toc: menu --- -# Collection +# Collection 待完善 ## `collection.addField()` diff --git a/docs/reference/context.md b/docs/reference/context.md index 295318bfc0..4dfaae59a3 100644 --- a/docs/reference/context.md +++ b/docs/reference/context.md @@ -24,7 +24,7 @@ async (ctx, next) { ## ctx.resourcer -## ctx.action +## ctx.action 待完善 ## ctx.i18n diff --git a/docs/reference/operators.md b/docs/reference/operators.md index 3f94edac6b..02faac1caf 100644 --- a/docs/reference/operators.md +++ b/docs/reference/operators.md @@ -2,7 +2,7 @@ toc: menu --- -# Operators +# Operators 待完善 ## string diff --git a/docs/reference/plugin-manager.md b/docs/reference/plugin-manager.md index f3d7c64b9e..e3c83789f1 100644 --- a/docs/reference/plugin-manager.md +++ b/docs/reference/plugin-manager.md @@ -2,7 +2,7 @@ toc: menu --- -# PluginManager +# PluginManager 待完善 ## pm.constructor() diff --git a/docs/reference/plugin.md b/docs/reference/plugin.md index 6c47a9ef93..402b6d2867 100644 --- a/docs/reference/plugin.md +++ b/docs/reference/plugin.md @@ -2,7 +2,7 @@ toc: menu --- -# Plugin +# Plugin 待完善 ## plugin.constructor() ## plugin.enable()