From 0d12aaa02d47b502bd03ee094f7d3460cbacf817 Mon Sep 17 00:00:00 2001 From: lyn-boyu Date: Sun, 21 Nov 2021 15:21:29 +0800 Subject: [PATCH] docs: add custom panel --- packages/xflow-core/src/common/rx-model.ts | 2 +- packages/xflow-docs/.umirc.ts | 14 +-- .../xflow-docs/docs/api/interface/hook.md | 5 +- .../xflow-docs/docs/api/interface/model.md | 21 +++++ packages/xflow-docs/docs/index.en-US.md | 2 +- packages/xflow-docs/docs/index.zh-CN.md | 2 +- packages/xflow-docs/docs/index.zh.md | 2 +- .../docs/tutorial/advanced/command/index.md | 61 ++++++++++++- .../docs/tutorial/advanced/hook/index.md | 77 +++++++++++++++- .../docs/tutorial/advanced/index.md | 15 ++-- .../docs/tutorial/advanced/model/index.md | 88 ++++++++++++++++++- packages/xflow-docs/docs/tutorial/contact.md | 13 --- .../docs/tutorial/getting-started/index.zh.md | 4 +- 13 files changed, 261 insertions(+), 45 deletions(-) delete mode 100644 packages/xflow-docs/docs/tutorial/contact.md diff --git a/packages/xflow-core/src/common/rx-model.ts b/packages/xflow-core/src/common/rx-model.ts index 874aec3d..2befa6c6 100644 --- a/packages/xflow-core/src/common/rx-model.ts +++ b/packages/xflow-core/src/common/rx-model.ts @@ -16,7 +16,7 @@ export namespace NsModel { export interface IModel { /** 传入一个回调函数来订阅model的变化 */ watch: IWatch - /** 更新model：有两种更新模式 */ + /** 更新model: 支持传值或者传入更新函数 */ setValue: ISetValue /** 获取model的值 */ getValue: () => T | EmptyType diff --git a/packages/xflow-docs/.umirc.ts b/packages/xflow-docs/.umirc.ts index fc32e856..c9e776aa 100644 --- a/packages/xflow-docs/.umirc.ts +++ b/packages/xflow-docs/.umirc.ts @@ -8,6 +8,7 @@ export default defineConfig({ logo: 'https://gw.alipayobjects.com/zos/antfincdn/FLrTNDvlna/antv.png', favicon: 'https://gw.alipayobjects.com/zos/antfincdn/FLrTNDvlna/antv.png', // publicPath: process.env.NODE_ENV === 'production' ? basementPublicPath : '/', + runtimePublicPath: true, resolve: { includes: ['docs'], @@ -36,16 +37,9 @@ export default defineConfig({ ['en-US', 'English'], ], navs: { - 'zh-CN': [ - null, - { title: 'GitHub', path: 'https://github.com/alibaba/hooks' }, - { title: '更新日志', path: 'https://github.com/alibaba/hooks/releases' }, - ], - 'en-US': [ - null, - { title: 'GitHub', path: 'https://github.com/alibaba/hooks' }, - { title: 'Changelog', path: 'https://github.com/alibaba/hooks/releases' }, - ], + zh: [null, { title: 'GitHub', path: 'https://github.com/antvis/XFlow' }], + 'zh-CN': [null, { title: 'GitHub', path: 'https://github.com/antvis/XFlow' }], + 'en-US': [null, { title: 'GitHub', path: 'https://github.com/antvis/XFlow' }], }, styles: ['.__dumi-default-previewer-demo{ min-height: 290px }'], /** css */ diff --git a/packages/xflow-docs/docs/api/interface/hook.md b/packages/xflow-docs/docs/api/interface/hook.md index d188a51f..fa665091 100644 --- a/packages/xflow-docs/docs/api/interface/hook.md +++ b/packages/xflow-docs/docs/api/interface/hook.md @@ -17,10 +17,13 @@ nav: /** 如何引入？ */ import { IHookService } from '@antv/xflow' -/** 边数据 */ +/** 钩子服务 */ export interface IHookService { + /** 注册一个新的插槽 */ registerHookHub: (hookName: string, hook: HookHub) => Disposable + /** 在插槽中插入一个钩子 */ registerHook: (registerHookFunc: IRegsiterHookFn) => Disposable + /** 钩子服务返回所有钩子 */ hookProvider: () => T } ``` diff --git a/packages/xflow-docs/docs/api/interface/model.md b/packages/xflow-docs/docs/api/interface/model.md index 0a1b8543..af675607 100644 --- a/packages/xflow-docs/docs/api/interface/model.md +++ b/packages/xflow-docs/docs/api/interface/model.md @@ -29,3 +29,24 @@ export interface IModelService { findDeferredModel: (token: Token) => undefined | Deferred> } ``` + +## IModel + +```tsx | pure +import { NsModel } from '@ali/xflow' +// NsModel.IModel + +/** model的类型 */ +export interface IModel { + /** 传入一个回调函数来订阅model的变化 */ + watch: IWatch + /** 更新model: 支持传值或者传入更新函数 */ + setValue: ISetValue + /** 获取model的值 */ + getValue: () => T | EmptyType + /** 是否有非空的值 */ + hasValidValue: () => boolean + /** 通过Promise获取一个非空值 */ + getValidValue: () => Promise +} +``` diff --git a/packages/xflow-docs/docs/index.en-US.md b/packages/xflow-docs/docs/index.en-US.md index 1ca1381d..4c468805 100644 --- a/packages/xflow-docs/docs/index.en-US.md +++ b/packages/xflow-docs/docs/index.en-US.md @@ -7,7 +7,7 @@ banner: image: https://gw.alipayobjects.com/mdn/rms_00edcb/afts/img/A*Gix7Rry3-5wAAAAAAAAAAABkARQnAQ actions: - text: 快速开始 -> - link: /docs/tutorial/quick-start + link: /docs/tutorial/intro/getting-started type: primary notifications: - type: Heavy Released diff --git a/packages/xflow-docs/docs/index.zh-CN.md b/packages/xflow-docs/docs/index.zh-CN.md index 3ebf4eae..0a259769 100644 --- a/packages/xflow-docs/docs/index.zh-CN.md +++ b/packages/xflow-docs/docs/index.zh-CN.md @@ -7,7 +7,7 @@ banner: image: https://gw.alipayobjects.com/mdn/rms_00edcb/afts/img/A*Gix7Rry3-5wAAAAAAAAAAABkARQnAQ actions: - text: 快速开始 -> - link: /docs/tutorial/quick-start + link: /docs/tutorial/intro/getting-started type: primary notifications: - type: Heavy Released diff --git a/packages/xflow-docs/docs/index.zh.md b/packages/xflow-docs/docs/index.zh.md index 3ebf4eae..0a259769 100644 --- a/packages/xflow-docs/docs/index.zh.md +++ b/packages/xflow-docs/docs/index.zh.md @@ -7,7 +7,7 @@ banner: image: https://gw.alipayobjects.com/mdn/rms_00edcb/afts/img/A*Gix7Rry3-5wAAAAAAAAAAABkARQnAQ actions: - text: 快速开始 -> - link: /docs/tutorial/quick-start + link: /docs/tutorial/intro/getting-started type: primary notifications: - type: Heavy Released diff --git a/packages/xflow-docs/docs/tutorial/advanced/command/index.md b/packages/xflow-docs/docs/tutorial/advanced/command/index.md index beea2d03..bd939011 100644 --- a/packages/xflow-docs/docs/tutorial/advanced/command/index.md +++ b/packages/xflow-docs/docs/tutorial/advanced/command/index.md @@ -1,5 +1,6 @@ --- title: Command +order: 2 group: path: /tutorial-advanced title: 自定义组件 @@ -12,10 +13,64 @@ nav: ## Command + + ### 概念说明 -Command 是 +Command 是解耦 UI 组件和 Graph 的关键，所有对 Graph 的操作都通过 CommandService.executeCommand 来完成，我们需要知道： + +1. 如何获取 CommandService +2. 如何调用 CommandService +3. 如何使用类型 + +### 如何使用 + +### 如何获取 CommandService + +CommandService 在 XFlow 内部无处不在，入口分为两种： + +1. React 组件内部使用： 通过 useXFlowApp 来获取 CommandService +2. XFlow 组件的配置项中使用：通过函数的参数可以获得 CommandService + +#### 第一种：React 组件内部使用 + +在 XFlow 组件内部我们可以获得 App App 上就有 CommandService 可以使用 + +```tsx | pure +import { useXFlowApp, XFlowGraphCommands, NsGraphCmd } from '@antv/xflow' + +export const GroupNode: NsGraph.INodeRender = props => { + const { cell } = props + const app = useXFlowApp() + return ( +
+ +
+ ) +} +``` + +#### 第二种：组件的配置项中使用 + +XFlow 的所有组件配置的所有事件函数的参数中都包含了 CommandService，比如 setEvents 的时候，仔细看下 IEvent 的函数签名 -### 如何扩展 +```tsx | pure +import { createGraphConfig } from '@antv/xflow' -通过以下的方式可以扩展 Command +export const useGraphConfig = createGraphConfig(config => { + const event: IEvent<'node:click'> = { + eventName: 'node:click', + callback: (eventArgs, commandService) => { + console.log('node:click', e) + }, + } + /** 这里绑定事件 */ + config.setEvents([event]) +}) +``` diff --git a/packages/xflow-docs/docs/tutorial/advanced/hook/index.md b/packages/xflow-docs/docs/tutorial/advanced/hook/index.md index c3b44949..4bf30c9b 100644 --- a/packages/xflow-docs/docs/tutorial/advanced/hook/index.md +++ b/packages/xflow-docs/docs/tutorial/advanced/hook/index.md @@ -1,5 +1,6 @@ --- title: Hook +order: 5 group: path: /tutorial-advanced title: 自定义组件 @@ -12,10 +13,80 @@ nav: ## Hook + + ### 概念说明 -Hook 是 +在 XFlow 中扩展逻辑都是通过 Hook 来完成，XFlow 内部可以注册 Hook 逻辑来完成对 Graph 配置和 Command 的 扩展 + +1. 如何新建 Hook 的配置项 +2. 有哪些 hook 可以使用 + +### 如何使用 + +### 如何新建 Hook 的配置项 + +```tsx | pure +import type { NsGraph } from '@antv/xflow' +import { XFlow, createHookConfig, DisposableCollection } from '@antv/xflow' + +export const useGraphHookConfig = createHookConfig(config => { + config.setRegisterHook(hooks => { + const disposableList = [ + // 注册增加 graph options + hooks.graphOptions.registerHook({ + name: 'custom-x6-options', + // before: 'dag-extension-x6-options', + handler: async options => { + options.grid = false + options.keyboard = { + enabled: true, + } + }, + }), + ] + const toDispose = new DisposableCollection() + toDispose.pushAll(disposableList) + return toDispose + }) +}) + +export const Demo = () => { + const graphHooksConfig = useGraphHookConfig(props) + return +} +``` + +### 有哪些 hook 可以使用 + +Hook 可以分为两种类型： + +1. GraphHook： 配置 Graph 相关的配置项 +2. CommandHook：配置可以修改 Command 参数的逻辑 + +#### GraphHook + +```tsx | pure +type IHooks = { + /* x6 graph 配置项 */ + graphOptions: HookHub + /* 绑定X6的事件 */ + x6Events: HookHub + /* 自定义节点React组件 */ + reactNodeRender: HookHub> + /* 自定义连线label的React组件 */ + reactEdgeLabelRender: HookHub> + /* 在Graph 实例化后执行的逻辑 */ + afterGraphInit: HookHub + /* 在Graph 销毁前执行的逻辑 */ + beforeGraphDestory: HookHub +} +``` + +#### CommandHook -### 如何扩展 +可以配置 Command 执行参数的扩展逻辑 -通过以下的方式可以扩展 Hook +```tsx | pure +type IHooks = INodeHooks & IEdgeHooks & IGroupHooks & IGraphHooks & IModelHooks +``` diff --git a/packages/xflow-docs/docs/tutorial/advanced/index.md b/packages/xflow-docs/docs/tutorial/advanced/index.md index b065fe1e..be5e257e 100644 --- a/packages/xflow-docs/docs/tutorial/advanced/index.md +++ b/packages/xflow-docs/docs/tutorial/advanced/index.md @@ -1,5 +1,6 @@ --- title: 如何扩展 +order: 1 group: path: /tutorial-advanced title: 自定义组件 @@ -14,10 +15,14 @@ nav: image.png +### UI 组件 和 Graph 的调用关系 + + + ## 核心模块 -| 名称 | 配置项 | 描述 | -| -----------------------------------------: | -------------------------: | -------------------------- | -| [Model](/docs/tutorial-advanced/model) | createContextServiceConfig | 全局状态 | -| [Hook](/docs/tutorial-advanced/hook) | createHookConfig | 扩展 Command 逻辑 | -| [Command](/docs/tutorial-advanced/command) | createCmdConfig | 执行 X6 api/改变 全局 状态 | +| 名称 | 配置项 | 描述 | +| -----------------------------------------: | -----------------------: | --------------------------------------- | +| [Model](/docs/tutorial-advanced/model) | createModelServiceConfig | 使用全局状态 | +| [Command](/docs/tutorial-advanced/command) | createCmdConfig | 使用 Command 执行 X6 api/改变 全局 状态 | +| [Hook](/docs/tutorial-advanced/hook) | createHookConfig | 使用 Hook 扩展 Command 逻辑 | diff --git a/packages/xflow-docs/docs/tutorial/advanced/model/index.md b/packages/xflow-docs/docs/tutorial/advanced/model/index.md index 9863ea9a..51a7776b 100644 --- a/packages/xflow-docs/docs/tutorial/advanced/model/index.md +++ b/packages/xflow-docs/docs/tutorial/advanced/model/index.md @@ -1,5 +1,6 @@ --- title: Model +order: 3 group: path: /tutorial-advanced title: 自定义组件 @@ -10,12 +11,91 @@ nav: order: 1 --- -## Model +## ModelService + + ### 概念说明 -Model 是 +在 XFlow 通过 Model 来驱动 React UI 组件更新渲染，我们通过监听事件可以在事件的回调函数中调用 Model 的 setValue 方法 来更新 Model，UI 组件中通过 Model 的 watch 方法来更新组件内部的 State，从而实现组件渲染的更新。 接下来我们需要了解以下几个概念： + +1. 如何获取 ModelService +2. 如何消费 XFlow 内置的 ModelService +3. 如何生产 XFlow 的 自定义 Model + +### 如何获取 ModelService + +CommandService 在 XFlow 内部无处不在，入口分为两种： + +1. React 组件内部使用： 通过 useXFlowApp 来获取 CommandService +2. XFlow 组件的配置项中使用：通过函数的参数可以获得 CommandService + +### 如何消费 内置的 Model + +可以通过以下方式获取内置 Model 的值,查看[所有的 Model](/api/models) + +```tsx | pure +// 如何使用？ +import { MODELS } from '@antv/xflow' +// 使用models +const getModel = async () => { + /** value */ + const graphScale = await MODELS.GRAPH_SCALE.useValue(modelService) + /** model */ + const graphScaleModel = await MODELS.GRAPH_SCALE.getModel(modelService) + console.log(graphScale, graphScaleModel) +} +``` + +### 如何生产 Model + +```tsx | pure +import type { IModelService } from '@antv/xflow' +import { XFlow, createModelServiceConfig } from '@antv/xflow' + +export namespace NS_LOADING_STATE { + export const id = 'custom-loading' + export interface IState { + loading: boolean + } + export const getValue = async (contextService: IModelService) => { + const ctx = await contextService.awaitModel(NS_LOADING_STATE.id) + return ctx.getValidValue() + } +} + +export const useModelServiceConfig = createModelServiceConfig(config => { + config.registerModel(registry => { + return registry.registerModel({ + id: NS_LOADING_STATE.id, + getInitialValue: () => { + loading: true + }, + }) + }) +}) +export const Demo = () => { + const modelServiceConfig = useModelServiceConfig() + return +} +``` + +## API -### 如何扩展 +通过以下的方式可以使用 Model -通过以下的方式可以扩展 Model +```tsx | pure +/** model的类型 */ +export interface IModel { + /** 传入一个回调函数来订阅model的变化 */ + watch: IWatch + /** 更新model: 支持传值或者传入更新函数 */ + setValue: ISetValue + /** 获取model的值 */ + getValue: () => T | EmptyType + /** 是否有非空的值 */ + hasValidValue: () => boolean + /** 通过Promise获取一个非空值 */ + getValidValue: () => Promise +} +``` diff --git a/packages/xflow-docs/docs/tutorial/contact.md b/packages/xflow-docs/docs/tutorial/contact.md deleted file mode 100644 index 2154cbcb..00000000 --- a/packages/xflow-docs/docs/tutorial/contact.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: 联系我们 -group: - path: /contact - title: 联系我们 - order: 9 -nav: - title: 教程 - path: /docs - order: 1 ---- - -## 联系我们 diff --git a/packages/xflow-docs/docs/tutorial/getting-started/index.zh.md b/packages/xflow-docs/docs/tutorial/getting-started/index.zh.md index 36b6283c..dd6941a7 100644 --- a/packages/xflow-docs/docs/tutorial/getting-started/index.zh.md +++ b/packages/xflow-docs/docs/tutorial/getting-started/index.zh.md @@ -40,9 +40,9 @@ $ yarn add @antv/xflow 对于生产环境, 我们推荐使用一个明确的版本号, 以避免新版本升级造成不可预期的破坏: -- https://unpkg.com/@antv/xflow@0.3.2-beta.1/dist/index.umd.js +- https://unpkg.com/@antv/xflow@1.0.0/dist/index.umd.js -- https://cdn.jsdelivr.net/npm/@antv/xflow@0.3.2-beta.1/dist/index.umd.js +- https://cdn.jsdelivr.net/npm/@antv/xflow@1.0.0/dist/index.umd.js 需要注意的是: