xt-element-ui 2.2.3 → 2.2.4

package/docs/components/base/theme.md

@@ -0,0 +1,248 @@
+## iframe 主题注入
+
+## 概述
+
+为微前端架构提供统一的主题管理方案。主系统切换主题后，子系统 iframe 中的 Element UI 组件会自动同步换色，子系统无需任何改造。
+
+### 设计思路
+
+| 角色 | 职责 |
+|------|------|
+| 主系统 | 统一管理主题状态，注入 CSS 变量到 iframe |
+| 子系统 | 标准 Element UI 项目，无需改造 |
+| 注入时机 | iframe 加载完成后自动注入 |
+
+### 工作流程
+
+```
+1. 主系统调用 setTheme('dark')
+      ↓
+2. utils 同步更新 --el-* + --xt-* 变量到主文档
+      ↓
+3. utils 通过 onConfigChange 广播主题变更
+      ↓
+4. 所有 IframeThemeInjector 实例收到通知
+      ↓
+5. 实例通过 applyThemeVars 将新主题应用到管理的 iframe
+      ↓
+6. 所有 iframe 内的 Element UI 组件实时换色
+```
+
+## 快速开始
+
+### JS 模块（CSS 已内联为字符串）
+
+```javascript
+import { createThemeInjector } from 'xt-element-ui'
+
+// 创建注入器（CSS 已内联，无需手动提供）
+const injector = createThemeInjector({ theme: 'white' })
+
+// 注入所有 iframe
+injector.injectAll('iframe')
+```
+
+### 直接引用 CSS 文件
+
+如果使用独立 CSS 文件注入：
+
+```html
+<link rel="stylesheet" href="xt-element-ui/lib/theme/element-vars.css">
+<link rel="stylesheet" href="xt-element-ui/lib/theme/element-overrides.css">
+```
+
+### 手动注入 iframe（使用独立 CSS 文件）
+
+```javascript
+// 动态加载并注入
+fetch('/lib/theme/element-vars.css')
+  .then(res => res.text())
+  .then(css => {
+    const style = document.createElement('style')
+    style.textContent = css
+    iframe.contentDocument.head.appendChild(style)
+  })
+```
+
+## API 说明
+
+### createThemeInjector(options)
+
+创建一个预配置的主题注入器实例。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `options.theme` | String | 否 | 初始主题：`white`、`dark`（默认 `white`） |
+| `options.primaryColor` | String | 否 | 初始主色调（默认 `#1890ff`） |
+| `options.brand` | String | 否 | 品牌标识：`''`、`water`、`electricity`、`gas` |
+| `options.persist` | Boolean | 否 | 是否持久化到 localStorage（默认 `false`） |
+| `options.onThemeChange` | Function | 否 | 主题变化回调 |
+
+**返回值**：`IframeThemeInjector` 实例
+
+### inject(iframe)
+
+向指定 iframe 注入主题 CSS。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `iframe` | HTMLIFrameElement | 是 | iframe 元素 |
+
+**返回值**：`boolean` 是否注入成功
+
+### injectAll(selector)
+
+批量注入所有匹配选择器的 iframe。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `selector` | String | 否 | CSS 选择器（默认 `'iframe'`） |
+
+**返回值**：`number` 成功注入的数量
+
+### setTheme(theme, options)
+
+切换主题，自动同步到主文档和所有 iframe。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `theme` | String | 是 | `white`、`dark` |
+| `options.primaryColor` | String | 否 | 同时设置主色调 |
+| `options.brand` | String | 否 | 同时设置品牌色 |
+
+```javascript
+const injector = createThemeInjector({ theme: 'white' })
+injector.injectAll('iframe')
+
+// 切换主题（自动同步主文档 + 所有 iframe）
+injector.setTheme('dark')
+```
+
+### setPrimaryColor(color)
+
+设置主色调，自动同步到主文档和所有 iframe。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `color` | String | 是 | 十六进制颜色值 |
+
+### setBrand(brand)
+
+设置品牌色，切换对应品牌的主色调。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `brand` | String | 是 | `''`、`water`、`electricity`、`gas` |
+
+**品牌色映射**：
+
+| 品牌 | 亮色 | 暗色 |
+|------|------|------|
+| `water` | `#0077be` | `#0099cc` |
+| `electricity` | `#2ecc71` | `#27ae60` |
+| `gas` | `#f39c12` | `#e67e22` |
+
+### startObserving(target)
+
+开始自动监听 DOM 变化，自动注入新添加的 iframe。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `target` | HTMLElement | 否 | 监听容器（默认 `document.body`） |
+
+### stopObserving()
+
+停止自动监听。
+
+### remove(iframe)
+
+移除指定 iframe 的注入。
+
+### removeAll()
+
+移除所有 iframe 的注入。
+
+### destroy()
+
+销毁实例，清理所有资源。
+
+## 使用示例
+
+### 基本用法
+
+```javascript
+import { createThemeInjector } from 'xt-element-ui'
+
+// 创建注入器
+const injector = createThemeInjector({ theme: 'white' })
+
+// 注入现有 iframe
+injector.injectAll('iframe')
+
+// 切换主题
+injector.setTheme('dark')
+
+// 设置品牌色
+injector.setBrand('water')
+
+// 销毁
+injector.destroy()
+```
+
+### 与全局主题配置联动
+
+```javascript
+import { setTheme, onConfigChange } from 'xt-element-ui'
+import { createThemeInjector } from 'xt-element-ui'
+
+// 1. 创建注入器
+const injector = createThemeInjector({ theme: 'white' })
+
+// 2. 注入 iframe
+injector.injectAll('iframe')
+
+// 3. 监听全局主题变化（保持同步）
+const unsubscribe = onConfigChange((key, value) => {
+  if (key === 'theme') {
+    console.log('主题变更：', value)
+  }
+})
+
+// 4. 通过全局 API 切换主题（自动同步到 iframe）
+setTheme('dark')
+```
+
+### 自动监听新增 iframe
+
+```javascript
+const injector = createThemeInjector({ theme: 'white' })
+injector.startObserving()  // 自动监听 DOM
+
+// 动态添加的 iframe 会自动被注入主题
+const newIframe = document.createElement('iframe')
+document.body.appendChild(newIframe)  // 自动注入
+
+// 清理
+injector.stopObserving()
+```
+
+### 持久化配置
+
+```javascript
+// 创建时启用持久化
+const injector = createThemeInjector({
+  theme: 'white',
+  persist: true  // 保存到 localStorage
+})
+
+// 下次加载时自动恢复
+// localStorage 中的配置会自动应用
+```
+
+## 注意事项
+
+1. **跨域限制**：跨域 iframe 无法访问，将输出警告日志
+2. **加载时机**：iframe 必须加载完成后才能注入（注入器会自动等待 `load` 事件）
+3. **CSS 内联**：推荐使用 `createThemeInjector()`，CSS 已内联无需额外配置
+4. **主题同步**：通过 `onConfigChange` 实现主文档和 iframe 的主题自动同步
+5. **性能**：大量 iframe 场景建议使用 `startObserving` 自动管理，避免手动注入遗漏

