From 30e6e7035b9489e14d5bced6ba7abc84ce3672d6 Mon Sep 17 00:00:00 2001 From: JackLian Date: Wed, 15 Feb 2023 17:07:04 +0800 Subject: [PATCH] docs: improve doc for plugin related apis --- docs/docs/api/plugins.md | 51 ++++++++++++++----- packages/designer/src/plugin/plugin-types.ts | 2 +- packages/shell/src/model/plugin-instance.ts | 2 +- packages/types/src/shell/api/plugins.ts | 25 ++++++--- .../types/src/shell/model/plugin-context.ts | 19 +++++-- .../types/src/shell/model/plugin-instance.ts | 27 ++++++++-- 6 files changed, 98 insertions(+), 28 deletions(-) diff --git a/docs/docs/api/plugins.md b/docs/docs/api/plugins.md index 58be1fde0..e35411d3a 100644 --- 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,8 +193,11 @@ function getAll(): IPublicModelPluginInstance[]; 判断是否有指定插件 ```typescript -function has(pluginName: string): boolean; - +/** + * 判断是否有指定插件 + * check if plugin with certain name exists + */ +has(pluginName: string): boolean; ``` ### delete @@ -195,8 +205,25 @@ function has(pluginName: string): boolean; 删除指定插件 ```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 | null | undefined; ``` ## 相关类型定义 diff --git a/packages/designer/src/plugin/plugin-types.ts b/packages/designer/src/plugin/plugin-types.ts index 8c246a5d2..837fae4b1 100644 --- 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 index 47a619482..156ec7579 100644 --- 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; } -} \ No newline at end of file +} diff --git a/packages/types/src/shell/api/plugins.ts b/packages/types/src/shell/api/plugins.ts index 32e13c3b6..518362b97 100644 --- a/packages/types/src/shell/api/plugins.ts +++ b/packages/types/src/shell/api/plugins.ts @@ -20,21 +20,34 @@ export interface IPublicApiPlugins { ): Promise; /** - * @deprecated use options instead + * 引擎初始化时可以提供全局配置给到各插件，通过这个方法可以获得本插件对应的配置 + * use this to get preference config for this plugin when engine.init() called */ getPluginPreference( pluginName: string, ): Record | 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; -} \ No newline at end of file +} diff --git a/packages/types/src/shell/model/plugin-context.ts b/packages/types/src/shell/model/plugin-context.ts index cc989ac76..ae7ef8bbb 100644 --- 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 { -} \ No newline at end of file +} diff --git a/packages/types/src/shell/model/plugin-instance.ts b/packages/types/src/shell/model/plugin-instance.ts index 7855d903b..88904205d 100644 --- 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; -} \ No newline at end of file + /** + * 插件名称 + * plugin name + */ + get pluginName(): string; + + /** + * 依赖信息，依赖的其他插件 + * depenency info + */ + get dep(): string[]; + + /** + * 插件配置元数据 + * meta info of this plugin + */ + get meta(): IPublicTypePluginMeta; +}