docs: 文档描述修改

2025-04-05 19:41:40 +08:00 · 2022-05-31 16:01:35 +08:00 · 2022-05-31 16:01:35 +08:00 · 1db52c36b4
commit 1db52c36b4
parent d2c936c5f0
11 changed files with 37 additions and 21 deletions
--- a/docs/package-lock.json
+++ b/docs/package-lock.json
@ -64,6 +64,11 @@
        "fastq": "^1.6.0"
      }
    },
+    "@popperjs/core": {
+      "version": "npm:@sxzz/popperjs-es@2.11.7",
+      "resolved": "https://registry.npmjs.org/@sxzz/popperjs-es/-/popperjs-es-2.11.7.tgz",
+      "integrity": "sha512-Ccy0NlLkzr0Ex2FKvh2X+OyERHXJ88XJ1MXtsI9y9fGexlaXaVTPzBCRBwIxFkORuOb+uBqeu+RqnpgYTEZRUQ=="
+    },
    "@types/debug": {
      "version": "4.1.7",
      "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.7.tgz",
@ -826,11 +831,6 @@
        "normalize-wheel-es": "^1.1.2"
      },
      "dependencies": {
-        "@popperjs/core": {
-          "version": "npm:@sxzz/popperjs-es@2.11.7",
-          "resolved": "https://registry.npmjs.org/@sxzz/popperjs-es/-/popperjs-es-2.11.7.tgz",
-          "integrity": "sha512-Ccy0NlLkzr0Ex2FKvh2X+OyERHXJ88XJ1MXtsI9y9fGexlaXaVTPzBCRBwIxFkORuOb+uBqeu+RqnpgYTEZRUQ=="
-        },
        "@vueuse/core": {
          "version": "8.5.0",
          "resolved": "https://registry.npmjs.org/@vueuse/core/-/core-8.5.0.tgz",
--- a/docs/src/admin/introduction.md
+++ b/docs/src/admin/introduction.md
@ -1,7 +1,6 @@
 # 介绍

-我们提供了与编辑器，表单配套的管理端供开发者直接使用。管理端（magic-admin）代码存放于[开源仓库](https://github.com/Tencent/tmagic-editor)"magic-admin"目录下，可作为一个独立项目运行。我们提供这个管理端一方面期望开发者可以更清晰的了解一个项目从编辑到生成的整个流程，另一方面，开发者也可以
-在 magic-admin 的基础上快速搭建适合自己业务的管理平台。
+我们提供了可视化搭建平台管理端（magic-admin）供开发者直接使用，与可视化编辑器（@tmagic/editor）、自定义表单（@tmagic/form）配套。管理端代码存放于[开源仓库](https://github.com/Tencent/tmagic-editor)"magic-admin"目录下，可作为一个独立项目运行。我们期望，一方面开发者可以更清晰的了解一个项目从编辑到生成的整个流程；另一方面，开发者也可以在 magic-admin 的基础上快速搭建适合自己业务的管理平台，构建一个完整的页面可视化搭建系统。

 管理端提供了如下能力：

--- a/docs/src/component/introduction.md
+++ b/docs/src/component/introduction.md
@ -1,6 +1,9 @@
 # 如何开发一个组件
 tmagic-editor支持业务方进行自定义组件开发。在tmagic-editor中，组件是以 npm 包形式存在的，组件和插件只要按照规范开发，就可以在tmagic-editor的 runtime 中被加入并正确渲染组件。

+## 组件开发
+以 vue3 的组件开发为例。运行项目中的 playground 示例，会自动加载 vue3 的 runtime。runtime会加载[@tmagic/ui](https://github.com/Tencent/tmagic-editor/tree/master/packages/ui)
+
 ## 组件注册
 在 [playground](https://tencent.github.io/tmagic-editor/playground/index.html#/) 中，我们可以尝试点击添加一个组件，在模拟器区域里，就会出现这个组件。其中就涉及到组件注册。

@ -8,9 +11,6 @@ tmagic-editor支持业务方进行自定义组件开发。在tmagic-editor中，

 可以参考 vue3 版本的 @tmagic/ui 中，[组件渲染](../guide/advanced/page.html#组件渲染)逻辑里，type 会作为组件名进入渲染。所以在 vue3 的组件开发中，我们也需要在为 vue 组件声明 name 字段时，和 type 值对应起来，才能正确渲染组件。

-## 组件开发
-以 vue3 的组件开发为例。目前项目中的 playground 代码，会自动加载 vue3 相关的组件库。
-
 ### 组件规范
 组件的基础形式，需要有四个文件
 - index 入口文件，引入下面几个文件
--- a/docs/src/guide/advanced/high-level-function.md
+++ b/docs/src/guide/advanced/high-level-function.md
@ -12,14 +12,14 @@ tmagic-editor的一个高级特性，就是支持开发者在不修改组件代
 - [vue runtime 执行钩子时机](https://github.com/Tencent/tmagic-editor/blob/master/packages/ui/src/useApp.ts)

 ## 函数编写
-在编辑中，即写入一个执行函数，tmagic-editor会在对应组件的指定声明周期中执行改函数。同时**传入当前组件的 Node 实例对象**，作为执行参数。
+在编辑中，即写入一个执行函数，tmagic-editor会在对应组件的指定声明周期中执行该函数。同时**传入当前组件的 Node 实例对象**，作为执行参数。

 传入的实例对象，可以根据各语言框架实现的 ui 提供的特性能力，来支持业务组件的能力实现。这个功能提供给开发者自由实现黑科技的机会。

 <img src="https://image.video.qpic.cn/oa_2a552e-0_934618672_1636348294258073">

 ### 函数参数
-在 Magic-Core 中，我们对执行钩子函数传入了对应的 Node 实例对象。在 react 和 vue 中会稍有差异。差异在于 Node 实例的 instance 属性。
+在 Magic-Core 中，我们对执行钩子函数传入了对应的 [Node](https://github.com/Tencent/tmagic-editor/blob/master/packages/core/src/Node.ts) 实例对象。在 react 和 vue 中会稍有差异。差异在于 [Node](https://github.com/Tencent/tmagic-editor/blob/master/packages/core/src/Node.ts) 实例的 instance 属性。

 - [Node 实例描述](https://github.com/Tencent/tmagic-editor/blob/master/packages/core/src/Node.ts)

--- a/docs/src/guide/advanced/js-schema.md
+++ b/docs/src/guide/advanced/js-schema.md
@ -1,5 +1,5 @@
 # JS Schema
-tmagic-editor的业务组件需要有表单配置能力，我们通过一份配置来描述表单，我们采用的描述方案是 JS schema。当我们在编辑器中配置一个页面时，页面的基本信息和页面包含的组件信息，也是采用 JS schema 描述的。JS schema 描述方案，，也是我们提供[高级函数](../advanced/high-level-function)功能的基础。
+tmagic-editor的业务组件需要有表单配置能力，我们通过一份配置来描述表单，我们采用的描述方案是 JS schema。当我们在编辑器中配置一个页面时，页面的基本信息和页面包含的组件信息，也是采用 JS schema 描述的。JS schema 描述方案，也是我们提供[高级函数](../advanced/high-level-function)功能的基础。

 组件的**配置描述**，参考[示例](../advanced/magic-form.html#示例)，是由开发者在开发组件时，通过 [@tmagic/form](../advanced/magic-form) 支持的表单项来提供的。

--- a/docs/src/guide/advanced/magic-form.md
+++ b/docs/src/guide/advanced/magic-form.md
@ -40,6 +40,8 @@ app.use(MagicForm);
 app.mount("#app");
 ```

+以上代码便完成了 @tmagic/form 的引入。需要注意的是，ElementUI 的样式文件需要单独引入。
+
 在 App.Vue 中写入以下内容：

 ```html
@ -104,8 +106,6 @@ app.mount("#app");
 </script>
 ```

-以上代码便完成了 @tmagic/form 的引入。需要注意的是，ElementUI 的样式文件需要单独引入。
-
 ### 开始使用

 至此，一个基于 Vue 和 @tmagic/form 的开发环境已经搭建完毕，现在就可以编写代码了。
--- a/docs/src/guide/advanced/page.md
+++ b/docs/src/guide/advanced/page.md
@ -25,7 +25,7 @@ export default {
 ```

 ## 组件渲染
-所有tmagic-editor组件，都通过一个tmagic-editor基础组件来渲染，这个基础组件会识别，当前渲染的组件是个普通组件，或者是容器组件，如果是普通组件（包括ui中提供的基础组件和业务开发的业务组件），则直接渲染；如果是个容器，则回到上一步的容器渲染逻辑中。
+所有tmagic-editor组件，都通过一个tmagic-editor基础组件来渲染。这个基础组件会识别当前渲染组件的类型。如果当前渲染组件是普通组件（包括ui中提供的基础组件和业务开发的业务组件），则直接渲染；如果当前渲染组件是容器，则回到[容器渲染](#容器渲染)逻辑中。

 基础组件的具体形式为：
 ```vue
--- a/docs/src/guide/conception.md
+++ b/docs/src/guide/conception.md
@ -16,6 +16,23 @@
 - 拓展描述，这部分内容目前还未有严格定义，但是我们保留这个扩展能力。
 - 组件 `type`, 是组件的类型，这是用来告诉编辑器，我们要渲染的是什么组件。每个组件在开发时就应该确定这样一个唯一、不和其他组件冲突的组件 `type`。

+```
+[
+  {
+    text: '文本',
+    type: 'text', ⬅️
+  },
+  {
+    text: '按钮',
+    type: 'button', ⬅️
+  },
+  {
+    text: '测试',
+    type: 'test', ⬅️
+  },
+]
+```
+
 ### 插件
 插件和组件类似，但是插件的功能是作为页面逻辑行为的一种补充方式。一般不显式的在模拟器中被渲染出具体内容（除非插件中会生成组件并插入页面），通常我们会用插件实现类似登录，页面环境判断，请求拦截器等等功能。

--- a/docs/src/guide/installation.md
+++ b/docs/src/guide/installation.md
@ -17,7 +17,7 @@ node.js > 14
 $ npm install @tmagic/editor@latest -S
 ```

-editor 中组件自定义属性配置由[@tmagic/form](advanced/magic-form.html)提供，需要添加@tmagic/form 依赖；editor 与 form 中使用到的 UI 组件都由 [element-plus](https://element-plus.org/)提供，需要添加 element-plus 依赖。
+editor 中组件自定义属性配置由[@tmagic/form](./advanced/magic-form.md)提供，需要添加@tmagic/form 依赖；editor 与 form 中使用到的 UI 组件都由 [element-plus](https://element-plus.org/)提供，需要添加 element-plus 依赖。

 ```bash
 $ npm install @tmagic/form@latest element-plus -S
@ -127,7 +127,7 @@ app.mount("#app");
 </style>
 ```

-关于 [@tmagic/editor](https://www.npmjs.com/package/@tmagic/editor) 组件，更多的属性配置详情请参考[编辑器 API](../api/editor.md)。
+关于 [@tmagic/editor](https://www.npmjs.com/package/@tmagic/editor) 组件，更多的属性配置详情请参考[编辑器 API](../api/editor/editor.md)。

 其中，**有四个需要注意的属性配置项**：`runtimeUrl` `values` `configs` `componentGroupList`。这是能让我们的编辑器正常运行的关键。

@ -141,7 +141,7 @@ app.mount("#app");

 ### componentGroupList

-`componentGroupList` 是指定左侧组件库内容的配置。此处定义了在编辑器组件库中有什么组件。在添加的时候通过组件 `type` 来确定 runtime 中要渲染什么组件。可以参考 [componentGroupList 配置](../api/editor.html#componentgrouplist)。
+`componentGroupList` 是指定左侧组件库内容的配置。此处定义了在编辑器组件库中有什么组件。在添加的时候通过组件 `type` 来确定 runtime 中要渲染什么组件。可以参考 [componentGroupList 配置](../api/editor/editor.html#componentgrouplist)。

 ### propsConfigs/propsValues

--- a/docs/src/page/advanced.md
+++ b/docs/src/page/advanced.md
@ -127,7 +127,7 @@ tmagic-editor的[打包脚本](../page/introduction.html#打包脚本)会根据

 <img src="https://image.video.qpic.cn/oa_88b7d-32_1233288257_1633783105283986" width="40%" alt="版本选择">

-版本管理具体如何实现取决于使用tmagic-editor的业务方相关，拥有版本管理能力，具有如下优点：
+版本管理具体如何实现，这取决于使用tmagic-editor的业务方。版本管理具有如下优点：
 1. 对于已经配置好发布的项目，使用固定版本，不会被新版本的特性影响，保证项目线上稳定运行
 2. 发布的新版本如果出现问题，可以及时回退选择使用旧版本

--- a/magic-admin/README.md
+++ b/magic-admin/README.md
@ -1,6 +1,6 @@
 # 介绍

-我们提供了与编辑器，表单配套的管理端供开发者直接使用。管理端（magic-admin）代码存放于[开源仓库](https://github.com/Tencent/tmagic-editor)"magic-admin"目录下，可作为一个独立项目运行。我们提供这个管理端一方面期望开发者可以更清晰的了解一个项目从编辑到生成的整个流程，另一方面，开发者也可以
+我们提供了与编辑器、表单等配套的管理端供开发者直接使用。管理端（magic-admin）代码存放于[开源仓库](https://github.com/Tencent/tmagic-editor)"magic-admin"目录下，可作为一个独立项目运行。我们提供这个管理端一方面期望开发者可以更清晰的了解一个项目从编辑到生成的整个流程，另一方面，开发者也可以
 在 magic-admin 的基础上快速搭建适合自己业务的管理平台。

 管理端提供了如下能力：