xt-element-ui 1.2.4 → 1.2.5

package/docs/components/base/xt-config-provider.md

@@ -0,0 +1,199 @@
+## XtConfigProvider 配置提供者
+
+配置提供者组件用于全局配置主题和样式变量。
+
+## 基本用法
+
+::: demo 基本用法
+```vue
+<template>
+  <XtConfigProvider :theme="theme" proxyElement="body">
+    <div>
+      <XtButton type="primary" @click="handleSwitchTheme">主题按钮</XtButton>
+    </div>
+  </XtConfigProvider>
+</template>
+<script>
+  export default {
+    data(){
+      return {
+        theme: 'white'
+      }
+    },
+    methods: {
+      handleSwitchTheme() {
+        this.theme = this.theme == 'dark' ? 'white': 'dark'
+      }
+    }
+  }
+</script>
+```
+:::
+
+## 属性说明
+| 属性 | 类型 | 默认值 | 可选值 | 说明 |
+|------|------|--------|--------|------|
+| `primaryColor` | String | - | - | 自定义主题色 |
+| `theme` | String | - | `dark`、`light` | 主题模式 |
+| `size` | String | - | `small`、`medium`、`large` | 组件尺寸 |
+| `injectBackground` | Boolean | - | - | 是否注入背景色到根元素 |
+| `injectColor` | Boolean | - | - | 是否注入文字颜色到根元素 |
+| `tag` | String | 'div' | - | 根元素标签 |
+| `proxyElement` | HTMLElement / String | - | - | 代理元素 |
+| `vars` | Object | - | - | 自定义 CSS 变量 |
+
+## 示例
+
+### 自定义主题色
+
+::: demo 自定义主题色
+```vue
+<template>
+  <XtConfigProvider :primaryColor="'#722ed1'">
+    <div>
+      <XtButton type="primary">紫色主题按钮</XtButton>
+      <XtCard title="自定义主题卡片">
+        <XtText type="primary">主题色文本</XtText>
+      </XtCard>
+    </div>
+  </XtConfigProvider>
+</template>
+```
+:::
+
+### 亮色主题
+
+::: demo 亮色主题
+```vue
+<template>
+  <XtConfigProvider theme="light" injectBackground>
+    <div style="min-height: 100px; padding: 16px;">
+      <XtCard title="亮色模式卡片">
+        <XtText type="primary">亮色主题内容</XtText>
+      </XtCard>
+      <XtButton type="primary">亮色主题按钮</XtButton>
+    </div>
+  </XtConfigProvider>
+</template>
+```
+:::
+
+### 自定义 CSS 变量
+
+::: demo 自定义 CSS 变量
+```vue
+<template>
+  <XtConfigProvider :vars="{
+    '--xt-color-primary': '#52c41a',
+    '--xt-color-success': '#13c2c2',
+    '--xt-flex-box-gap': '20px'
+  }">
+    <XtFlexBox>
+      <XtButton type="primary">绿色主题按钮</XtButton>
+      <XtButton type="success">青色成功按钮</XtButton>
+    </XtFlexBox>
+  </XtConfigProvider>
+</template>
+```
+:::
+
+### 组合配置
+
+::: demo 组合配置
+```vue
+<template>
+  <XtConfigProvider 
+    :primaryColor="'#1890ff'"
+    size="medium"
+  >
+    <div style="padding: 16px;">
+      <XtCard title="综合配置示例">
+        <XtText type="primary">主题色: #1890ff</XtText>
+        <XtText type="success">尺寸: medium</XtText>
+      </XtCard>
+      <XtFlexBox gap="16px" style="margin-top: 16px;">
+        <XtButton type="primary">主要按钮</XtButton>
+        <XtButton type="success">成功按钮</XtButton>
+        <XtButton type="warning">警告按钮</XtButton>
+      </XtFlexBox>
+    </div>
+  </XtConfigProvider>
+</template>
+```
+:::
+
+### 动态主题切换
+::: demo 动态主题切换
+```vue
+<template>
+  <XtConfigProvider 
+    :primaryColor="primaryColor"
+    :theme="currentTheme"
+    injectBackground
+  >
+    <div style="min-height: 120px; padding: 16px;">
+      <XtFlexBox content="space-between" style="margin-bottom: 16px;">
+        <span>当前主题: {{ currentTheme }}</span>
+        <XtFlexBox gap="8px">
+          <XtButton 
+            type="primary" 
+            plain
+            @click="switchTheme"
+          >
+            切换主题
+          </XtButton>
+          <XtButton 
+            type="success" 
+            plain
+            @click="changeColor"
+          >
+            更换主题色
+          </XtButton>
+        </XtFlexBox>
+      </XtFlexBox>
+      <XtCard title="动态主题示例">
+        <XtText type="primary">当前主题色: {{ primaryColor }}</XtText>
+      </XtCard>
+    </div>
+  </XtConfigProvider>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      primaryColor: '#1890ff',
+      currentTheme: 'light',
+      colors: ['#1890ff', '#52c41a', '#faad14', '#f5222d', '#722ed1']
+    }
+  },
+  methods: {
+    switchTheme() {
+      this.currentTheme = this.currentTheme === 'light' ? 'dark' : 'light'
+    },
+    changeColor() {
+      const randomIndex = Math.floor(Math.random() * this.colors.length)
+      this.primaryColor = this.colors[randomIndex]
+    }
+  }
+}
+</script>
+```
+:::
+
+## 支持的 CSS 变量
+
+| CSS 变量 | 说明 |
+|----------|------|
+| `--xt-color-primary` | 主色 |
+| `--xt-color-success` | 成功色 |
+| `--xt-color-warning` | 警告色 |
+| `--xt-color-danger` | 危险色 |
+| `--xt-color-info` | 信息色 |
+| `--xt-text-color-primary` | 主要文字颜色 |
+| `--xt-text-color-regular` | 常规文字颜色 |
+| `--xt-text-color-secondary` | 次要文字颜色 |
+| `--xt-bg-color` | 背景颜色 |
+| `--xt-bg-color-page` | 页面背景颜色 |
+| `--xt-border-color` | 边框颜色 |
+| `--xt-flex-box-gap` | FlexBox 默认间距 |

