Document ESM UI providers (#613)

* Document ESM UI providers

* Update ESM UI provider documentation

Author: ruibaby

docs/developer-guide/plugin/api-changelog.md

@@ -3,6 +3,20 @@ title: API 变更日志
 description: 记录每一个版本的插件 API 变更记录，方便开发者适配
 ---
 
+## 2.26.0
+
+### UI 扩展支持 ESM 和异步分块
+
+从 Halo 2.26.0 开始，插件和已激活主题的 Console / UC UI 扩展可以使用 ESM 构建和加载，并支持异步 JavaScript、CSS 和其他静态资源分块。Halo 2.x 会继续兼容已有的 IIFE 产物，无需为兼容新版本而重新构建旧插件。
+
+将 `@halo-dev/ui-plugin-bundler-kit` 升级到 2.26.0 后，`viteConfig` 和 `rsbuildConfig` 默认根据 `plugin.yaml` 的 `spec.requires` 自动选择格式。简单的 `requires: ">=2.26.0"` 会选择 ESM；暂时无法迁移的项目可以显式设置 `format: "iife"`。默认 ESM preset 会为入口、启动样式和异步资源使用内容哈希文件名，`ui-plugin.json` 会记录实际启动资源路径；清单、入口、样式、分块和静态资源必须作为一个完整目录打包。详细文档请参考 [UI 构建](./basics/ui/build.md#output-format)。
+
+ESM 插件可以从 Halo 共享运行时导入 Vue、Vue Router、Pinia、Axios、FormKit 和公开的 Halo UI 包，其他依赖默认保留在插件自己的构建产物中。共享包的完整列表、兼容性诊断和自定义配置边界请参考 [共享运行时依赖](./basics/ui/build.md#shared-runtime-dependencies)。
+
+### 查询 UI provider 的注册状态
+
+`@halo-dev/ui-shared@2.26.0` 新增 `stores.uiPlugins()`，用于查询插件或已激活主题的 UI provider 是否被发现、是否已经成功注册以及当前状态。它替代了 `window.PluginName` 和 `window.enabledUiPlugins` 等依赖 IIFE 全局变量的检测方式。详细文档请参考 [共享工具库 > uiPlugins](./api-reference/ui/shared.md#uiplugins)。
+
 ## 2.25.0
 
 ### 表单定义 > `select` 选项支持图标和描述

docs/developer-guide/plugin/api-reference/ui/api-request.md

@@ -63,7 +63,9 @@ axiosInstance.get("/apis/foo.halo.run/v1alpha1/bar").then(response => {
 })
 ```
 
-此外，在最新的 `@halo-dev/ui-plugin-bundler-kit@2.17.0` 中，已经排除了 `@halo-dev/api-client`、`axios` 依赖，所以最终产物中的相关依赖会自动使用 Halo 本身提供的依赖，无需关心最终产物大小。
+`@halo-dev/ui-plugin-bundler-kit` 会让插件复用 Halo 提供的 `@halo-dev/api-client` 和 `axios`。旧版 IIFE 通过兼容全局对象提供这些依赖，Halo 2.26.0 开始支持的 ESM 则通过共享运行时模块提供，插件代码都应继续使用标准的包导入。
+
+直接从 `axios` 导入的是共享的标准 Axios 模块，不包含 Halo 的认证配置。请勿修改它的全局 defaults 或 interceptors；需要独立配置时使用 `axios.create()`。`@halo-dev/api-client` 导出的 `axiosInstance` 是另一个带有 Halo 认证和统一错误处理的实例，也不应修改它的 defaults 或 interceptors。
 
 :::info[提醒]
 如果插件中使用了 `@halo-dev/api-client@2.17.0` 和 `@halo-dev/ui-plugin-bundler-kit@2.17.0`，需要提升 `plugin.yaml` 中的 `spec.requires` 版本为 `>=2.17.0`。

docs/developer-guide/plugin/api-reference/ui/shared.md

@@ -15,6 +15,53 @@ description: 介绍 @halo-dev/ui-shared 包中的共享工具库
 pnpm install pinia
 ```
 
+### uiPlugins
+
+从 Halo 2.26.0 开始，可以通过 `stores.uiPlugins()` 查询当前页面发现的插件和已激活主题的 UI provider 状态。使用此 API 时，需要将 `@halo-dev/ui-shared` 和 `@halo-dev/ui-plugin-bundler-kit` 升级到 2.26.0 或更高版本，并将插件的 `spec.requires` 设置为不低于 Halo 2.26.0。
+
+```ts
+import { stores } from "@halo-dev/ui-shared"
+import { computed } from "vue"
+
+const uiPlugins = stores.uiPlugins()
+
+// 是否在当前 provider 列表中
+uiPlugins.isEnabled("plugin-search")
+
+// 当前页面中是否已经成功注册
+const searchRegistered = computed(() =>
+  uiPlugins.isRegistered("plugin-search")
+)
+
+// 读取 Halo 提供的只读状态
+uiPlugins.get("plugin-search")
+```
+
+主题 provider 使用 `theme:{metadata.name}` 作为名称，例如 `theme:theme-earth`。
+
+#### 属性
+
+- `registrations`：只读的 provider 注册记录列表。
+
+每条记录包含：
+
+```ts
+interface UiPluginRegistration {
+  name: string
+  type: "plugin" | "theme"
+  version: string
+  status: "pending" | "registered" | "failed"
+}
+```
+
+#### 方法
+
+- `get(name)`：返回指定 provider 的只读注册记录，不存在时返回 `undefined`。
+- `isEnabled(name)`：是否在当前页面的 provider 描述中被发现，不代表其 UI 已经注册成功。
+- `isRegistered(name)`：当前页面中是否已经成功完成 UI 注册。
+
+该 store 由 Halo 管理，插件不应尝试修改注册记录，也不应依赖 provider 的加载或注册顺序。需要检测其他插件是否启用时，应使用 `isEnabled` 代替 `window.PluginName` 或 `window.enabledUiPlugins`；不支持通过该 store 获取、调用或导入其他 provider 的 `PluginModule`。
+
 ### currentUser
 
 用于获取当前登录用户的信息，示例：

docs/developer-guide/plugin/basics/devtools.md

@@ -198,6 +198,7 @@ haloPlugin {
       // exclude '**/.idea/**'
       // exclude '**/.git/**'
       // exclude '**/.gradle/**'
+      // exclude 'src/main/resources/ui/**'
       // exclude 'src/main/resources/console/**'
       // exclude 'build/**'
       // exclude 'gradle/**'

docs/developer-guide/plugin/basics/manifest.md

@@ -54,6 +54,8 @@ spec:
 如果你在 plugin.yaml 中配置了 `settingName` 但确没有对应的 `Setting` 自定义模型资源文件，会导致插件无法启动，原因是 `Setting` 模型 `metadata.name` 为你配置的 `settingName` 的资源无法找到。
 :::
 
+从 `@halo-dev/ui-plugin-bundler-kit@2.26.0` 开始，`spec.requires` 也用于自动选择 UI 构建格式。支持的推导写法和回退行为请参考 [UI 构建 > 输出格式与 Halo 目标](./ui/build.md#output-format)。
+
 ## 插件运行模式
 
 Halo 插件可以在两种模式下运行：`deployment`（默认）模式和 `development` 开发模式。

docs/developer-guide/plugin/basics/structure.md

@@ -30,9 +30,6 @@ description: 了解插件项目的文件结构
 │       │           └── starter
 │       │               └── StarterPlugin.java
 │       └── resources
-│           ├── console
-│           │   ├── main.js
-│           │   └── style.css
 │           └── plugin.yaml
 ├── LICENSE
 ├── README.md
@@ -51,10 +48,10 @@ description: 了解插件项目的文件结构
 
 - `StarterPlugin.java`：插件后端的入口文件，位于 `src/main/java/com/example/starter` 路径下。你可以根据需要修改包名和类名，但需要确保该类继承 `run.halo.app.plugin.BasePlugin`，以指定其为插件的入口。
 - `plugin.yaml`：这是插件的描述文件，位于 `src/main/resources` 目录下。该文件是必须的，包含插件的基本信息，如插件名称、版本、作者、描述以及依赖等内容。
-- `resources/console`：该文件夹通常包含前端部分打包后生成的文件，包括 main.js（JavaScript 文件）和 style.css（样式表）。如果插件不包含前端部分，此目录可以忽略。
+- `resources/ui`：插件 JAR 中的推荐 UI 资源目录。Gradle 会将 `ui/build/dist` 的完整构建产物复制到 `build/resources/main/ui` 后打包，其中可能包含 `ui-plugin.json`、入口、样式、异步分块和其他静态资源。如果插件不包含 UI 部分，此目录可以忽略。
 
 :::warning[注意]
-从 2.11 开始，Halo 支持了 UC 个人中心，且个人中心和 Console 的插件机制共享，所以为了避免歧义，`resources/console` 在后续版本会被重命名为 `resources/ui`，但同时也会兼容 `resources/console`。
+从 2.11 开始，Halo 支持了 UC 个人中心，且个人中心和 Console 的插件机制共享，因此推荐使用 `resources/ui`。Halo 2.x 仍兼容旧项目使用的 `resources/console`，并优先读取 `ui`。
 :::
 
 ### 前端部分