docs: improve doc for plugin related apis

JackLian · liujuping · commit 9d83b8b5b9a9 · 2023-02-15T17:15:12.000+08:00
diff --git a/docs/docs/api/plugins.md b/docs/docs/api/plugins.md
@@ -118,11 +118,13 @@ import { IPublicModelPluginContext } from '@alilc/lowcode-types';
 const BuiltinPluginRegistry = (ctx: IPublicModelPluginContext, options: any) => {
   return {
     async init() {
-      // 1.0.4 之后的传值方式，通过 register(xxx, options)
-      // 取值通过 options
+      // 直接传值方式：
+      //   通过 register(xxx, options) 传入
+      //   通过 options 取出
 
-      // 1.0.4 之前的传值方式，通过 init(..., preference)
-      // 取值通过 ctx.preference.getValue()
+      // 引擎初始化时也可以设置某插件的全局配置项：
+      //   通过 engine.init(..., preference) 传入
+      //   通过 ctx.preference.getValue() 取出
     },
   };
 }
@@ -155,7 +157,6 @@ BuiltinPluginRegistry.meta = {
   },
 }
 
-// 从 1.0.4 开始，支持直接在 pluginCreator 的第二个参数 options 获取入参
 await plugins.register(BuiltinPluginRegistry, { key1: 'abc', key5: 'willNotPassToPlugin' });
 ```
 
@@ -164,8 +165,11 @@ await plugins.register(BuiltinPluginRegistry, { key1: 'abc', key5: 'willNotPassT
 获取指定插件
 
 ```typescript
-function get(pluginName: string): IPublicModelPluginInstance;
-
+/**
+ * 获取指定插件
+ * get plugin instance by name
+ */
+get(pluginName: string): IPublicModelPluginInstance | null;
 ```
 
 关联模型 [IPublicModelPluginInstance](./model/plugin-instance)
@@ -175,8 +179,11 @@ function get(pluginName: string): IPublicModelPluginInstance;
 获取所有的插件实例
 
 ```typescript
-function getAll(): IPublicModelPluginInstance[];
-
+/**
+ * 获取所有的插件实例
+ * get all plugin instances
+ */
+getAll(): IPublicModelPluginInstance[];
 ```
 
 关联模型 [IPublicModelPluginInstance](./model/plugin-instance)
@@ -186,17 +193,37 @@ function getAll(): IPublicModelPluginInstance[];
 判断是否有指定插件
 
 ```typescript
-function has(pluginName: string): boolean;
-
+/**
+ * 判断是否有指定插件
+ * check if plugin with certain name exists
+ */
+has(pluginName: string): boolean;
 ```
 
 ### delete
 
 删除指定插件
 
 ```typescript