package/docs/components/base/xt-list.md

@@ -164,7 +164,7 @@ export default {
 
 ### 虚拟滚动
 
-大数据量场景下启用虚拟滚动，仅渲染可见区域的卡片。
+大数据量场景下启用虚拟滚动，仅渲染可见区域的卡片。组件内部使用 `XtScroll`（原生滚动容器）作为滚动容器，提供流畅的滚动体验。
 
 ::: demo 虚拟滚动
 ```vue

package/docs/components/base/xt-scroll-arrow.md

@@ -1,4 +1,4 @@
-滚动箭头组件用于在内容溢出时显示滚动箭头，支持水平和垂直方向的滚动。
+滚动箭头组件用于在内容溢出时显示滚动箭头，支持水平和垂直方向的滚动。基于 `XtScroll` 封装，支持虚拟滚动模式处理海量数据。
 
 ## 基本用法
 
@@ -24,11 +24,27 @@
 | `autoHide` | Boolean | true | - | 是否自动隐藏箭头（滚动到边界时隐藏） |
 | `height` | String / Number | - | - | 容器高度 |
 | `width` | String / Number | - | - | 容器宽度 |
+| `v-scroll` | Boolean | false | - | 是否启用虚拟滚动 |
+| `v-scroll-data` | Array | [] | - | 虚拟滚动数据源 |
+| `item-size` | Number | 50 | - | 每个 item 的固定尺寸（px） |
+| `key-field` | String | 'id' | - | item 的唯一键字段名 |
+| `buffer-size` | Number | 5 | - | 预渲染缓冲区大小 |
+| `v-scroll-loading` | Boolean | false | - | 虚拟滚动加载状态 |
+| `load-more` | Boolean | false | - | 是否启用加载更多 |
+| `load-more-text` | String | '加载更多' | - | 加载更多按钮文字 |
+| `load-more-loading` | Boolean | false | - | 加载更多按钮加载状态 |
+
+## 插槽说明
+| 插槽名 | 作用域 | 说明 |
+|--------|--------|------|
+| `default` | — | 非虚拟滚动模式下的默认内容 |
+| `vitem` | `{ item, index }` | 虚拟滚动模式下每个 item 的渲染内容 |
 
 ## 事件说明
 | 事件名称 | 说明 | 参数 |
 |----------|------|------|
 | `scroll` | 滚动时触发 | `scrollContainer` - 滚动容器元素 |
+| `load-more` | 触发加载更多 | — |
 
 ## 示例
 
@@ -153,4 +169,74 @@ export default {
   </XtScrollArrow>
 </template>
 ```
+:::
+
+### 虚拟滚动（水平）
+
+::: demo 虚拟滚动（水平）—— 渲染 5000 条数据
+```vue
+<template>
+  <XtScrollArrow
+    direction="horizontal"
+    :v-scroll="true"
+    :v-scroll-data="tagData"
+    :item-size="120"
+  >
+    <template #vitem="{ item }">
+      <div style="width: 100px; height: 40px; display: flex; align-items: center; justify-content: center; background: #ecf5ff; border-radius: 4px; margin: 0 4px; color: #409eff; font-size: 13px;">
+        {{ item.label }}
+      </div>
+    </template>
+  </XtScrollArrow>
+</template>
+<script>
+export default {
+  data() {
+    return {
+      tagData: Array.from({ length: 5000 }, (_, i) => ({
+        id: i,
+        label: `标签 ${i + 1}`
+      }))
+    }
+  }
+}
+</script>
+```
+:::
+
+### 虚拟滚动（垂直）
+
+::: demo 虚拟滚动（垂直）—— 渲染 5000 条数据
+```vue
+<template>
+  <XtScrollArrow
+    direction="vertical"
+    :height="200"
+    :v-scroll="true"
+    :v-scroll-data="listData"
+    :item-size="48"
+  >
+    <template #vitem="{ item, index }">
+      <div style="height: 48px; display: flex; align-items: center; padding: 0 12px; border-bottom: 1px solid #ebeef5; gap: 8px;">
+        <span style="color: #909399; font-size: 12px;">{{ index + 1 }}</span>
+        <span>{{ item.name }}</span>
+        <span style="color: #909399; font-size: 12px; margin-left: auto;">{{ item.desc }}</span>
+      </div>
+    </template>
+  </XtScrollArrow>
+</template>
+<script>
+export default {
+  data() {
+    return {
+      listData: Array.from({ length: 5000 }, (_, i) => ({
+        id: i,
+        name: `用户 ${i + 1}`,
+        desc: `部门 ${(i % 10) + 1}`
+      }))
+    }
+  }
+}
+</script>
+```
 :::

package/docs/components/base/xt-scroll.md

@@ -0,0 +1,237 @@
+原生实现的虚拟滚动容器组件，支持横向和纵向虚拟滚动，适用于大数据量列表的高性能渲染。不依赖 `el-scrollbar`，采用原生 CSS 滚动容器，更轻量灵活。
+
+### 基本用法
+
+::: demo 基本用法
+```vue
+<template>
+  <XtScroll :style="{ height: '400px' }" :v-scroll="true" :data="items" :item-size="50" key-field="id">
+    <template #item="{ item, index }">
+      <div style="padding: 12px; border-bottom: 1px solid #eee;">
+        <strong>{{ index + 1 }}.</strong> {{ item.label }}
+      </div>
+    </template>
+  </XtScroll>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      items: Array.from({ length: 10000 }, (_, i) => ({ id: i, label: `数据项 ${i + 1}` }))
+    }
+  }
+}
+</script>
+```
+:::
+
+### 纵向虚拟滚动
+
+::: demo 设置 `scroll-direction="vertical"`（默认值）启用纵向虚拟滚动。
+```vue
+<template>
+  <XtScroll
+    :style="{ height: '300px' }"
+    :v-scroll="true"
+    :data="verticalData"
+    :item-size="40"
+    key-field="id"
+    scroll-direction="vertical"
+  >
+    <template #item="{ item }">
+      <div style="padding: 0 12px; line-height: 40px; height: 40px; border-bottom: 1px solid #ebeef5;">
+        {{ item.name }} - {{ item.email }}
+      </div>
+    </template>
+  </XtScroll>
+</template>
+<script>
+export default {
+  data() {
+    return {
+      verticalData: Array.from({ length: 5000 }, (_, i) => ({
+        id: i,
+        name: `用户 ${i + 1}`,
+        email: `user${i + 1}@example.com`
+      }))
+    }
+  }
+}
+</script>
+```
+:::
+
+### 横向虚拟滚动
+
+::: demo 设置 `scroll-direction="horizontal"` 启用横向虚拟滚动，适用于超宽表格、时间轴等场景。
+```vue
+<template>
+  <XtScroll
+    :style="{ width: '600px', height: '80px' }"
+    :v-scroll="true"
+    :data="horizontalData"
+    :item-size="120"
+    scroll-direction="horizontal"
+  >
+    <template #item="{ item, index }">
+      <div style="width: 120px; height: 80px; display: inline-flex; align-items: center; justify-content: center; background: #f0f2f5; margin-right: 4px; border-radius: 4px;">
+        <span>{{ item }}</span>
+      </div>
+    </template>
+  </XtScroll>
+</template>
+<script>
+export default {
+  data() {
+    return {
+      horizontalData: Array.from({ length: 1000 }, (_, i) => `标签 ${i + 1}`)
+    }
+  }
+}
+</script>
+```
+:::
+
+### 非虚拟滚动模式
+
+::: demo `vScroll` 为 false 时，使用默认插槽正常渲染，原生滚动条提供流畅的滚动体验。
+```vue
+<template>
+  <XtScroll :style="{ height: '200px' }">
+    <div v-for="i in 20" :key="i" style="padding: 8px; border-bottom: 1px solid #eee;">
+      内容行 {{ i }} - 原生滚动条
+    </div>
+  </XtScroll>
+</template>
+```
+:::
+
+### 配合 XtList 使用
+
+::: demo XtList 内置了 XtScroll，开启 `virtual-scroll` 即可启用虚拟滚动。
+```vue
+<template>
+  <XtList
+    :data="listData"
+    :columns="2"
+    :virtual-scroll="true"
+    :item-height="160"
+    :height="400"
+    title="订单列表（虚拟滚动）"
+  />
+</template>
+<script>
+export default {
+  data() {
+    return {
+      listData: Array.from({ length: 5000 }, (_, i) => ({
+        title: `订单 #${i + 1}`,
+        subtitle: `2024-${String(Math.ceil((i + 1) / 30)).padStart(2, '0')}-${String((i % 28) + 1).padStart(2, '0')}`,
+        content: `金额: ¥${(Math.random() * 1000).toFixed(2)}`,
+        footer: i % 3 === 0 ? '已完成' : i % 3 === 1 ? '待发货' : '已取消'
+      }))
+    }
+  }
+}
+</script>
+```
+:::
+
+### 配合 XtScrollArrow 使用
+
+::: demo XtScrollArrow 内置了 XtScroll，开启虚拟滚动后支持海量数据带箭头导航。
+```vue
+<template>
+  <XtScrollArrow
+    direction="horizontal"
+    :v-scroll="true"
+    :v-scroll-data="arrowData"
+    :item-size="120"
+  >
+    <template #vitem="{ item }">
+      <div style="width: 100px; height: 40px; display: flex; align-items: center; justify-content: center; background: #ecf5ff; border-radius: 4px; margin: 0 4px;">
+        {{ item.label }}
+      </div>
+    </template>
+  </XtScrollArrow>
+</template>
+<script>
+export default {
+  data() {
+    return {
+      arrowData: Array.from({ length: 200 }, (_, i) => ({ id: i, label: `标签 ${i + 1}` }))
+    }
+  }
+}
+</script>
+```
+:::
+
+### Attributes
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| v-scroll | 是否启用虚拟滚动 | boolean | false |
+| data | 虚拟滚动数据源 | array | [] |
+| item-size | 每个 item 的固定尺寸（px），纵向为高度，横向为宽度 | number | 50 |
+| key-field | item 的唯一键字段名 | string | 'id' |
+| buffer-size | 预渲染缓冲区大小（item 数量） | number | 5 |
+| scroll-direction | 虚拟滚动方向 | 'vertical' \| 'horizontal' | 'vertical' |
+| item-class-name | item 的自定义 CSS 类名 | string | '' |
+| height | 容器高度 | number \| string | '' |
+| max-height | 容器最大高度 | number \| string | '' |
+| width | 容器宽度 | number \| string | '' |
+| max-width | 容器最大宽度 | number \| string | '' |
+| loading | 加载状态 | boolean | false |
+| empty-text | 空数据提示文字 | string | '暂无数据' |
+| load-more | 是否启用加载更多 | boolean | false |
+| load-more-text | 加载更多按钮文字 | string | '加载更多' |
+| load-more-loading | 加载更多按钮加载状态 | boolean | false |
+
+### Slots
+
+| 名称 | 说明 | 作用域 |
+|------|------|--------|
+| default | 非虚拟滚动模式下的默认内容 | — |
+| item | 虚拟滚动模式下每个 item 的渲染内容 | `{ item, index }` |
+| empty | 空数据时的自定义内容 | — |
+| loading | 加载中的自定义内容 | — |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+|--------|------|----------|
+| scroll | 滚动事件 | `{ scrollTop, scrollLeft }` |
+| load-more | 触发加载更多 | — |
+
+### Methods
+
+| 方法名 | 说明 | 参数 |
+|--------|------|------|
+| scrollTo(pos) | 滚动到指定位置 | `pos: number` |
+| scrollToItem(index) | 滚动到指定索引的 item | `index: number` |
+| scrollToStart() | 滚动到顶部/左侧 | — |
+| scrollToEnd() | 滚动到底部/右侧 | — |
+| getScrollPos() | 获取当前滚动位置 | — |
+| getScrollContainer() | 获取原生滚动容器 DOM 元素 | — |
+
+### XtScrollArrow 新增属性
+
+| 参数 | 说明 | 类型 | 默认值 |
+|------|------|------|--------|
+| v-scroll | 是否启用虚拟滚动 | boolean | false |
+| v-scroll-data | 虚拟滚动数据源 | array | [] |
+| item-size | 每个 item 的固定尺寸（px） | number | 50 |
+| key-field | item 的唯一键字段名 | string | 'id' |
+| buffer-size | 预渲染缓冲区大小 | number | 5 |
+| v-scroll-loading | 虚拟滚动加载状态 | boolean | false |
+| load-more | 是否启用加载更多 | boolean | false |
+| load-more-text | 加载更多按钮文字 | string | '加载更多' |
+| load-more-loading | 加载更多按钮加载状态 | boolean | false |
+
+### XtScrollArrow 新增 Slot
+
+| 名称 | 说明 | 作用域 |
+|------|------|--------|
+| vitem | 虚拟滚动模式下每个 item 的渲染内容 | `{ item, index }` |

package/docs/components/utils/config.md

@@ -80,12 +80,25 @@ export default {
 
 ### setPrimaryColor(color)
 
-设置全局主色调。
+设置全局主色调，同时更新 `--el-color-primary*`（Element UI）和 `--xt-color-primary*`（xt 组件）两套 CSS 变量。
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
 | `color` | String | 是 | 十六进制颜色值 |
 
+**自动衍生变量**：设置主色后会自动生成以下 Element UI 变量：
+
+| 变量 | 说明 |
+|------|------|
+| `--el-color-primary` | 主色 |
+| `--el-color-primary-light-3` | 主色 +30% 亮度 |
+| `--el-color-primary-light-5` | 主色 +50% 亮度 |
+| `--el-color-primary-light-7` | 主色 +70% 亮度 |
+| `--el-color-primary-light-8` | 主色 +80% 亮度 |
+| `--el-color-primary-light-9` | 主色 +90% 亮度 |
+| `--el-color-primary-dark-2` | 主色 -20% 亮度 |
+| `--el-color-primary-rgb` | 主色 RGB 值 |
+
 ```vue
 <template>
   <div>
@@ -280,6 +293,7 @@ export default {
 ## 注意事项
 
 1. `setPrimaryColor` 只支持十六进制颜色格式（如 `#1890ff`、`#fff`）
-2. 设置主色调时，会自动生成对应的浅色系列（light-3 到 light-9）
-3. `onConfigChange` 返回的取消订阅函数应在组件销毁时调用，避免内存泄漏
-4. 所有配置修改都会触发 `onConfigChange` 监听器
+2. 设置主色调时，会自动生成对应的浅色系列（light-3 到 light-9）和暗色系列（dark-2）
+3. `setPrimaryColor` 会**同时设置** `--el-*`（Element UI）和 `--xt-*`（xt 组件）两套变量
+4. `onConfigChange` 返回的取消订阅函数应在组件销毁时调用，避免内存泄漏
+5. 所有配置修改都会触发 `onConfigChange` 监听器