@zl-ui-kit/components 0.3.3 → 0.5.0

package/README.md

@@ -15,7 +15,7 @@ ZL UI 业务组件库 —— Element Plus 体系，`Zl` 前缀，47 个业务组
 | 包 | 职责 |
 | --- | --- |
 | [`@zl-ui-kit/components`](https://www.npmjs.com/package/@zl-ui-kit/components) | EP 化业务组件库（`Zl` 前缀，47 个组件） |
-| [`@zl-ui-kit/composables`](https://www.npmjs.com/package/@zl-ui-kit/composables) | `useRequest` 请求体系、`useDict`、微前端通信层 |
+| [`@zl-ui-kit/composables`](https://www.npmjs.com/package/@zl-ui-kit/composables) | `useRequest` 请求体系、`useDict`、`useGlobalData` 全局数据、国际化 |
 | [`@zl-ui-kit/icons`](https://www.npmjs.com/package/@zl-ui-kit/icons) | 444 个离线 SVG 图标（prefix `zl`，开源图标库） |
 | [`@zl-ui-kit/theme`](https://www.npmjs.com/package/@zl-ui-kit/theme) | 5 套主题 + `defineTheme` 运行时定制（内置 OFL 开源中文字体） |
 | [`@zl-ui-kit/utils`](https://www.npmjs.com/package/@zl-ui-kit/utils) | TS 工具函数库 + Axios 请求封装 |
@@ -56,6 +56,14 @@ import { ZlFilePreview, ZlFileViewer } from '@zl-ui-kit/components/file-preview'
 > 例外：`ZlPdfViewer` 没有重型依赖，仍留在主入口，`import { ZlPdfViewer } from '@zl-ui-kit/components'`。
 > `app.use(ZlUI)` 全量注册**不含**上述子入口组件，需要的话手动 `app.component('ZlChart', ZlChart)`。
 
+**关于 `echarts` 版本**（`peerDependencies: "^5.6.0 || ^6.0.0"`，5.6+ 与 6.x 均支持）：
+
+- `ZlChart` 内部是 `import * as echarts from 'echarts'`（全量包，开箱即用、无需自己 `use()` 注册图表类型）；
+  若宿主用 `echarts/core` + 按需注册，两者是两份独立实例，产物会同时含两份 echarts（实测约 +600KB）。
+  此时可按需改用宿主实例自绘，或在构建里把 `echarts` 设为 external 由宿主提供。
+- 升级到 **echarts 6** 后默认主题变了（配色、legend 默认挪到画布底部、轴标签防溢出默认开启），
+  想保持 v5 观感：`import 'echarts/theme/v5'` + `<ZlChart theme="v5" ... />`（`theme` prop 见 §6 ⑧）。
+
 接入：
 
 ```ts
@@ -74,7 +82,7 @@ createApp(App).use(ElementPlus).use(ZlUI).mount('#app')
 ```ts
 // 1. 组件 —— Zl 前缀
 import { ZlTable, ZlEmpty } from '@zl-ui-kit/components'
-// 2. hooks —— useRequest / useDict / useLocale / usePageTabs / useZlT …
+// 2. hooks —— useRequest / useDict / useLocale / useGlobalData / useZlT …
 import { useRequest, useDict } from '@zl-ui-kit/composables'
 // 3. 工具函数 —— generateUUID / paginate / formatNumber …
 import { generateUUID, paginate } from '@zl-ui-kit/utils'
@@ -90,20 +98,22 @@ import '@zl-ui-kit/theme/themes.css'
 > npm i @zl-ui-kit/components @zl-ui-kit/composables @zl-ui-kit/utils
 > ```
 
-> **版本要求 `>=0.3.2`**
+> **版本要求 `>=0.4.0`**
 >
 > - `0.2.0`：tarball 里依赖仍是 `catalog:` 协议，安装报 `Unsupported URL Type "catalog:"`
 > - `0.3.0`：`exports` 指向不存在的 `dist/index.mjs`，装得上但 import 报 `ERR_MODULE_NOT_FOUND`
 > - `0.3.1`：把 micro-app 误设为**必需** peer，纯 Web 应用会被强行拉入 micro-app（约 2.4MB）
 >
-> 这三个版本均已 `deprecate`，请直接用 `0.3.2` 或更新版本。
+> 这三个版本均已 `deprecate`，请直接用 `0.4.0` 或更新版本。
 
-> **`@micro-zoe/micro-app` 是可选依赖（0.3.2 起）**
+> **`0.5.0` 起不再包含任何微前端依赖**
 >
-> 只在用微前端时才需要装：`npm i @micro-zoe/micro-app`。
-> 不装时 `useLocale` / 主题 / 字典等核心能力照常工作（globalData 降级为 localStorage：
-> `$zl_locale` / `$zl_theme` / `$zl_token`），但 `useMicroApp` / `useMicroAction` / `usePageTabs`
-> 这类微前端 hook 会在调用时抛出带指引的错误，而不是 `Cannot read properties of undefined`。
+> 微前端通信层（`useMicroApp` / `useMicroAction` / `usePageTabs` / `useMicroGlobalData`）与
+> `formatMicroUrl` 工具已全部移除，`@micro-zoe/micro-app` 不再是 peer 依赖 —— 安装本库不会
+> 再拉入这个约 2.4MB 的包，`@zl-ui-kit/composables` 的产物里也没有它的静态 import
+> （旧版在 Node 原生 ESM / SSR 下会因这条 import 报 `ERR_MODULE_NOT_FOUND`）。
+> 全局数据（`locale` / `theme` / `token` / 用户 / 权限 / `config`）改用 `useGlobalData()`，
+> 纯 `localStorage` 持久化；`useLocale`、主题、字典等能力的用法与行为不变。
 
 > **两个「看起来像错、其实正常」的现象**
 >
@@ -188,7 +198,7 @@ setTheme('dark')               // 切换主题（light/dark/red-light/red-dark/b
 ### 3.5 文件与编辑
 `ZlFilePreview` · `ZlFileViewer` · `ZlPdfViewer` · `ZlEditor` · `ZlSqlEditor` · `ZlLogin`
 
-> 微前端页签类组件（`ZlMicroPage`/`ZlAppTabs`/`ZlPageTabs`/`ZlDevMenu`）已从组件库移除，相关 composables 保留并标注运行前提。
+> 页签/微前端类组件（`ZlMicroPage`/`ZlAppTabs`/`ZlPageTabs`/`ZlDevMenu`）与配套 composables（`usePageTabs` 等）均已移除，`0.5.0` 起组件库不含任何微前端能力。
 
 ### 3.6 国际化基础设施（独立于 47 个业务组件）
 `ZlI18nProvider` —— 国际化根容器，将 Element Plus 语言包经 `<el-config-provider>` 挂载到 Element Plus（详见第 13 章）。
@@ -249,7 +259,7 @@ setTheme('dark')               // 切换主题（light/dark/red-light/red-dark/b
 ```
 
 ### ZlDictTag — 字典标签
-经 `useDict(dictKey)` 解析独立字典 store（`useDictStore`，Vue3 状态管理缓存，不依赖微前端）。**支持三种数据注入方式**（详见第 12.1.4 节与第 6.3 节 ⑤）：
+经 `useDict(dictKey)` 解析独立字典 store（`useDictStore`，Vue3 状态管理缓存，不依赖全局数据）。**支持三种数据注入方式**（详见第 12.1.3 节与第 6.3 节 ⑤）：
 
 ```vue
 <!-- 1. 组件级直传（最轻量，无需任何全局配置即可翻译） -->
@@ -374,7 +384,7 @@ function onSearch(params) { req.run({ pageNum: 1, pageSize: 6, ...params }) }
 
 #### ⑤ `ZlDictTag` —— 注入字典后由 `useDict` 解析
 
-字典模块**不依赖任何微前端逻辑**：数据由调用方注入或经 `setDictSource` 注册的加载器获取，缓存在独立的全局字典 store（`useDictStore`，基于 Vue3 `createGlobalState` 单例）中，跨组件共享并复用，避免重复加载。
+字典模块**不依赖全局数据**：数据由调用方注入或经 `setDictSource` 注册的加载器获取，缓存在独立的全局字典 store（`useDictStore`，基于 Vue3 `createGlobalState` 单例）中，跨组件共享并复用，避免重复加载。
 
 `useDict` 的数据解析优先级（从高到低）：**组件级直传 → 局部注入 source → 全局 source**。任一来源命中即写入缓存 `dictStore[key]` 统一解析；同一 key 仅在缓存未命中且未在加载时触发一次加载（结果缓存）。
 
@@ -445,6 +455,13 @@ const chartOption = computed(() => {
 <ZlChart v-bind="chartOption" />
 ```
 
+| Prop | 类型 | 说明 |
+| --- | --- | --- |
+| `series` | `object \| object[]` | 系列（单个或数组）；其余 option 字段经 attrs 透传 |
+| `theme` | `string` | 主题名，initialize 时指定。需先注册，如 `import 'echarts/theme/v5'` 后传 `theme="v5"`；echarts 6 想保留 v5 观感时用 |
+
+> 暴露方法：`clear()`（模板 ref 调用）。尺寸自适应由 `useResizeObserver` 负责，容器需有明确高度。
+
 #### ⑨ `useRequest` 生命周期面板
 ```ts
 const req = useRequest(getResourcePageMaybeFail, { defaultParams: [{ pageNum: 1, pageSize: 5 }] })
@@ -541,6 +558,55 @@ const items: FormItem[] = [
 - `ZlEditor` / `ZlSqlEditor`(+`useSqlCompletion`)：富文本 / SQL 编辑器。
 - `ZlLogin`(+`LoginForm`+`SlideChecker`)：登录框，背景改半透明 + `backdrop-filter`。
 
+### 9.1 `ZlEditor`：monaco worker 配置与首屏治理
+
+`ZlEditor` 内部 `import * as monaco from 'monaco-editor'`（**全量**，含各语言 contribution），
+是除 echarts 之外最重的一块依赖：`monaco-editor@0.41` 安装体积约 **83.8MB**，
+min 后的编辑器内核约 **3.3MB**，其中 worker 单独成文件（`tsWorker` 4.4MB、`jsonWorker` 0.12MB）。
+
+**worker 是干什么的**：monaco 把「语法校验、智能补全、格式化、TS 类型检查」这些 CPU 密集活儿
+丢进 Web Worker，避免打字时主线程卡顿。**不配 worker 不会白屏**——编辑器照常输入，
+但没有语言服务，控制台会打一条告警：
+
+```
+[ZlEditor] monaco worker 未配置：语言服务（TS/JSON/CSS 补全校验）不可用。
+```
+
+**为什么库不打包 worker**：vite lib 模式无法把 `?worker` 产物正确外链进库，打进库只会得到
+一个指向不存在文件的 URL。所以由宿主注入 —— 用 `setupMonacoEnvironment(getWorker)`：
+
+```ts
+// 放在「延迟加载编辑器的那个模块」里，不要放 main.ts 顶部
+import { setupMonacoEnvironment } from '@zl-ui-kit/components/editor'
+import EditorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker'
+import JsonWorker from 'monaco-editor/esm/vs/language/json/json.worker?worker'
+import TsWorker from 'monaco-editor/esm/vs/language/typescript/ts.worker?worker'
+
+setupMonacoEnvironment((_, label) => {
+  if (label === 'json') return new JsonWorker()
+  if (label === 'typescript' || label === 'javascript') return new TsWorker()
+  return new EditorWorker() // 其他语言（含 SQL 的着色）走基础 worker
+})
+```
+
+> `getWorker` 必须是**同步**返回 `Worker`，所以 worker 要用上面的 `?worker` 静态导入（Vite 会
+> 输出独立文件），不能在函数里 `await import()`。
+
+**让编辑器不进首屏**（体积 3MB+，务必异步）：
+
+```ts
+const ZlEditor = defineAsyncComponent(() =>
+  import('@zl-ui-kit/components/editor').then(m => m.ZlEditor),
+)
+```
+
+路由级拆分（`() => import('./EditorPage.vue')`）效果相同 —— 只要 `@zl-ui-kit/components/editor`
+这条导入不在首屏的静态依赖图里，monaco 就一定在异步 chunk 中；worker 文件只会在
+`new Worker()` 时被请求。
+
+**只用 SQL 编辑器**时：SQL 补全由 `useSqlCompletion` + `dt-sql-parser`（纯 JS）提供，
+着色走 monaco 的 Monarch，所以只配 `editor.worker` 就够，可以不引 `tsWorker`。
+
 ---
 
 ## 10. 主题定制（@zl-ui-kit/theme）
@@ -617,7 +683,7 @@ const { theme, themes, setTheme } = useTheme()   // 组件内响应式
 ### 12.1 `@zl-ui-kit/composables` —— 公共 Hooks
 
 ```ts
-import { useRequest, useMicroGlobalData, useDict /* … */ } from '@zl-ui-kit/composables'
+import { useRequest, useGlobalData, useDict /* … */ } from '@zl-ui-kit/composables'
 ```
 
 #### 12.1.1 请求体系 `useRequest`（插件与全局配置）
@@ -646,55 +712,37 @@ const logPlugin = defineUseRequestPlugin((inst) => ({
 const { data } = useRequest(getList, {}, [logPlugin])
 ```
 
-#### 12.1.2 微前端通信（基于 `@micro-zoe/micro-app`）
-
-> 运行前提：微前端相关 hook 需要 `@micro-zoe/micro-app`（**0.3.2 起为可选依赖**，`npm i @micro-zoe/micro-app`）。
-> 缺失时这些 hook 会抛出带安装指引的错误。
->
-> `useMicroGlobalData` 是例外：它在检测不到 micro-app 时**自动降级**为本地存储模式
-> （`$zl_locale` / `$zl_theme` / `$zl_token`），因此 `useLocale`、主题、字典在纯 Web 应用中照常可用。
-> `enableGlobalDataMock(true)` 仍然保留，用于开发态强制走 mock 数据。
-
-| Hook / 函数 | 返回 / 签名 | 说明 |
-| --- | --- | --- |
-| `useMicroApp()` | `{ apps, isMicroBase(), isMicroChild(), updateApps(), startMicroApp(config?) }` | 微应用身份判断、启动、活跃应用列表（全局单例） |
-| `useMicroAction(action, appName?)` | `(...args) => void` | 向子应用（或指定 app，缺省广播全部）派发动作事件（前缀 `action__`） |
-| `useMicroActionAsync(action, appName?)` | `(...args) => Promise` | 派发并等待 Promise 化结果（主/子应用语义不同） |
-| `useMicroListener()`（共享单例） | `{ on, off, once }` | 监听动作事件 |
-| `useMicroResultListener(action, callback)` | `void` | 监听动作执行结果 |
-| `dispatchMicroAction(action, appName, ...data)` | `Promise<void>` | 向指定子应用派发动作（回调式） |
-
-#### 12.1.3 全局数据 `useMicroGlobalData`
+#### 12.1.2 全局数据 `useGlobalData`
 
 ```ts
-const g = useMicroGlobalData()
+import { useGlobalData } from '@zl-ui-kit/composables'
+const g = useGlobalData()
 ```
-响应式字段（均为 `WritableComputedRef`）：`locale` / `theme` / `token` / `isI18nKeyVisible` / `roles` / `permissions` / `user` / `localeMessages` / `elLocaleMessages` / `config`。（注：字典数据已独立为 `useDictStore`，不再挂在全局数据上。）
+响应式字段（均为 `WritableComputedRef`）：`locale` / `theme` / `token` / `isI18nKeyVisible` / `roles` / `permissions` / `user` / `localeMessages` / `elLocaleMessages` / `config`。（注：字典数据已独立为 `useDictStore`，不挂在全局数据上。）
 
 方法：`getConfig(key, default?)` / `isConfig(key, compareValue='true')` / `setAndWaitUntil({ set?, until? })`（设置并等待条件成立）/ `resetUser()`。
-存储键：`$zl_locale` / `$zl_theme` / `$zl_token`（经 `useStorage` 持久化，`theme` 缺省 `light`）。
+持久化：`locale` / `theme` / `token` 经 `useStorage` 写入 `$zl_locale` / `$zl_theme` / `$zl_token`（`theme` 缺省 `light`），并同步到 `<body data-theme>` / `<body data-locale>`；其余字段（用户、权限、`config` 等）为内存态，由宿主自行写入。
 
 ```ts
-// 无 micro-app 环境会自动降级为本地存储模式，无需额外调用（0.3.2 起）
-import { useMicroGlobalData } from '@zl-ui-kit/composables'
-const g = useMicroGlobalData()   // locale/theme/token 等全局数据（与字典无关）
+// 应用入口：初始化登录态与业务配置
+const g = useGlobalData()
+g.token.value = loginToken                                  // 持久化到 $zl_token
+g.config.value = { 'zl.service.type': 'platform' }           // useServiceType 读取它
+g.user.value = { name: '张三' }
 
-// 如需强制使用 mock 数据（例如 playground 调试），仍可显式开启，须在首次调用前执行
-import { enableGlobalDataMock } from '@zl-ui-kit/composables'
-enableGlobalDataMock(true)
+g.locale.value = 'en'                                       // 切换语言，useLocale / ZlI18nProvider 跟随
+g.resetUser()                                               // 登出：清 user / roles / permissions / token
 ```
 
-`enableGlobalDataMock(enabled = true)`：显式开启开发态 mock。**不是**使用本 hook 的必要条件 ——
-检测不到 micro-app 时会自动降级，只有想强制 mock 时才需要调用。
-
-> 字典数据已独立：经 `setDictSource()` 注册（见 12.1.4），由 `useDictStore` 缓存，不再通过 `useMicroGlobalData().dictStore`。
+> 本 hook 只依赖 `localStorage`，**不依赖任何微前端框架**。它替代了 `0.4.x` 及更早版本的
+> `useMicroGlobalData`（已随微前端通信层一并移除），存储键保持一致，升级后已持久化的数据不会丢。
 
-#### 12.1.4 字典与国际化
+#### 12.1.3 字典与国际化
 
 - `useDictStore`（全局字典 store，基于 Vue3 `createGlobalState` 单例）：`dictStore`（缓存 `Record<key, DictItem[]>`）、`loadingKeys`、`setDictSource(source|null)`、`getDictSource()`、`ensureDict(key, localSource?)`。同一 key 仅在缓存未命中且未在加载时触发一次加载，结果缓存复用。
 - `useDict(key, options?)` → `ComputedRef<DictItem[]>`（附带 `.label: Record<value,label>`）：读 `useDictStore` 并解析。数据解析优先级：组件级 `options.data` → 局部 `useDictProvider({ source })` → 全局 `setDictSource(source)`。`DictItem = { label, value, icon?, type? }`（亦可用 `type DictItem` 导入）。
 - `setDictSource(source | null)`：全局注册字典数据源（应用入口调用一次）。`source` 为静态表 `Record<string, DictItem[]>` 或函数 `(key) => DictItem[] | Promise<DictItem[]>`；传 `null` 清空。`getDictSource()` 可读取当前值。
-- `useDictProvider(source)`：子树根提供局部字典数据源（覆盖全局，非微前端注入）。
+- `useDictProvider(source)`：子树根提供局部字典数据源（覆盖全局）。
 - `useLocale(options?, loader?)` → `{ i18n, locale, isI18nKeyVisible }`：创建与全局语言联动的 vue-i18n 实例；`loader(locale)` 按需返回 `{ localeMessages, elLocaleMessages }`（业务包 + Element Plus locale）。`elLocaleMessages` 写入全局数据后，**必须**由 `ZlI18nProvider` 经 `<el-config-provider>` 挂载到 Element Plus 才生效（分页 / 日期选择器等内置组件才本地化）。详见第 13 章。
 - `useZlT()` → `{ t }`：组件内部渐进式翻译的安全桥梁。`t(key, fallback?, params?)` 在宿主已 `app.use(i18n)` 时委托 vue-i18n 解析（`params` 用于 `{name}` 命名插值），未命中 key 或宿主未装 i18n 时降级为 `fallback`（缺省返回 key），**绝不抛错**，从而可在不破坏存量消费方的前提下逐步把硬编码中文替换为 `t('zl.xxx','中文兜底')`。语言包 key 规范：`zl.<组件>.<语义>`。
 - `mergeMessages(base, ...overrides)`：i18n 语言包深度合并，后者覆盖前者、未提供的 key 保留原值（按 `locale → key` 结构）。用于消费者「只覆盖部分文案」。
@@ -702,7 +750,7 @@ enableGlobalDataMock(true)
 - `zlMessages` / `zlZhMessages` / `zlEnMessages`（来自 `@zl-ui-kit/components`）：组件库内置语言包（zh / zh-cn / en），可被覆盖或整包替换。
 - `ZlI18nProvider`（新增，来自 `@zl-ui-kit/components`）：国际化根容器。用法 `<ZlI18nProvider><App/></ZlI18nProvider>`，在应用根包裹一次，把全局 `elLocaleMessages` 绑定到 Element Plus。
 
-#### 12.1.5 全局消息 `useGlobalMessage`
+#### 12.1.4 全局消息 `useGlobalMessage`
 
 ```ts
 const { Message, Modal, Notification } = useGlobalMessage()
@@ -715,14 +763,7 @@ const r = await Modal.confirmPromise({ title: '删除', message: '确认删除
 ```
 `throwOnOk` / `throwOnCancel` 控制错误是否向上抛出（默认吞错 resolve(false) / resolve('Cancel')）。
 
-#### 12.1.6 页签管理 `usePageTabs`
-
-```ts
-const { roots, activeRoot, pageTabs, current, addPageTab, removePageTab, removeCurrentTab, clearPageTab, setCurrentTab, createPageTabsRoot, setRootChild } = usePageTabs()
-```
-micro-app 多应用页签模型（root 树 → 扁平页签 → 当前激活页签）。另含 `micros`、`activeRootKey` 只读属性。
-
-#### 12.1.7 其它 Hooks
+#### 12.1.5 其它 Hooks
 
 - `createCacheComputed(getter)`：带缓存的 computed 工厂，同一对象结果缓存、作用域销毁自动清理；返回函数带 `.clear()`。
 - `useSash(refName, options?)` → `{ sashElRef }`：拖拽分隔条交互；`options` 含 `start / onMousedown / onMousemove({dx,dy,start}) / onMouseup / onDoubleClick`。
@@ -762,7 +803,7 @@ api.get('/resources', { params: { pageNum: 1, pageSize: 10 } })
 | `hasOwn(obj, key)` | `Object.prototype.hasOwnProperty` 封装 |
 | `isObject` / `isPlainObject` / `isArray` / `isFunction` / `isPromise` / `isBoolean` / `isNumber` / `isDefined` | 类型判断（TS 类型守卫） |
 
-#### 12.2.3 函数 / 加密 / DOM / 文件 / 微前端 URL / 杂项
+#### 12.2.3 函数 / 加密 / DOM / 文件 / 杂项
 
 **函数**
 - `debounce(fn, delay = 300)`：防抖。
@@ -784,9 +825,6 @@ api.get('/resources', { params: { pageNum: 1, pageSize: 10 } })
 - `fileUrlPreviewType(path)` → `'image' | 'pdf' | 'word' | 'ppt' | 'excel'`（按扩展名判断）。
 - `formatFilesize(size, { precision = 2, units })`：文件大小格式化（B/KB/MB/GB）。
 
-**微前端 URL**
-- `formatMicroUrl(url, { dev?, origins? })` → `{ micro, URL, url, fullpath }`：从路径首段提取微应用标识；`dev` 态可将微应用源映射为本机 dev server（如 `{ dsc: 'http://localhost:5204' }`）。
-
 **杂项**
 - `generateUUID()`：UUID v4。
 - `getRandomInt(min, max)`：`[min, max]` 区间随机整数。
@@ -816,15 +854,12 @@ api.get('/resources', { params: { pageNum: 1, pageSize: 10 } })
 
 ```ts
 import { createZlI18n } from '@zl-ui-kit/components'
-import { enableGlobalDataMock, useMicroGlobalData } from '@zl-ui-kit/composables'
+import { useGlobalData } from '@zl-ui-kit/composables'
 import en from 'element-plus/es/locale/lang/en'
 import zhCn from 'element-plus/es/locale/lang/zh-cn'
 
-// 开发态无 micro-app 时开启本地 mock（须在首次 useMicroGlobalData 前调用）
-enableGlobalDataMock(true)
-
 // 指定初始语言，避免 createI18n 取到非法 locale
-const { locale } = useMicroGlobalData()
+const { locale } = useGlobalData()
 locale.value = 'zh'
 
 const { i18n } = createZlI18n({
@@ -843,15 +878,15 @@ createApp(App).use(i18n).use(ElementPlus).use(ZlUi).use(router).mount('#app')
 
 - `elLocales` 的 value 须是 Element Plus 语言包模块（`element-plus/es/locale/lang/<locale>`）。
 - **合并优先级（低 → 高）：内置 `zlMessages` → `loader` 返回的业务包 → 消费者 `messages` 覆盖项。**
-- 需完全自定义加载逻辑（如远端按需拉取）时，改用底层 `useLocale(options, loader)`（见 §12.1.4）；`createZlI18n` 内部即是对它的封装，并额外处理「默认包 + 覆盖 + EP 包」的合并。
+- 需完全自定义加载逻辑（如远端按需拉取）时，改用底层 `useLocale(options, loader)`（见 §12.1.3）；`createZlI18n` 内部即是对它的封装，并额外处理「默认包 + 覆盖 + EP 包」的合并。
 
 ### 13.3 根容器挂载（App.vue）
 
 ```vue
 <script setup lang="ts">
-import { useMicroGlobalData } from '@zl-ui-kit/composables'
+import { useGlobalData } from '@zl-ui-kit/composables'
 import { ZlI18nProvider } from '@zl-ui-kit/components'
-const { locale, isI18nKeyVisible } = useMicroGlobalData()
+const { locale, isI18nKeyVisible } = useGlobalData()
 </script>
 
 <template>
@@ -893,7 +928,7 @@ const text = t('zl.empty.noData', '暂无相关数据')
 | 内置默认 | 5 套主题（light / dark / red-light / red-dark / blue） | `zlMessages`（zh / zh-cn / en） |
 | 运行时定义 | `defineTheme({ name, base, colors, tokens })` | `createZlI18n({ messages })` 覆盖 / 新增语言 |
 | 引用 / 切换 | `setTheme('dark')` / `useTheme()` | `locale.value = 'en'` / `useLocale()` 返回的 `locale` |
-| 持久化 | `enableThemePersistence()` | `useMicroGlobalData().locale` 经 `$zl_locale` 持久化 |
+| 持久化 | `enableThemePersistence()` | `useGlobalData().locale` 经 `$zl_locale` 持久化 |
 | 细粒度覆盖 | CSS 变量 L1 覆写（`--zl-primary-6`） | `mergeMessages` / 直接覆盖单个 key |
 | 挂载点 | `body[data-theme]` | `<ZlI18nProvider>`（EP locale）+ `app.use(i18n)`（业务文案） |
 

package/dist/components/ZlChart/index.vue.d.ts

@@ -1,6 +1,8 @@
 type __VLS_Props = {
     /** 系列（单对象或数组）；其余图表配置经 attrs 透传（title/xAxis/yAxis/tooltip 等，可用 src/utils/echarts 工具构造） */
     series?: Record<string, any> | Array<Record<string, any>>;
+    /** 主题名：先 `import 'echarts/theme/v5'` 之类注册主题，再传 `theme="v5"`。升级到 echarts 6 后想保持 v5 观感时用 */
+    theme?: string;
 };
 declare function clear(): void;
 declare const _default: import('vue').DefineComponent<__VLS_Props, {

package/dist/components/ZlChart/index.vue.mjs

@@ -1,41 +1,44 @@
-import { defineComponent as m, useAttrs as v, computed as h, shallowRef as d, ref as _, watch as x, onMounted as k, onScopeDispose as w, openBlock as R, createElementBlock as y, nextTick as o } from "vue";
+import { defineComponent as v, useAttrs as h, computed as d, shallowRef as _, ref as x, watch as c, onMounted as k, onScopeDispose as w, openBlock as R, createElementBlock as y, nextTick as i } from "vue";
 import { useResizeObserver as z } from "@vueuse/core";
 import * as O from "echarts";
-const C = /* @__PURE__ */ m({
+const C = /* @__PURE__ */ v({
   name: "ZlChart",
   inheritAttrs: !1,
   __name: "index",
   props: {
-    series: {}
+    series: {},
+    theme: {}
   },
-  setup(a, { expose: c }) {
-    const i = a, l = v(), s = h(() => {
-      const { series: f, ...n } = l;
+  setup(l, { expose: u }) {
+    const s = l, p = h(), r = d(() => {
+      const { series: m, ...a } = p;
       return {
-        ...n,
-        series: [].concat(i.series ?? [])
+        ...a,
+        series: [].concat(s.series ?? [])
       };
-    }), e = d(), t = _();
-    async function r() {
-      await o(), e.value?.setOption(s.value);
+    }), e = _(), t = x();
+    async function n() {
+      await i(), e.value?.setOption(r.value);
     }
-    async function u() {
-      await o(), t.value && (e.value = O.init(t.value), r());
+    async function o() {
+      await i(), t.value && (e.value = O.init(t.value, s.theme), n());
     }
-    function p() {
+    function f() {
       e.value?.clear();
     }
     return z(t, () => {
       e.value?.resize();
-    }), x(() => s.value, () => {
-      r();
+    }), c(() => r.value, () => {
+      n();
+    }), c(() => s.theme, () => {
+      e.value?.dispose(), e.value = void 0, o();
     }), k(() => {
-      u();
+      o();
     }), w(() => {
       e.value?.dispose();
-    }), c({
-      clear: p
-    }), (f, n) => (R(), y("div", {
+    }), u({
+      clear: f
+    }), (m, a) => (R(), y("div", {
       ref_key: "chartRef",
       ref: t,
       class: "zl-chart"

package/dist/components/ZlEditor/setupMonacoEnvironment.d.ts

@@ -3,7 +3,7 @@
  * 库模式下 worker 无法静态打包（vite lib 限制），默认实现仅警告；
  * 消费方按官方方式自行提供 worker（或 CDN），经 setupMonacoEnvironment(getWorker) 注入。
  */
-type GetWorker = (...args: any[]) => Worker;
+export type GetWorker = (...args: any[]) => Worker;
 declare global {
     interface GlobalThis {
         MonacoEnvironment?: {
@@ -12,5 +12,4 @@ declare global {
     }
 }
 export declare function setupMonacoEnvironment(getWorker?: GetWorker): void;
-export {};
 //# sourceMappingURL=setupMonacoEnvironment.d.ts.map

package/dist/components/ZlEditor/setupMonacoEnvironment.mjs

@@ -1,9 +1,16 @@
-function n(o) {
-  globalThis.MonacoEnvironment?.getWorker || console.warn(
+function e(o) {
+  const n = globalThis.MonacoEnvironment?.getWorker;
+  if (o) {
+    globalThis.MonacoEnvironment = {
+      getWorker: o
+    };
+    return;
+  }
+  n || console.warn(
     "[ZlEditor] monaco worker 未配置：语言服务（TS/JSON/CSS 补全校验）不可用。请调用 setupMonacoEnvironment(getWorker) 注入（见 README「monaco worker 配置」）。"
   );
 }
 export {
-  n as setupMonacoEnvironment
+  e as setupMonacoEnvironment
 };
 //# sourceMappingURL=setupMonacoEnvironment.mjs.map

package/dist/components/ZlI18nProvider/index.vue.mjs

@@ -1,15 +1,15 @@
-import { defineComponent as t, openBlock as l, createBlock as a, unref as e, withCtx as n, renderSlot as c } from "vue";
-import { ElConfigProvider as s } from "element-plus";
-import { useMicroGlobalData as i } from "@zl-ui-kit/composables";
-const _ = /* @__PURE__ */ t({
+import { defineComponent as r, openBlock as l, createBlock as a, unref as e, withCtx as n, renderSlot as s } from "vue";
+import { ElConfigProvider as c } from "element-plus";
+import { useGlobalData as f } from "@zl-ui-kit/composables";
+const _ = /* @__PURE__ */ r({
   __name: "index",
-  setup(f) {
-    const { elLocaleMessages: o } = i();
-    return (r, m) => (l(), a(e(s), {
+  setup(i) {
+    const { elLocaleMessages: o } = f();
+    return (t, m) => (l(), a(e(c), {
       locale: e(o) || void 0
     }, {
       default: n(() => [
-        c(r.$slots, "default")
+        s(t.$slots, "default")
       ]),
       _: 3
     }, 8, ["locale"]));

package/dist/entries/editor.d.ts

@@ -7,6 +7,8 @@
  */
 export { default as ZlEditor } from '../components/ZlEditor/index.vue';
 export { default as ZlSqlEditor } from '../components/ZlEditor/ZlSqlEditor.vue';
+export { setupMonacoEnvironment } from '../components/ZlEditor/setupMonacoEnvironment';
+export type { GetWorker } from '../components/ZlEditor/setupMonacoEnvironment';
 export { useSqlCompletion } from '../components/ZlEditor/useSqlCompletion';
 export type { SqlTableColumn, SqlTableSchema } from '../components/ZlEditor/useSqlCompletion';
 //# sourceMappingURL=editor.d.ts.map

package/dist/entries/editor.mjs

@@ -1,10 +1,12 @@
 import { default as e } from "../components/ZlEditor/index.vue.mjs";
 import '../components/ZlEditor/index.css';/* empty css                                 */
-import { default as f } from "../components/ZlEditor/ZlSqlEditor.vue.mjs";
-import { useSqlCompletion as p } from "../components/ZlEditor/useSqlCompletion.mjs";
+import { default as m } from "../components/ZlEditor/ZlSqlEditor.vue.mjs";
+import { setupMonacoEnvironment as f } from "../components/ZlEditor/setupMonacoEnvironment.mjs";
+import { useSqlCompletion as i } from "../components/ZlEditor/useSqlCompletion.mjs";
 export {
   e as ZlEditor,
-  f as ZlSqlEditor,
-  p as useSqlCompletion
+  m as ZlSqlEditor,
+  f as setupMonacoEnvironment,
+  i as useSqlCompletion
 };
 //# sourceMappingURL=editor.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zl-ui-kit/components",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "type": "module",
   "description": "ZL UI 业务组件库（Element Plus 体系，Zl 前缀）——首批：Icon/AutoTooltip/Tag/CornerTag/Text/Title/Copy/Empty/Pagination/DictTag",
   "license": "MIT",
@@ -39,9 +39,9 @@
     "file-type": "^20.4.1",
     "dt-sql-parser": "^4.3.1",
     "sql-formatter": "^15.4.2",
-    "@zl-ui-kit/composables": "0.3.3",
-    "@zl-ui-kit/utils": "0.3.3",
-    "@zl-ui-kit/icons": "0.3.3"
+    "@zl-ui-kit/composables": "0.5.0",
+    "@zl-ui-kit/icons": "0.5.0",
+    "@zl-ui-kit/utils": "0.5.0"
   },
   "peerDependencies": {
     "@vueuse/core": "^12.3.0",
@@ -52,7 +52,7 @@
     "@vue-office/excel": "1.7.14",
     "@vue-office/pdf": "^2.0.10",
     "@vue-office/pptx": "1.0.1",
-    "echarts": "^5.6.0"
+    "echarts": "^5.6.0 || ^6.0.0"
   },
   "peerDependenciesMeta": {
     "monaco-editor": {
@@ -98,10 +98,10 @@
     "@vue-office/pdf": "^2.0.10",
     "@vue-office/pptx": "1.0.1",
     "echarts": "^5.6.0",
+    "@jichuang/eslint-config": "1.0.0",
     "@jichuang/vite-config": "1.0.0",
     "@jichuang/tsconfig": "1.0.0",
-    "@jichuang/eslint-config": "1.0.0",
-    "@zl-ui-kit/theme": "0.3.3"
+    "@zl-ui-kit/theme": "0.5.0"
   },
   "repository": {
     "type": "git",