package/docs/components/base/xt-flex-box.md

@@ -0,0 +1,115 @@
+## XtFlexBox 弹性布局组件
+
+弹性布局组件，基于 CSS Flexbox 实现，提供便捷的布局能力。
+
+## 基本用法
+
+::: demo 基本用法
+```vue
+<template>
+  <XtFlexBox gap="16px">
+    <div style="width: 80px; height: 40px; background: #f0f0f0; display: flex; align-items: center; justify-content: center;">子元素1</div>
+    <div style="width: 80px; height: 40px; background: #f0f0f0; display: flex; align-items: center; justify-content: center;">子元素2</div>
+    <div style="width: 80px; height: 40px; background: #f0f0f0; display: flex; align-items: center; justify-content: center;">子元素3</div>
+  </XtFlexBox>
+</template>
+```
+:::
+
+## 属性说明
+| 属性 | 类型 | 默认值 | 可选值 | 说明 |
+|------|------|--------|--------|------|
+| `type` | String | flex | - | 布局类型 |
+| `align` | String | center | `start`、`center`、`end`、`stretch`、`baseline` | 交叉轴对齐方式 |
+| `content` | String | start | `start`、`center`、`end`、`between`、`around`、`evenly` | 主轴对齐方式 |
+| `direction` | String | row | `row`、`row-reverse`、`column`、`column-reverse` | 排列方向 |
+| `wrap` | String | unset | `wrap`、`nowrap`、`wrap-reverse` | 是否换行 |
+| `gap` | String | - | - | 子元素间距 |
+
+## 示例
+
+### 水平居中且两端对齐
+::: demo 水平居中且两端对齐
+```vue
+<template>
+  <XtFlexBox content="space-between" align="center">
+    <span>左侧内容</span>
+    <span>右侧内容</span>
+  </XtFlexBox>
+</template>
+```
+:::
+
+### 垂直布局
+
+::: demo 垂直布局
+```vue
+<template>
+  <XtFlexBox direction="column" gap="12px">
+    <div style="background: #1890ff; color: white; padding: 8px;">顶部</div>
+    <div style="background: #52c41a; color: white; padding: 8px;">中部</div>
+    <div style="background: #faad14; color: white; padding: 8px;">底部</div>
+  </XtFlexBox>
+</template>
+```
+:::
+
+### 均匀分布
+
+::: demo 均匀分布
+```vue
+<template>
+  <XtFlexBox content="space-around">
+    <div style="width: 60px; height: 60px; background: #e6f7ff; border-radius: 8px; display: flex; align-items: center; justify-content: center;">1</div>
+    <div style="width: 60px; height: 60px; background: #e6f7ff; border-radius: 8px; display: flex; align-items: center; justify-content: center;">2</div>
+    <div style="width: 60px; height: 60px; background: #e6f7ff; border-radius: 8px; display: flex; align-items: center; justify-content: center;">3</div>
+    <div style="width: 60px; height: 60px; background: #e6f7ff; border-radius: 8px; display: flex; align-items: center; justify-content: center;">4</div>
+  </XtFlexBox>
+</template>
+```
+:::
+
+### 自动换行
+
+::: demo 自动换行
+```vue
+<template>
+  <XtFlexBox wrap="wrap" gap="8px">
+    <div v-for="i in 10" :key="i" style="width: 80px; height: 80px; background: #f0f0f0; border-radius: 8px; display: flex; align-items: center; justify-content: center;">{{ i }}</div>
+  </XtFlexBox>
+</template>
+```
+:::
+
+### 反向排列
+
+::: demo 反向排列
+```vue
+<template>
+  <XtFlexBox direction="row-reverse">
+    <span style="padding: 8px; background: #f5f5f5;">第一</span>
+    <span style="padding: 8px; background: #f5f5f5;">第二</span>
+    <span style="padding: 8px; background: #f5f5f5;">第三</span>
+  </XtFlexBox>
+</template>
+```
+:::
+
+### 嵌套使用
+
+::: demo 嵌套使用
+```vue
+<template>
+  <XtFlexBox direction="column" gap="16px">
+    <XtFlexBox content="space-between">
+      <span>头部左侧</span>
+      <span>头部右侧</span>
+    </XtFlexBox>
+    <XtFlexBox>
+      <div style="flex: 1; background: #e6f7ff; padding: 16px;">主内容区</div>
+      <div style="width: 200px; background: #f6ffed; padding: 16px;">侧边栏</div>
+    </XtFlexBox>
+  </XtFlexBox>
+</template>
+```
+:::

