From 9ee36c1291f86fb32cbf38b25dc7edb234b3751d Mon Sep 17 00:00:00 2001 From: chilingling <26962197+chilingling@users.noreply.github.com> Date: Fri, 20 Jun 2025 16:48:54 +0800 Subject: [PATCH] docs: update version docs (#1470) --- docs/README.md | 2 +- docs/api/frontend-api/globalService-api.md | 2 +- docs/api/frontend-api/preview-api.md | 59 +++++++++++++++++++ docs/catalog.json | 2 +- docs/changelog/changelog.md | 6 +- ...upgrade-guide.md => v2.7-upgrade-guide.md} | 24 ++++---- .../new-registry.md | 4 +- .../registry.md | 8 ++- 8 files changed, 85 insertions(+), 22 deletions(-) rename docs/changelog/{v2.6-upgrade-guide.md => v2.7-upgrade-guide.md} (93%) diff --git a/docs/README.md b/docs/README.md index dd66df81..0a6c9a6f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -48,7 +48,7 @@ - [前后端启动联调(Java服务端)](./development-getting-started/debugging-of-java-backend.md) - 更新日志 - [更新日志](./changelog/changelog.md) - - [v2.6升级指南](./changelog/v2.6-upgrade-guide.md) + - [v2.7升级指南](./changelog/v2.7-upgrade-guide.md) - 解决方案 - [Java服务端部署](./solutions/server-deployment-solution-java.md) - [Node.js服务端部署](./solutions/server-deployment-solution.md) diff --git a/docs/api/frontend-api/globalService-api.md b/docs/api/frontend-api/globalService-api.md index 242258ae..1b6e1b56 100644 --- a/docs/api/frontend-api/globalService-api.md +++ b/docs/api/frontend-api/globalService-api.md @@ -17,7 +17,7 @@ 默认值：true -描述：defaultGlobalService 会读取 app 信息，根据 app 的信息配置网页的标题为：`${app.name}-TinyEditor设计器` +描述：defaultGlobalService 会读取 app 信息，根据 app 的信息配置网页的标题为：`${app.name} —— TinyEngine 前端可视化设计器` 如果需要自定义标题，可以设置为 false。然后通过 document.title 来设置标题 diff --git a/docs/api/frontend-api/preview-api.md b/docs/api/frontend-api/preview-api.md index 0040636c..2d1605c6 100644 --- a/docs/api/frontend-api/preview-api.md +++ b/docs/api/frontend-api/preview-api.md @@ -1,5 +1,64 @@ # 页面预览相关配置项 +## 在页面预览入口添加物料配置 + +> **⚠️ Breaking Change (v2.6)** +> 在 v2.6 版本中，我们对页面预览配置进行了破坏性调整，现在需要在物料入口 `preview.js` 中直接配置物料信息，不再通过 URL 参数传递物料相关的 script 和 css 资源。 + +### 基本配置 + +在 `preview.js` 文件中，需要在注册表的 `engine.config` 配置中添加 `material` 属性： + +```javascript +import { initPreview, META_SERVICE, HttpService } from '@opentiny/tiny-engine' + +// 其他配置... + +const registry = { + [META_SERVICE.Http]: HttpService, + 'engine.config': { + id: 'engine.config', + theme: 'light', + // 新增：物料配置 + material: ['/mock/bundle.json'] + } +} + +initPreview({ + registry +}) +``` + +### 配置说明 + +- `material`：物料包配置数组，支持配置多个物料包 +- 每个物料包可以是一个 JSON 文件路径，包含物料的元数据、组件定义、样式等信息 +- 物料包的资源（script、css）会根据配置自动加载，无需在 URL 中传递 + +### 多物料包配置示例 + +```javascript +const registry = { + [META_SERVICE.Http]: HttpService, + 'engine.config': { + id: 'engine.config', + theme: 'light', + // 配置多个物料包 + material: [ + '/mock/bundle.json', // 基础物料包 + '/custom/business-bundle.json', // 业务物料包 + '/third-party/ui-bundle.json' // 第三方物料包 + ] + } +} +``` + +### 迁移指南 + +如果您从 v2.5 或更早版本升级到 v2.6，请按以下步骤进行迁移： + +1. 在 `preview.js` 的 `engine.config` 中添加 `material` 配置 +2. 确保物料包 JSON 文件路径正确且可访问 ## 配置预览页面的跳转 url diff --git a/docs/catalog.json b/docs/catalog.json index db74af24..3066d291 100644 --- a/docs/catalog.json +++ b/docs/catalog.json @@ -87,7 +87,7 @@ "name": "changelog", "articles": [ { "title": "更新日志", "name": "changelog.md" }, - { "title": "v2.6升级指南", "name": "v2.6-upgrade-guide.md" } + { "title": "v2.7升级指南", "name": "v2.7-upgrade-guide.md" } ] }, { diff --git a/docs/changelog/changelog.md b/docs/changelog/changelog.md index b11faeeb..4adeda5e 100644 --- a/docs/changelog/changelog.md +++ b/docs/changelog/changelog.md @@ -1,10 +1,10 @@ # 更新日志 -## v2.6 +## v2.7 ### 升级指南 -[v2.6 升级指南](./v2.6-upgrade-guide.md) +[v2.7 升级指南](./v2.7-upgrade-guide.md) ### What's Change @@ -22,7 +22,7 @@ #### 📚 Documentation -- 新增 [v2.6 升级指南](./v2.6-upgrade-guide.md) +- 新增 [v2.7 升级指南](./v2.7-upgrade-guide.md) - 新增 [新注册表](../extension-capabilities-overview/new-registry.md) 文档 - 新增 [注册表高级配置](../extension-capabilities-overview/new-registry-advanced.md) 文档 diff --git a/docs/changelog/v2.6-upgrade-guide.md b/docs/changelog/v2.7-upgrade-guide.md similarity index 93% rename from docs/changelog/v2.6-upgrade-guide.md rename to docs/changelog/v2.7-upgrade-guide.md index c373eb9b..5e6865e9 100644 --- a/docs/changelog/v2.6-upgrade-guide.md +++ b/docs/changelog/v2.7-upgrade-guide.md @@ -1,14 +1,14 @@ -# v2.6 升级指南 +# v2.7 升级指南 -> 本文档为 v2.6 版本的升级指南，主要介绍了 v2.6 版本的主要新特性、升级步骤和注意事项。 +> 本文档为 v2.7 版本的升级指南，主要介绍了 v2.7 版本的主要新特性、升级步骤和注意事项。 > -> 升级前请先阅读 [v2.6 更新日志](./changelog.md)，了解 v2.6 版本的变更内容。 +> 升级前请先阅读 [v2.7 更新日志](./changelog.md)，了解 v2.7 版本的变更内容。 ## 主要变更内容 ### 1. 注册表声明方式变更 -v2.6 版本对注册表的声明方式进行了重大调整，采用了基于唯一 ID 的新注册方式，使配置更加灵活和精确。 +v2.7 版本对注册表的声明方式进行了重大调整，采用了基于唯一 ID 的新注册方式，使配置更加灵活和精确。 #### 旧版注册表方式 @@ -74,7 +74,7 @@ const register = { 3. 移除不需要的插件时，将其值设置为 `false` 4. 添加新插件时，确保使用与官方插件不同的唯一 ID -> **重要提示⚠️**：v2.6 开始，如果对原插件没有改动（配置、替换、删除），则不需要在注册表中进行声明，因为官方内置了全量的注册表。 +> **重要提示⚠️**：v2.7 开始，如果对原插件没有改动（配置、替换、删除），则不需要在注册表中进行声明，因为官方内置了全量的注册表。 详细内容请参考 [新注册表](../extension-capabilities-overview/new-registry.md)。 @@ -82,7 +82,7 @@ const register = { ### @opentiny/tiny-engine-meta-register 包 API 变化 -v2.6 版本对 `@opentiny/tiny-engine-meta-register` 包的 API 进行了重大重构，以下是主要变化： +v2.7 版本对 `@opentiny/tiny-engine-meta-register` 包的 API 进行了重大重构，以下是主要变化： #### 移除的 API @@ -190,7 +190,7 @@ await initHotfixRegistry({ ### registryPath 配置 -**重要说明⚠️**：v2.6 版本开始，为了使注册表的 tree-shaking 功能正常工作，您需要在 `vite.config.js` 中配置 `registryPath` 参数。 +**重要说明⚠️**：v2.7 版本开始，为了使注册表的 tree-shaking 功能正常工作，您需要在 `vite.config.js` 中配置 `registryPath` 参数。 ```javascript // vite.config.js @@ -217,7 +217,7 @@ export default defineConfig((configEnv) => { ### 2. 布局（layout）变更 -v2.6 版本对布局配置进行了优化，使布局更加灵活可配置。 +v2.7 版本对布局配置进行了优化，使布局更加灵活可配置。 #### 布局配置变更 @@ -272,7 +272,7 @@ export default { #### 3.1 插件 `align` 配置的废弃 -在 v2.6 版本中，插件的 `align` 配置属性已被废弃，不再作为定位插件位置的方式。新版本中应使用 `layoutConfig` 或 `relativeLayoutConfig` 来定位插件。 +在 v2.7 版本中，插件的 `align` 配置属性已被废弃，不再作为定位插件位置的方式。新版本中应使用 `layoutConfig` 或 `relativeLayoutConfig` 来定位插件。 旧版写法： ```javascript @@ -317,7 +317,7 @@ const register = { #### 3.2 插件 `type: setting` 配置的废弃 -在 v2.6 版本中，右侧设置面板插件不再使用 `type: 'setting'` 来标识，而是统一使用插件 ID 来区分。 +在 v2.7 版本中，右侧设置面板插件不再使用 `type: 'setting'` 来标识，而是统一使用插件 ID 来区分。 旧版写法： ```javascript @@ -363,7 +363,7 @@ const register = { ### 4. 注册表热修复功能 -v2.6 版本新增了注册表热修复（hotfix）功能，可以通过覆盖官方插件的特定函数或模板，实现紧急 bug 修复，而不需要等待官方版本发布。 +v2.7 版本新增了注册表热修复（hotfix）功能，可以通过覆盖官方插件的特定函数或模板，实现紧急 bug 修复，而不需要等待官方版本发布。 ```javascript // hotfix 注册表示例 @@ -390,7 +390,7 @@ export default { ## 其他改进 -- **默认注册表内置**：v2.6 版本内置了全量的默认注册表，如果对原插件没有改动（配置、替换、删除），则不需要在注册表中进行声明。 +- **默认注册表内置**：v2.7 版本内置了全量的默认注册表，如果对原插件没有改动（配置、替换、删除），则不需要在注册表中进行声明。 ## 升级步骤建议 diff --git a/docs/extension-capabilities-overview/new-registry.md b/docs/extension-capabilities-overview/new-registry.md index ae13b3b8..e75ca723 100644 --- a/docs/extension-capabilities-overview/new-registry.md +++ b/docs/extension-capabilities-overview/new-registry.md @@ -1,6 +1,6 @@ # 注册表（新） -⚠️注意：该文档仅适用于 TinyEngine v2.6+ 版本，如果需要了解旧的注册表配置方式，请参考 [旧注册表](./registry.md)。 +⚠️注意：该文档仅适用于 TinyEngine v2.7+ 版本，如果需要了解旧的注册表配置方式，请参考 [旧注册表](./registry.md)。 ## 什么是注册表 @@ -56,7 +56,7 @@ const register = { 通过这种基于ID的注册方式，可以更精细地控制平台的各个部分，实现添加、替换或移除特定功能，而不需要重新配置整个注册表结构。 -注意⚠️：v2.6 开始，如果对原插件没有改动（配置、替换、删除），则不需要在注册表中进行声明，因为官方内置了全量的注册表： +注意⚠️：v2.7 开始，如果对原插件没有改动（配置、替换、删除），则不需要在注册表中进行声明，因为官方内置了全量的注册表： 官方默认的全局注册表，请参考 [默认注册表](https://github.com/opentiny/tiny-engine/blob/develop/packages/design-core/registry.js)。 diff --git a/docs/extension-capabilities-overview/registry.md b/docs/extension-capabilities-overview/registry.md index 1d5165a7..10d91fdb 100644 --- a/docs/extension-capabilities-overview/registry.md +++ b/docs/extension-capabilities-overview/registry.md @@ -1,6 +1,6 @@ # 注册表 -⚠️注意：TinyEngine v2.6 版本之后，注册表的方式有所变化，请参考 [新注册表](./new-registry.md) 了解新的注册表配置方式。 +⚠️注意：TinyEngine v2.7 版本之后，注册表的方式有所变化，请参考 [新注册表](./new-registry.md) 了解新的注册表配置方式。 ## 什么是注册表 @@ -151,7 +151,11 @@ material 配置用于指定物料资源的来源，它接受一个数组，每 import bundle from './bundle.json' // engine.config.js 示例 export default { - // ... + // 可以传入 url 路径 + material: ['/mock/bundle.json'], + // 也可以传入 JSON 对象 + material: [bundle], + // 也可以传入多个物料源 material: ['/mock/bundle.json', bundle], // ... }