xt-element-ui 2.1.4 → 2.1.6

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

@@ -8,6 +8,7 @@
 ```vue
 <template>
   <XtText type="primary">主要文本</XtText>
+  <div style="width: 80px;"><XtText ellipsis>溢出隐藏文本溢出隐藏文本</XtText></div>
 </template>
 ```
 :::

package/docs/components/base/xt-transfer-tree.md

@@ -0,0 +1,272 @@
+## XtTransferTree 树形穿梭框组件
+
+树形穿梭框组件，支持树形结构数据的穿梭，提供多种穿梭模式满足不同业务场景。
+
+## 基本用法
+
+::: demo 基本用法
+```vue
+<template>
+  <XtTransferTree 
+    :data="treeData" 
+    v-model="selectedIds" 
+    :height="400"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      selectedIds: [],
+      treeData: [
+        {
+          id: '1',
+          label: '一级菜单',
+          children: [
+            {
+              id: '1-1',
+              label: '二级菜单1'
+            },
+            {
+              id: '1-2',
+              label: '二级菜单2'
+            }
+          ]
+        },
+        {
+          id: '2',
+          label: '一级菜单2',
+          children: [
+            {
+              id: '2-1',
+              label: '二级菜单3'
+            }
+          ]
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 属性说明
+
+| 属性 | 类型 | 默认值 | 可选值 | 说明 |
+|------|------|--------|--------|------|
+| `value` / `v-model` | Array | `[]` | - | 已选择的节点 ID 数组 |
+| `data` | Array | `[]` | - | 树形数据源 |
+| `leftTitle` | String | `待选择` | - | 左侧面板标题 |
+| `rightTitle` | String | `已选择` | - | 右侧面板标题 |
+| `treeProps` | Object | `{ label, children, value }` | - | 树节点属性配置 |
+| `defaultExpandAll` | Boolean | `true` | - | 是否默认展开所有节点 |
+| `filterable` | Boolean | `false` | - | 是否支持搜索过滤 |
+| `showCheckbox` | Boolean | `true` | - | 是否显示复选框 |
+| `cascade` | Boolean | `true` | - | 是否级联选择 |
+| `transferMode` | String | `single` | `single`, `multiple`, `parent-child` | 穿梭模式 |
+| `buttonSize` | String | `small` | - | 按钮尺寸 |
+
+## 穿梭模式说明
+
+| 模式 | 说明 |
+|------|------|
+| `single` | 单选模式，点击节点或勾选后只穿梭当前节点 |
+| `multiple` | 多选模式，勾选多个节点后一次性穿梭 |
+| `parent-child` | 父子模式，穿梭父节点时自动包含所有子节点 |
+
+## 事件
+
+| 事件名 | 说明 | 参数 |
+|--------|------|------|
+| `change` | 数据变化时触发 | `{ value, addedKeys, removedKeys }` |
+
+## 示例
+
+### 父子级联穿梭
+
+::: demo 父子级联穿梭
+```vue
+<template>
+  <XtTransferTree 
+    :data="treeData" 
+    v-model="selectedIds" 
+    :height="400"
+    transfer-mode="parent-child"
+    @change="handleChange"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      selectedIds: [],
+      treeData: [
+        {
+          id: '1',
+          label: '部门A',
+          children: [
+            { id: '1-1', label: '员工1' },
+            { id: '1-2', label: '员工2' }
+          ]
+        },
+        {
+          id: '2',
+          label: '部门B',
+          children: [
+            { id: '2-1', label: '员工3' }
+          ]
+        }
+      ]
+    }
+  },
+  methods: {
+    handleChange({ value, addedKeys, removedKeys }) {
+      console.log('已选择:', value)
+      console.log('新增:', addedKeys)
+      console.log('移除:', removedKeys)
+    }
+  }
+}
+</script>
+```
+:::
+
+### 支持搜索过滤
+
+::: demo 支持搜索过滤
+```vue
+<template>
+  <XtTransferTree 
+    :data="treeData" 
+    v-model="selectedIds" 
+    :height="400"
+    :filterable="true"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      selectedIds: [],
+      treeData: [
+        {
+          id: '1',
+          label: '水果',
+          children: [
+            { id: '1-1', label: '苹果' },
+            { id: '1-2', label: '香蕉' },
+            { id: '1-3', label: '橙子' }
+          ]
+        },
+        {
+          id: '2',
+          label: '蔬菜',
+          children: [
+            { id: '2-1', label: '西红柿' },
+            { id: '2-2', label: '黄瓜' }
+          ]
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+### 不级联选择
+
+::: demo 不级联选择
+```vue
+<template>
+  <XtTransferTree 
+    :data="treeData" 
+    v-model="selectedIds" 
+    :height="400"
+    :cascade="false"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      selectedIds: [],
+      treeData: [
+        {
+          id: '1',
+          label: '分类1',
+          children: [
+            { id: '1-1', label: '项目1' },
+            { id: '1-2', label: '项目2' }
+          ]
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+### 点击穿梭（无复选框）
+
+::: demo 点击穿梭
+```vue
+<template>
+  <XtTransferTree 
+    :data="treeData" 
+    v-model="selectedIds" 
+    :height="400"
+    :show-checkbox="false"
+  />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      selectedIds: [],
+      treeData: [
+        {
+          id: '1',
+          label: '选项1'
+        },
+        {
+          id: '2',
+          label: '选项2'
+        }
+      ]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 方法
+
+| 方法名 | 说明 | 参数 |
+|--------|------|------|
+| `clearSelection` | 清空选择 | - |
+
+## 数据格式
+
+```javascript
+[
+  {
+    id: 'node-id',
+    label: '节点名称',
+    children: [
+      {
+        id: 'child-id',
+        label: '子节点名称'
+      }
+    ]
+  }
+]
+```

package/docs/components/utils/config.md

@@ -0,0 +1,285 @@
+## 全局配置
+
+## 概述
+
+提供全局配置管理工具函数，包括配置的获取、设置、重置以及主色调配置等功能。
+
+## 方法说明
+
+### getConfig()
+
+获取当前全局配置。
+
+```vue
+<template>
+  <div>
+    <XtText>当前配置：{{ JSON.stringify(config) }}</XtText>
+  </div>
+</template>
+
+<script>
+import { getConfig } from 'xt-element-ui'
+
+export default {
+  computed: {
+    config() {
+      return getConfig()
+    }
+  }
+}
+</script>
+```
+
+**返回值**：
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `theme` | String | 'white' | 主题类型 |
+| `size` | String | 'medium' | 字体大小 |
+| `primaryColor` | String | '#1890ff' | 主色调 |
+
+### setConfig(config)
+
+批量设置全局配置。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `config` | Object | 是 | 配置对象 |
+
+**config 参数**：
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `theme` | String | 主题类型：`white`、`dark` |
+| `size` | String | 字体大小：`small`、`medium`、`large` |
+| `primaryColor` | String | 主色调，十六进制颜色格式 |
+
+```vue
+<template>
+  <div>
+    <XtButton @click="initConfig">初始化配置</XtButton>
+  </div>
+</template>
+
+<script>
+import { setConfig } from 'xt-element-ui'
+
+export default {
+  methods: {
+    initConfig() {
+      setConfig({
+        theme: 'dark',
+        size: 'large',
+        primaryColor: '#1890ff'
+      })
+    }
+  }
+}
+</script>
+```
+
+### setPrimaryColor(color)
+
+设置全局主色调。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `color` | String | 是 | 十六进制颜色值 |
+
+```vue
+<template>
+  <div>
+    <XtButton @click="changePrimaryColor('#ff5722')">橙色主题</XtButton>
+    <XtButton @click="changePrimaryColor('#4caf50')">绿色主题</XtButton>
+  </div>
+</template>
+
+<script>
+import { setPrimaryColor } from 'xt-element-ui'
+
+export default {
+  methods: {
+    changePrimaryColor(color) {
+      setPrimaryColor(color)
+    }
+  }
+}
+</script>
+```
+
+### getPrimaryColor()
+
+获取当前主色调配置。
+
+```vue
+<template>
+  <div>
+    <XtText>当前主色调：{{ currentColor }}</XtText>
+  </div>
+</template>
+
+<script>
+import { getPrimaryColor } from 'xt-element-ui'
+
+export default {
+  computed: {
+    currentColor() {
+      return getPrimaryColor()
+    }
+  }
+}
+</script>
+```
+
+### resetConfig()
+
+重置为默认配置。
+
+```vue
+<template>
+  <div>
+    <XtButton @click="reset">重置配置</XtButton>
+  </div>
+</template>
+
+<script>
+import { resetConfig } from 'xt-element-ui'
+
+export default {
+  methods: {
+    reset() {
+      resetConfig()
+    }
+  }
+}
+</script>
+```
+
+### onConfigChange(listener)
+
+监听配置变化，返回取消订阅函数。
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `listener` | Function | 是 | 变化监听回调函数 |
+
+**回调参数**：
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `key` | String | 变化的配置项：`theme`、`size`、`primaryColor` |
+| `value` | Any | 配置项的新值 |
+
+```vue
+<template>
+  <div>
+    <XtText>配置变化次数：{{ changeCount }}</XtText>
+  </div>
+</template>
+
+<script>
+import { onConfigChange } from 'xt-element-ui'
+
+export default {
+  data() {
+    return {
+      changeCount: 0,
+      unsubscribe: null
+    }
+  },
+  mounted() {
+    this.unsubscribe = onConfigChange((key, value) => {
+      this.changeCount++
+      console.log(`配置 ${key} 已变更为:`, value)
+    })
+  },
+  beforeDestroy() {
+    if (this.unsubscribe) {
+      this.unsubscribe()
+    }
+  }
+}
+</script>
+```
+
+## 使用示例
+
+### 完整配置示例
+
+```vue
+<template>
+  <XtCard>
+    <XtCardItem title="当前配置">
+      <XtText>{{ JSON.stringify(config) }}</XtText>
+    </XtCardItem>
+    
+    <XtCardItem title="配置操作">
+      <XtFlexBox direction="vertical" style="gap: 12px;">
+        <XtButton @click="updateConfig">更新配置</XtButton>
+        <XtButton @click="changePrimary('#67c23a')">修改主色调</XtButton>
+        <XtButton type="danger" @click="reset">重置</XtButton>
+      </XtFlexBox>
+    </XtCardItem>
+    
+    <XtCardItem title="配置变化">
+      <XtText>变化次数：{{ changeCount }}</XtText>
+    </XtCardItem>
+  </XtCard>
+</template>
+
+<script>
+import { 
+  getConfig, 
+  setConfig, 
+  setPrimaryColor, 
+  resetConfig,
+  onConfigChange 
+} from 'xt-element-ui'
+
+export default {
+  data() {
+    return {
+      changeCount: 0,
+      unsubscribe: null
+    }
+  },
+  computed: {
+    config() {
+      return getConfig()
+    }
+  },
+  mounted() {
+    this.unsubscribe = onConfigChange(() => {
+      this.changeCount++
+    })
+  },
+  beforeDestroy() {
+    if (this.unsubscribe) {
+      this.unsubscribe()
+    }
+  },
+  methods: {
+    updateConfig() {
+      setConfig({
+        theme: 'dark',
+        size: 'medium',
+        primaryColor: '#1890ff'
+      })
+    },
+    changePrimary(color) {
+      setPrimaryColor(color)
+    },
+    reset() {
+      resetConfig()
+    }
+  }
+}
+</script>
+```
+
+## 注意事项
+
+1. `setPrimaryColor` 只支持十六进制颜色格式（如 `#1890ff`、`#fff`）
+2. 设置主色调时，会自动生成对应的浅色系列（light-3 到 light-9）
+3. `onConfigChange` 返回的取消订阅函数应在组件销毁时调用，避免内存泄漏
+4. 所有配置修改都会触发 `onConfigChange` 监听器