package/docs/components/base/xt-grid-box.md

@@ -0,0 +1,303 @@
+## XtGridBox 网格布局组件
+
+基于 CSS Grid 实现的网格布局组件，提供强大的二维布局能力，支持响应式设计和灵活的配置选项。
+
+## 基本用法
+
+::: demo 基本用法
+```vue
+<template>
+  <XtGridBox :columns="3" gap="16px">
+    <div style="padding: 16px; background: #f0f0f0; border-radius: 8px;">项目1</div>
+    <div style="padding: 16px; background: #f0f0f0; border-radius: 8px;">项目2</div>
+    <div style="padding: 16px; background: #f0f0f0; border-radius: 8px;">项目3</div>
+    <div style="padding: 16px; background: #f0f0f0; border-radius: 8px;">项目4</div>
+    <div style="padding: 16px; background: #f0f0f0; border-radius: 8px;">项目5</div>
+    <div style="padding: 16px; background: #f0f0f0; border-radius: 8px;">项目6</div>
+  </XtGridBox>
+</template>
+```
+:::
+
+## 属性说明
+
+| 属性 | 类型 | 默认值 | 可选值 | 说明 |
+|------|------|--------|--------|------|
+| `columns` | String / Array / Number | `1fr` | - | 列配置，支持数字、字符串或数组 |
+| `rows` | String / Array | `auto` | - | 行配置 |
+| `gap` | String | - | - | 网格间距（同时控制行和列） |
+| `rowGap` | String | - | - | 行间距 |
+| `colGap` | String | - | - | 列间距 |
+| `flow` | String | `row` | `row`、`column`、`row dense`、`column dense` | 自动排列方向 |
+| `areas` | String / Array | - | - | 命名区域布局 |
+| `align` | String | `stretch` | `start`、`end`、`center`、`stretch`、`baseline` | 子项对齐方式 |
+| `justify` | String | `start` | `start`、`end`、`center`、`space-between`、`space-around`、`space-evenly`、`stretch` | 内容对齐方式 |
+| `responsive` | Object | `{}` | - | 响应式断点配置 |
+
+## XtGridItem 子项组件
+
+配合 XtGridBox 使用的子项组件，支持跨行跨列等高级布局。
+
+### 属性说明
+
+| 属性 | 类型 | 默认值 | 可选值 | 说明 |
+|------|------|--------|--------|------|
+| `span` | Number | `1` | >0 | 跨列数 |
+| `rowSpan` | Number | `1` | >0 | 跨行数 |
+| `start` | Number | `0` | >=0 | 起始列位置 |
+| `rowStart` | Number | `0` | >=0 | 起始行位置 |
+| `area` | String | - | - | 命名区域名称 |
+| `justifySelf` | String | `auto` | `auto`、`start`、`end`、`center`、`stretch` | 水平对齐 |
+| `alignSelf` | String | `auto` | `auto`、`start`、`end`、`center`、`stretch`、`baseline` | 垂直对齐 |
+
+## 示例
+
+### 基础网格
+
+::: demo 基础网格
+```vue
+<template>
+  <XtGridBox :columns="4" gap="12px">
+    <div v-for="i in 8" :key="i" style="padding: 12px; background: #e6f7ff; border-radius: 4px; text-align: center;">{{ i }}</div>
+  </XtGridBox>
+</template>
+```
+:::
+
+### 列配置方式
+
+::: demo 列配置方式
+```vue
+<template>
+  <div>
+    <!-- 数字方式：自动 repeat -->
+    <XtGridBox :columns="3" gap="8px" style="margin-bottom: 16px;">
+      <div v-for="i in 3" :key="i" style="padding: 12px; background: #f0f0f0;">{{ i }}</div>
+    </XtGridBox>
+    
+    <!-- 字符串方式 -->
+    <XtGridBox columns="200px 1fr 1fr" gap="8px" style="margin-bottom: 16px;">
+      <div style="padding: 12px; background: #e6f7ff;">固定宽度</div>
+      <div style="padding: 12px; background: #f6ffed;">弹性1</div>
+      <div style="padding: 12px; background: #fff7e6;">弹性2</div>
+    </XtGridBox>
+    
+    <!-- 数组方式 -->
+    <XtGridBox :columns="['100px', '1fr', '2fr']" gap="8px">
+      <div style="padding: 12px; background: #f9f0ff;">固定</div>
+      <div style="padding: 12px; background: #e6fffb;">1份</div>
+      <div style="padding: 12px; background: #fff7e6;">2份</div>
+    </XtGridBox>
+  </div>
+</template>
+```
+:::
+
+### 跨列跨行
+
+::: demo 跨列跨行
+```vue
+<template>
+  <XtGridBox :columns="4" gap="12px">
+    <XtGridItem :span="2" style="padding: 24px; background: #1890ff; color: white; border-radius: 8px;">跨2列</XtGridItem>
+    <XtGridItem style="padding: 24px; background: #52c41a; color: white; border-radius: 8px;">普通</XtGridItem>
+    <XtGridItem style="padding: 24px; background: #52c41a; color: white; border-radius: 8px;">普通</XtGridItem>
+    <XtGridItem :rowSpan="2" style="padding: 48px 16px; background: #faad14; color: white; border-radius: 8px;">跨2行</XtGridItem>
+    <XtGridItem style="padding: 24px; background: #f5222d; color: white; border-radius: 8px;">普通</XtGridItem>
+    <XtGridItem style="padding: 24px; background: #f5222d; color: white; border-radius: 8px;">普通</XtGridItem>
+    <XtGridItem style="padding: 24px; background: #f5222d; color: white; border-radius: 8px;">普通</XtGridItem>
+  </XtGridBox>
+</template>
+```
+:::
+
+### 命名区域布局
+
+::: demo 命名区域布局
+```vue
+<template>
+  <XtGridBox 
+    :areas="[
+      'header header header',
+      'sidebar main main',
+      'footer footer footer'
+    ]"
+    gap="12px"
+  >
+    <XtGridItem area="header" style="padding: 16px; background: #1890ff; color: white; border-radius: 8px;">Header</XtGridItem>
+    <XtGridItem area="sidebar" style="padding: 16px; background: #52c41a; color: white; border-radius: 8px;">Sidebar</XtGridItem>
+    <XtGridItem area="main" style="padding: 16px; background: #faad14; color: white; border-radius: 8px;">Main Content</XtGridItem>
+    <XtGridItem area="footer" style="padding: 16px; background: #f5222d; color: white; border-radius: 8px;">Footer</XtGridItem>
+  </XtGridBox>
+</template>
+```
+:::
+
+### 对齐方式
+
+::: demo 对齐方式
+```vue
+<template>
+  <div>
+    <!-- 子项居中对齐 -->
+    <XtGridBox :columns="3" gap="8px" align="center" style="height: 120px; background: #f0f0f0; margin-bottom: 16px;">
+      <div style="padding: 8px 16px; background: white;">居中</div>
+      <div style="padding: 8px 16px; background: white;">居中</div>
+      <div style="padding: 8px 16px; background: white;">居中</div>
+    </XtGridBox>
+    
+    <!-- 内容两端对齐 -->
+    <XtGridBox :columns="3" gap="8px" justify="space-between" style="background: #f0f0f0;">
+      <div style="padding: 8px 16px; background: white;">左</div>
+      <div style="padding: 8px 16px; background: white;">中</div>
+      <div style="padding: 8px 16px; background: white;">右</div>
+    </XtGridBox>
+  </div>
+</template>
+```
+:::
+
+### 独立间距控制
+
+::: demo 独立间距控制
+```vue
+<template>
+  <XtGridBox :columns="3" rowGap="24px" colGap="8px">
+    <div v-for="i in 6" :key="i" style="padding: 12px; background: #e6f7ff; text-align: center;">{{ i }}</div>
+  </XtGridBox>
+</template>
+```
+:::
+
+### 自动填充布局
+
+::: demo 自动填充布局
+```vue
+<template>
+  <XtGridBox columns="repeat(auto-fill, minmax(150px, 1fr))" gap="12px">
+    <div v-for="i in 8" :key="i" style="padding: 16px; background: #f0f0f0; text-align: center;">项目{{ i }}</div>
+  </XtGridBox>
+</template>
+```
+:::
+
+### 嵌套网格
+
+::: demo 嵌套网格
+```vue
+<template>
+  <XtGridBox :columns="2" gap="16px">
+    <!-- 左侧 -->
+    <div style="padding: 16px; background: #e6f7ff;">
+      <h4>左侧面板</h4>
+      <XtGridBox :columns="1" gap="8px">
+        <div style="padding: 8px; background: white;">子项1</div>
+        <div style="padding: 8px; background: white;">子项2</div>
+      </XtGridBox>
+    </div>
+    
+    <!-- 右侧 -->
+    <div style="padding: 16px; background: #f6ffed;">
+      <h4>右侧面板</h4>
+      <XtGridBox :columns="2" gap="8px">
+        <div style="padding: 8px; background: white;">A</div>
+        <div style="padding: 8px; background: white;">B</div>
+        <div style="padding: 8px; background: white;">C</div>
+        <div style="padding: 8px; background: white;">D</div>
+      </XtGridBox>
+    </div>
+  </XtGridBox>
+</template>
+```
+:::
+
+## 常见布局问题解决方案
+
+### 1. 网格内容溢出
+
+**问题**：当网格内容过多时，网格会超出容器边界
+
+**解决方案**：
+```vue
+<template>
+  <XtGridBox :columns="3" gap="12px" style="min-height: 0;">
+    <div style="overflow-y: auto; max-height: 200px;">
+      <!-- 大量内容 -->
+    </div>
+  </XtGridBox>
+</template>
+```
+
+### 2. 动态内容高度不一致
+
+**问题**：网格子项内容高度不同导致布局错乱
+
+**解决方案**：
+```vue
+<template>
+  <!-- 使用 align 属性强制对齐 -->
+  <XtGridBox :columns="3" gap="12px" align="stretch">
+    <div style="display: flex; flex-direction: column;">
+      <div style="flex: 1;">内容区域</div>
+      <div>固定底部</div>
+    </div>
+  </XtGridBox>
+</template>
+```
+
+### 3. 响应式列数调整
+
+**问题**：在不同屏幕尺寸下需要不同的列数
+
+**解决方案**：
+```vue
+<template>
+  <!-- 使用 CSS 类配合媒体查询 -->
+  <XtGridBox class="responsive-grid" gap="12px">
+    <div v-for="i in 6" :key="i" style="padding: 12px; background: #f0f0f0;">{{ i }}</div>
+  </XtGridBox>
+</template>
+
+<style>
+.responsive-grid {
+  grid-template-columns: repeat(1, 1fr);
+}
+
+@media (min-width: 576px) {
+  .responsive-grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+@media (min-width: 768px) {
+  .responsive-grid {
+    grid-template-columns: repeat(3, 1fr);
+  }
+}
+</style>
+```
+
+### 4. 网格项无法收缩
+
+**问题**：当父容器高度受限，子项无法自动收缩
+
+**解决方案**：
+```vue
+<template>
+  <div style="height: 300px; background: #f0f0f0;">
+    <XtGridBox :columns="2" style="height: 100%; min-height: 0;">
+      <div style="overflow-y: auto;">
+        <!-- 可滚动内容 -->
+      </div>
+      <div>固定内容</div>
+    </XtGridBox>
+  </div>
+</template>
+```
+
+## 注意事项
+
+1. **min-height: 0**：当网格作为子元素嵌套在其他布局中时，建议设置 `min-height: 0` 以确保正确的收缩行为
+2. **响应式设计**：建议配合 CSS 媒体查询实现响应式布局
+3. **性能优化**：对于大量网格项，考虑使用 `flow="dense"` 优化空间利用率
+4. **嵌套使用**：网格可以嵌套使用，但注意控制嵌套层级以避免性能问题