-function delete(pluginName: string): void;
+/**
+ * 删除指定插件
+ * delete plugin instance by name
+ */
+delete(pluginName: string): void;
+```
 
+### getPluginPreference
+
+引擎初始化时可以提供全局配置给到各插件，通过这个方法可以获得本插件对应的配置
+
+```typescript
+/**
+ * 引擎初始化时可以提供全局配置给到各插件，通过这个方法可以获得本插件对应的配置
+ * use this to get preference config for this plugin when engine.init() called
+ */
+getPluginPreference(
+    pluginName: string,
+  ): Record<string, IPublicTypePreferenceValueType> | null | undefined;
 ```
 
 ## 相关类型定义
diff --git a/packages/designer/src/plugin/plugin-types.ts b/packages/designer/src/plugin/plugin-types.ts
@@ -26,12 +26,12 @@ export interface ILowCodePluginRuntimeCore {
   disabled: boolean;
   config: IPublicTypePluginConfig;
   logger: IPublicApiLogger;
+  meta: IPublicTypePluginMeta;
   init(forceInit?: boolean): void;
   isInited(): boolean;
   destroy(): void;
   toProxy(): any;
   setDisabled(flag: boolean): void;
-  meta: IPublicTypePluginMeta;
 }
 
 interface ILowCodePluginRuntimeExportsAccessor {
diff --git a/packages/shell/src/model/plugin-instance.ts b/packages/shell/src/model/plugin-instance.ts
@@ -28,4 +28,4 @@ export class PluginInstance implements IPublicModelPluginInstance {
   get meta() {
     return this[pluginInstanceSymbol].meta;
   }
-}
+}
diff --git a/packages/types/src/shell/api/plugins.ts b/packages/types/src/shell/api/plugins.ts
@@ -20,21 +20,34 @@ export interface IPublicApiPlugins {
   ): Promise<void>;
 
   /**
-   * @deprecated use options instead
+   * 引擎初始化时可以提供全局配置给到各插件，通过这个方法可以获得本插件对应的配置
+   * use this to get preference config for this plugin when engine.init() called
    */
   getPluginPreference(
       pluginName: string,
     ): Record<string, IPublicTypePreferenceValueType> | null | undefined;
 
-  /** 获取指定插件 */
+  /**
+   * 获取指定插件
+   * get plugin instance by name
+   */
   get(pluginName: string): IPublicModelPluginInstance | null;
 
-  /** 获取所有的插件实例 */
+  /**
+   * 获取所有的插件实例
+   * get all plugin instances
+   */
   getAll(): IPublicModelPluginInstance[];
 
-  /** 判断是否有指定插件 */
+  /**
+   * 判断是否有指定插件
+   * check if plugin with certain name exists
+   */
   has(pluginName: string): boolean;
 
-  /** 删除指定插件 */
+  /**
+   * 删除指定插件
+   * delete plugin instance by name
+   */
   delete(pluginName: string): void;
-}
+}
diff --git a/packages/types/src/shell/model/plugin-context.ts b/packages/types/src/shell/model/plugin-context.ts
@@ -14,11 +14,26 @@ import {
 import { IPublicModelEngineConfig } from './';
 
 export interface IPublicModelPluginContext {
+
+  /**
+   * 对于插件开发者来说，可以在 context 挂载自定义的内容，作为插件内全局上下文使用
+   *
+   * for plugin developers, costom properties can be add to plugin context
+   * from inside plugin for convenience.
+   */
+  [key: string]: any;
+
+  /**
+   * 可通过该对象读取插件初始化配置
+   * by using this, init options can be accessed from inside plugin
+   */
+  preference: IPluginPreferenceMananger;
   get skeleton(): IPublicApiSkeleton;
   get hotkey(): IPublicApiHotkey;
   get setters(): IPublicApiSetters;
   get config(): IPublicModelEngineConfig;
   get material(): IPublicApiMaterial;
+
   /**
    * this event works globally, can be used between plugins and engine.
    */
@@ -33,8 +48,6 @@ export interface IPublicModelPluginContext {
    */
   get pluginEvent(): IPublicApiEvent;
   get canvas(): IPublicApiCanvas;
-  preference: IPluginPreferenceMananger;
-  [key: string]: any;
 }
 
 /**
@@ -44,4 +57,4 @@ export interface IPublicModelPluginContext {
  */
 export interface ILowCodePluginContext extends IPublicModelPluginContext {
 
-}
+}
diff --git a/packages/types/src/shell/model/plugin-instance.ts b/packages/types/src/shell/model/plugin-instance.ts
@@ -1,11 +1,28 @@
 import { IPublicTypePluginMeta } from '../type/plugin-meta';
 
 export interface IPublicModelPluginInstance {
-  pluginName: string;
-
-  dep: string[];
 
+  /**
+   * 是否 disable
+   * current plugin instance is disabled or not
+   */
   disabled: boolean;
 
-  meta: IPublicTypePluginMeta;
-}
+  /**
+   * 插件名称
+   * plugin name
+   */
+  get pluginName(): string;
+
+  /**
+   * 依赖信息，依赖的其他插件
+   * depenency info
+   */
+  get dep(): string[];
+
+  /**
+   * 插件配置元数据
+   * meta info of this plugin
+   */
+  get meta(): IPublicTypePluginMeta;
+}

Original file line number	Diff line number	Diff line change
`@@ -28,4 +28,4 @@ export class PluginInstance implements IPublicModelPluginInstance {`
`28`	`28`	`get meta() {`
`29`	`29`	`return this[pluginInstanceSymbol].meta;`
`30`	`30`	`}`
`31`		`-}`
	`31`	`+}`