xt-element-ui 1.2.4 → 1.2.6

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. **嵌套使用**：网格可以嵌套使用，但注意控制嵌套层级以避免性能问题

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

@@ -0,0 +1,150 @@
+## XtInput 输入框组件
+
+输入框组件用于收集用户输入的信息。
+
+## 基本用法
+
+::: demo 基本用法
+```vue
+<template>
+  <XtInput v-model="inputValue" placeholder="请输入内容"></XtInput>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      inputValue: ''
+    }
+  }
+}
+</script>
+```
+:::
+
+## 属性说明
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `value` | String / Number | - | 输入值（支持 v-model） |
+| `placeholder` | String | '请输入内容' | 占位提示文本 |
+| `color` | String | - | 自定义聚焦颜色 |
+
+## 示例
+
+### 基础输入框
+::: demo 基础输入框
+```vue
+<template>
+  <XtInput v-model="username" placeholder="请输入用户名"></XtInput>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      username: ''
+    }
+  }
+}
+</script>
+```
+:::
+
+### 自定义占位符
+
+::: demo 自定义占位符
+```vue
+<template>
+  <XtInput v-model="email" placeholder="请输入您的邮箱地址"></XtInput>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      email: ''
+    }
+  }
+}
+</script>
+```
+:::
+
+### 自定义聚焦颜色
+::: demo 自定义聚焦颜色
+```vue
+<template>
+  <div style="display: flex; gap: 16px;">
+    <XtInput v-model="input1" placeholder="默认颜色"></XtInput>
+    <XtInput v-model="input2" placeholder="绿色主题" color="#52c41a"></XtInput>
+    <XtInput v-model="input3" placeholder="橙色主题" color="#faad14"></XtInput>
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      input1: '',
+      input2: '',
+      input3: ''
+    }
+  }
+}
+</script>
+```
+:::
+
+### 输入框组
+
+::: demo 输入框组
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px;">
+    <XtInput v-model="name" placeholder="姓名"></XtInput>
+    <XtInput v-model="phone" placeholder="手机"></XtInput>
+    <XtInput v-model="address" placeholder="地址"></XtInput>
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      name: '',
+      phone: '',
+      address: ''
+    }
+  }
+}
+</script>
+```
+:::
+
+### 监听输入事件
+
+::: demo 监听输入事件
+```vue
+<template>
+  <div>
+    <XtInput :value="inputValue" placeholder="实时监听输入" @input="handleInput"></XtInput>
+    <p style="margin-top: 12px;">输入长度: {{ inputValue.length }}</p>
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      inputValue: ''
+    }
+  },
+  methods: {
+    handleInput(value) {
+      this.inputValue = value
+    }
+  }
+}
+</script>
+```
+:::

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

@@ -0,0 +1,212 @@
+## XtText 文本组件
+
+文本组件用于展示不同样式的文本内容。
+
+## 基本用法
+
+::: demo 基本用法
+```vue
+<template>
+  <XtText type="primary">主要文本</XtText>
+</template>
+```
+:::
+
+## 属性说明
+| 属性 | 类型 | 默认值 | 可选值 | 说明 |
+|------|------|--------|--------|------|
+| `type` | String | - | `primary`、`success`、`warning`、`danger` | 文本颜色类型 |
+| `size` | String | base | `extra-large`、`large`、`medium`、`base`、`small`、`extra-small` | 字体大小 |
+| `bold` | Boolean | false | - | 是否加粗 |
+| `letterSpacing` | String / Number | - | - | 字间距 |
+| `money` | Boolean | false | - | 是否启用金额格式化 |
+| `value` | Number / String | - | - | 金额数值 |
+| `currency` | String | CNY | `CNY`、`USD`、`EUR`、`JPY`、`GBP`、`AUD`、`CAD` | 货币类型 |
+| `decimals` | Number | 2 | 0-10 | 小数位数 |
+| `locale` | String | zh-CN | - | 语言环境 |
+| `showSign` | Boolean | false | - | 是否显示正负号 |
+| `prefix` | String | - | - | 自定义前缀 |
+| `suffix` | String | - | - | 自定义后缀 |
+
+## 示例
+
+### 不同类型的文本
+::: demo 不同类型的文本
+```vue
+<template>
+  <div style="display: flex; gap: 16px;">
+    <XtText type="primary">主要文本</XtText>
+    <XtText type="success">成功文本</XtText>
+    <XtText type="warning">警告文本</XtText>
+    <XtText type="danger">危险文本</XtText>
+  </div>
+</template>
+```
+:::
+
+### 不同字体大小
+::: demo 不同字体大小
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <XtText size="extra-large">特大号文本</XtText>
+    <XtText size="large">大号文本</XtText>
+    <XtText size="medium">中号文本</XtText>
+    <XtText size="base">基准文本</XtText>
+    <XtText size="small">小号文本</XtText>
+    <XtText size="extra-small">特小号文本</XtText>
+  </div>
+</template>
+```
+:::
+
+### 加粗文本
+
+::: demo 加粗文本
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <XtText bold>普通加粗文本</XtText>
+    <XtText type="primary" bold>主要加粗文本</XtText>
+  </div>
+</template>
+```
+:::
+
+### 字间距
+::: demo 字间距
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <XtText>正常字间距</XtText>
+    <XtText :letterSpacing="4">宽字距文本</XtText>
+    <XtText letterSpacing="8px">更宽字距文本</XtText>
+  </div>
+</template>
+```
+:::
+
+### 组合使用
+
+::: demo 组合使用
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <XtText type="success" bold>成功加粗文本</XtText>
+    <XtText type="danger" :letterSpacing="2">危险宽字距文本</XtText>
+    <XtText type="warning" bold :letterSpacing="3">警告加粗宽字距</XtText>
+  </div>
+</template>
+```
+:::
+
+### 段落文本
+
+::: demo 段落文本
+```vue
+<template>
+  <p>
+    这是一段普通文本，其中包含
+    <XtText type="primary">高亮的主要文本</XtText>
+    和
+    <XtText type="danger">危险提示文本</XtText>。
+  </p>
+</template>
+```
+:::
+
+### 数据展示
+
+::: demo 数据展示
+```vue
+<template>
+  <div style="display: flex; align-items: baseline; gap: 8px;">
+    <XtText type="primary" bold style="font-size: 24px;">¥1,234.56</XtText>
+    <XtText type="warning" :letterSpacing="1">本月已节省¥520</XtText>
+  </div>
+</template>
+```
+:::
+
+### 金额格式化
+::: demo 金额格式化
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px;">
+    <div>
+      <span style="color: #909399; margin-right: 16px;">人民币：</span>
+      <XtText money :value="123456.78" type="primary" bold></XtText>
+    </div>
+    <div>
+      <span style="color: #909399; margin-right: 16px;">美元：</span>
+      <XtText money :value="123456.78" currency="USD"></XtText>
+    </div>
+    <div>
+      <span style="color: #909399; margin-right: 16px;">欧元：</span>
+      <XtText money :value="123456.78" currency="EUR" locale="de-DE"></XtText>
+    </div>
+    <div>
+      <span style="color: #909399; margin-right: 16px;">日元：</span>
+      <XtText money :value="123456" currency="JPY" :decimals="0"></XtText>
+    </div>
+  </div>
+</template>
+```
+:::
+
+### 金额显示正负号
+::: demo 金额显示正负号
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <div>
+      <span style="color: #909399; margin-right: 16px;">收入：</span>
+      <XtText money :value="5000" showSign type="success"></XtText>
+    </div>
+    <div>
+      <span style="color: #909399; margin-right: 16px;">支出：</span>
+      <XtText money :value="-2300" showSign type="danger"></XtText>
+    </div>
+  </div>
+</template>
+```
+:::
+
+### 自定义前缀后缀
+
+::: demo 自定义前缀后缀
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 8px;">
+    <div>
+      <XtText money :value="1000" prefix="合计：" suffix=" 元整" type="primary"></XtText>
+    </div>
+    <div>
+      <XtText money :value="98.5" prefix="折扣价：" type="warning"></XtText>
+    </div>
+  </div>
+</template>
+```
+:::
+
+### 金额样式组合
+
+::: demo 金额样式组合
+```vue
+<template>
+  <div style="display: flex; flex-direction: column; gap: 12px;">
+    <div style="font-size: 28px;">
+      <XtText money :value="1234567.89" type="primary" bold></XtText>
+    </div>
+    <div>
+      <span style="color: #909399;">今日收益：</span>
+      <XtText money :value="1258.67" showSign type="success"></XtText>
+    </div>
+    <div>
+      <span style="color: #909399;">累计支出：</span>
+      <XtText money :value="-8920.30" showSign type="danger"></XtText>
+    </div>
+  </div>
+</template>
+```
+:::