vue3-smart-table 1.0.0 → 1.0.3

package/README.md

@@ -181,7 +181,6 @@ src/
 │  ├─ renderer.ts            # 渲染器管理器
 │  ├─ config.ts              # 全局配置管理
 │  ├─ utils/                 # 内部工具函数
-│  ├─ styles/                # 组件样式
 │  ├─ types.ts               # 类型定义
 │  └─ index.vue              # SmartTable 主组件
 ├─ types/                    # 类型工具（对外提供）
@@ -231,7 +230,7 @@ const loading = ref(false)
 
 ---
 
-## 新特性 (v1.0.0)
+
 
 ### 1. 插件化架构
 
@@ -266,9 +265,6 @@ setSmartTableConfig({
     page: 1,
     size: 20
   },
-  theme: {
-    primaryColor: '#409EFF'
-  },
   renderers: {
     // 全局注册自定义渲染器
     'custom-renderer': MyRendererComponent
@@ -359,771 +355,771 @@ export interface ButtonConfig<R = any> {
 
 ---
 
-## 4. 内置渲染器完整指南
-
-SmartTable 提供 13 种内置渲染器，按功能分为 4 类：
-
-- **📝 展示型** (7种)：html、copy、img、dict、map、formatter、icon
-- **✏️ 编辑型** (3种)：input、input-number、select
-- **🔘 操作型** (2种)：button、link
-- **🔧 扩展型** (1种)：slot
-
-### 快速查找表
-
-| 渲染器 | 类型 | 配置复杂度 | 支持事件 |
-|--------|------|-----------|---------|
-| `html` | 展示 | ⭐ | ❌ |
-| `copy` | 展示 | ⭐⭐ | ❌ |
-| `img` | 展示 | ⭐⭐ | ❌ |
-| `dict` | 展示 | ⭐⭐⭐ | ❌ |
-| `map` | 展示 | ⭐⭐ | ❌ |
-| `formatter` | 展示 | ⭐⭐ | ❌ |
-| `icon` | 展示 | ⭐⭐ | ❌ |
-| `input` | 编辑 | ⭐⭐ | ✅ |
-| `input-number` | 编辑 | ⭐⭐ | ✅ |
-| `select` | 编辑 | ⭐⭐ | ✅ |
-| `button` | 操作 | ⭐ | ✅ |
-| `link` | 操作 | ⭐ | ✅ |
-| `slot` | 扩展 | ⭐⭐⭐⭐ | ❌ |
-
----
-
-### 📝 展示型渲染器
-
-用于数据展示，不涉及用户交互。
-
-#### 1. `html` - HTML 内容渲染
-
-**功能**：渲染 HTML 内容，支持多行文本截断（最多 2 行）。
-
-**配置**：
-```typescript
-{
-  key: 'description',
-  label: '描述',
-  render: 'html',
-  renderProps: {
-    style?: string   // 自定义样式
-    class?: string   // 自定义类名
-  }
-}
-```
-
-**示例**：
-```typescript
-const columns = [
-  {
-    key: 'content',
-    label: '商品描述',
-    render: 'html'
-  }
-]
-
-const tableData = [
-  {
-    content: '<p>这是一段<strong>加粗</strong>的文本</p>'
-  }
-]
-```
-
-**效果**：
-- 自动截断为 2 行
-- 支持富文本 HTML
-- 超出部分显示省略号
-
----
-
-#### 2. `copy` - 可复制文本
-
-**功能**：hover 显示复制按钮，点击复制文本到剪贴板。
-
-**配置**：
-```typescript
-{
-  key: 'code',
-  label: '编号',
-  render: 'copy',
-  renderProps: {
-    iconColor?: string        // 图标颜色，默认 '#409EFF'
-    copyTitle?: string        // 复制提示文本，默认 '复制'
-    successText?: string      // 成功提示，默认 '复制成功'
-    errorText?: string        // 失败提示，默认 '复制失败'
-  }
-}
-```
-
-**示例**：
-```typescript
-const columns = [
-  {
-    key: 'orderNo',
-    label: '订单号',
-    render: 'copy',
-    renderProps: {
-      iconColor: '#67C23A',
-      successText: '订单号已复制',
-      errorText: '复制失败，请重试'
-    }
-  }
-]
-```
-
-**效果**：
-- hover 显示复制按钮图标
-- 点击自动复制到剪贴板
-- 使用 ElMessage 提示结果
-- 支持单行文本截断
-
----
-
-#### 3. `img` - 图片预览
-
-**功能**：图片展示，支持单图/多图预览。
-
-**配置**：
-```typescript
-{
-  key: 'avatar',
-  label: '头像',
-  render: 'img',
-  renderProps: {
-    width?: string | number           // 图片宽度，默认 '80px'
-    height?: string | number          // 图片高度，默认 '80px'
-    fit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'  // 适应方式
-    previewSrcList?: string[]         // 预览图片列表（可选）
-    placeholder?: string              // 无图片时的占位文本
-    style?: string                    // 自定义样式
-  }
-}
-```
-
-**示例 - 单图**：
-```typescript
-const columns = [
-  {
-    key: 'avatar',
-    label: '头像',
-    render: 'img',
-    renderProps: {
-      width: '60px',
-      height: '60px',
-      fit: 'cover'
-    }
-  }
-]
-
-const tableData = [
-  { avatar: 'https://example.com/avatar.jpg' }
-]
-```
-
-**示例 - 多图**：
-```typescript
-const columns = [
-  {
-    key: 'gallery',
-    label: '相册',
-    render: 'img',
-    renderProps: {
-      width: '80px',
-      height: '80px'
-    }
-  }
-]
-
-const tableData = [
-  {
-    gallery: [
-      'https://example.com/img1.jpg',
-      'https://example.com/img2.jpg',
-      'https://example.com/img3.jpg'
-    ]
-  }
-]
-```
-
-**效果**：
-- **单图**：直接显示，点击预览
-- **多图**：显示第一张 + 数量标记（如：+2），点击预览全部
-- 支持 Element Plus Image 的所有预览功能
-- 无图片时显示占位符或空内容
-
----
-
-#### 4. `dict` - 字典标签映射
-
-**功能**：将值映射为标签显示（使用 ElTag）。
-
-**配置**：
-```typescript
-{
-  key: 'status',
-  label: '状态',
-  render: 'dict',
-  renderProps: {
-    options: Array<{           // 字典配置（必需）
-      label: string            // 显示文本
-      value: any               // 值
-      listClass?: string       // ElTag 类型：'primary' | 'success' | 'warning' | 'danger' | 'info'
-      cssClass?: string        // 自定义类名
-    }>
-    showValue?: boolean        // 是否显示未匹配的值，默认 false
-  }
-}
-```
-
-**示例 - 单值**：
-```typescript
-const columns = [
-  {
-    key: 'status',
-    label: '状态',
-    render: 'dict',
-    renderProps: {
-      options: [
-        { label: '启用', value: 1, listClass: 'success' },
-        { label: '禁用', value: 0, listClass: 'danger' },
-        { label: '审核中', value: 2, listClass: 'warning' }
-      ]
-    }
-  }
-]
-
-const tableData = [
-  { status: 1 }  // 显示：[启用]
-]
-```
-
-**示例 - 多值**：
-```typescript
-const columns = [
-  {
-    key: 'tags',
-    label: '标签',
-    render: 'dict',
-    renderProps: {
-      options: [
-        { label: '重要', value: 'important', listClass: 'danger' },
-        { label: '紧急', value: 'urgent', listClass: 'warning' }
-      ],
-      showValue: true  // 显示未匹配的值
-    }
-  }
-]
-
-const tableData = [
-  { tags: ['important', 'urgent'] }  // 显示：[重要] [紧急]
-]
-```
-
-**效果**：
-- 单值映射为单个标签
-- 多值映射为多个标签
-- 未匹配的值根据 `showValue` 决定是否显示
-- 支持自定义标签颜色和样式
-
----
-
-#### 5. `map` - 键值映射
-
-**功能**：简单的 key-value 映射。
-
-**配置**：
-```typescript
-{
-  key: 'gender',
-  label: '性别',
-  render: 'map',
-  renderProps: {
-    options: Record<string | number, any>  // 映射配置（必需）
-  }
-}
-```
-
-**示例**：
-```typescript
-const columns = [
-  {
-    key: 'gender',
-    label: '性别',
-    render: 'map',
-    renderProps: {
-      options: {
-        1: '男',
-        2: '女',
-        0: '未知'
-      }
-    }
-  }
-]
-
-const tableData = [
-  { gender: 1 },  // 显示：男
-  { gender: 2 },  // 显示：女
-  { gender: 99 }  // 显示：(空)
-]
-```
-
-**效果**：
-- 根据值映射显示对应文本
-- 未匹配的值显示空字符串
-- 比 `dict` 更简单，适合不需要标签样式的场景
-
----
-
-#### 6. `formatter` - 自定义格式化
-
-**功能**：使用自定义函数格式化显示。
-
-**配置**：
-```typescript
-{
-  key: 'price',
-  label: '价格',
-  render: 'formatter',
-  formatter: (value: any, row: any) => string  // 格式化函数
-}
-```
-
-**示例**：
-```typescript
-const columns = [
-  {
-    key: 'price',
-    label: '价格',
-    render: 'formatter',
-    formatter: (value, row) => {
-      return `¥${Number(value).toFixed(2)}`
-    }
-  },
-  {
-    key: 'date',
-    label: '日期',
-    render: 'formatter',
-    formatter: (value) => {
-      return new Date(value).toLocaleDateString('zh-CN')
-    }
-  }
-]
-
-const tableData = [
-  { price: 99.9, date: '2024-01-01' }
-]
-```
-
-**效果**：
-- 完全自定义格式化逻辑
-- 可以访问当前行数据
-- 适合复杂的格式化需求
-
----
-
-#### 7. `icon` - 图标渲染
-
-**功能**：支持多种图标格式。
-
-**配置**：
-```typescript
-{
-  key: 'icon',
-  label: '图标',
-  render: 'icon',
-  renderProps: {
-    style?: string  // 自定义样式
-    size?: number   // 图标大小（像素）
-    class?: string  // 自定义类名
-  }
-}
-```
-
-**示例**：
-```typescript
-const columns = [
-  {
-    key: 'avatarIcon',
-    label: '头像',
-    render: 'icon',
-    renderProps: {
-      style: 'font-size: 32px; color: #409EFF'
-    }
-  }
-]
-
-const tableData = [
-  // 1. 网络图片
-  { icon: 'https://example.com/icon.png' },
-
-  // 2. SVG 源码
-  { icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024">...</svg>' },
-
-  // 3. iconfont 类名
-  { icon: 'iconfont icon-user' }
-]
-```
-
-**效果**：
-- 自动识别图标类型
-- 网络图片：显示为 ElImage
-- SVG：直接渲染
-- iconfont：应用类名样式
-
----
-
-### ✏️ 编辑型渲染器
-
-支持单元格编辑，触发 `cellChange`、`cellBlur`、`cellEnter` 事件。
-
-#### 8. `input` - 可编辑输入框
-
-**配置**：
-```typescript
-{
-  key: 'username',
-  label: '用户名',
-  render: 'input',
-  renderProps: {
-    placeholder?: string   // 占位文本，默认 ''
-    size?: 'large' | 'default' | 'small'  // 尺寸，默认 'small'
-    clearable?: boolean   // 是否可清空，默认 true
-    // ... 其他 ElInput 属性
-  }
-}
-```
-
-**示例**：
-```typescript
-const columns = [
-  {
-    key: 'username',
-    label: '用户名',
-    render: 'input',
-    renderProps: {
-      placeholder: '请输入用户名',
-      clearable: true
-    }
-  }
-]
-```
-
-**事件处理**：
-```vue
-<script setup>
-const handleCellChange = (row, col) => {
-  console.log('值已修改:', row[col.key])
-}
-
-const handleCellBlur = (row, col) => {
-  console.log('失去焦点')
-}
-
-const handleCellEnter = (row, col) => {
-  console.log('回车确认')
-}
-</script>
-
-<template>
-  <SmartTable
-    :columns="columns"
-    :data="tableData"
-    @cellChange="handleCellChange"
-    @cellBlur="handleCellBlur"
-    @cellEnter="handleCellEnter"
-  />
-</template>
-```
-
----
-
-#### 9. `input-number` - 可编辑数字输入框
-
-**配置**：
-```typescript
-{
-  key: 'age',
-  label: '年龄',
-  render: 'input-number',
-  renderProps: {
-    min?: number          // 最小值
-    max?: number          // 最大值
-    step?: number         // 步长
-    precision?: number    // 精度
-    size?: 'large' | 'default' | 'small'
-    controls?: boolean    // 是否显示增减按钮
-    // ... 其他 ElInputNumber 属性
-  }
-}
-```
-
-**示例**：
-```typescript
-const columns = [
-  {
-    key: 'orderNum',
-    label: '序号',
-    render: 'input-number',
-    renderProps: {
-      min: 0,
-      max: 100,
-      step: 1,
-      controls: false  // 隐藏增减按钮
-    }
-  }
-]
-```
-
----
-
-#### 10. `select` - 可编辑下拉选择
-
-**配置**：
-```typescript
-{
-  key: 'status',
-  label: '状态',
-  render: 'select',
-  renderProps: {
-    options: Array<{           // 选项配置（必需）
-      label: string
-      value: any
-    }>
-    placeholder?: string       // 占位文本，默认 '请选择'
-    size?: 'large' | 'default' | 'small'
-    clearable?: boolean        // 是否可清空
-    // ... 其他 ElSelect 属性
-  }
-}
-```
-
-**示例**：
-```typescript
-const columns = [
-  {
-    key: 'role',
-    label: '角色',
-    render: 'select',
-    renderProps: {
-      placeholder: '请选择角色',
-      clearable: true,
-      options: [
-        { label: '管理员', value: 'admin' },
-        { label: '普通用户', value: 'user' },
-        { label: '访客', value: 'guest' }
-      ]
-    }
-  }
-]
-```
-
----
-
-### 🔘 操作型渲染器
-
-用于触发操作或跳转。
-
-#### 11. `button` - 操作按钮
-
-**配置**：
-```typescript
-{
-  key: 'action',
-  label: '操作',
-  render: 'button',
-  renderProps: {
-    label?: string        // 按钮文本
-    type?: 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'text'
-    size?: 'large' | 'default' | 'small'
-    disabled?: boolean
-    // ... 其他 ElButton 属性
-  }
-}
-```
-
-**示例**：
-```typescript
-const columns = [
-  {
-    key: 'edit',
-    label: '编辑',
-    render: 'button',
-    renderProps: {
-      label: '编辑',
-      type: 'primary',
-      size: 'small'
-    }
-  }
-]
-```
-
-**事件处理**：
-```vue
-<script setup>
-const handleCellClick = (row, col) => {
-  if (col.key === 'edit') {
-    console.log('编辑行:', row)
-  }
-}
-</script>
-
-<template>
-  <SmartTable
-    :columns="columns"
-    :data="tableData"
-    @cellClick="handleCellClick"
-  />
-</template>
-```
-
----
-
-#### 12. `link` - 链接
-
-**配置**：
-```typescript
-{
-  key: 'detail',
-  label: '详情',
-  render: 'link',
-  renderProps: {
-    label?: string        // 链接文本
-    href: string          // 链接地址（必需）
-    blank?: boolean       // 是否新窗口打开，默认 false
-    style?: string        // 自定义样式
-  }
-}
-```
-
-**示例**：
-```typescript
-const columns = [
-  {
-    key: 'url',
-    label: '查看',
-    render: 'link',
-    renderProps: {
-      label: '查看详情',
-      href: 'https://example.com',
-      blank: true,
-      style: 'color: #409EFF'
-    }
-  }
-]
-```
-
----
-
-### 🔧 扩展型渲染器
-
-用于自定义复杂场景。
-
-#### 13. `slot` - 自定义插槽
-
-**功能**：使用 Vue 插槽完全自定义列内容。
-
-**配置**：
-```typescript
-{
-  key: 'attachments',
-  label: '附件',
-  render: 'slot',
-  slot?: string  // 插槽名称，默认使用 key
-}
-```
-
-**示例**：
-```vue
-<script setup>
-const columns = [
-  {
-    key: 'attachments',
-    label: '附件列表',
-    render: 'slot',
-    slot: 'attachments'
-  }
-]
-
-const tableData = ref([
-  {
-    id: 1,
-    attachments: [
-      { name: 'file1.pdf', url: '/files/file1.pdf' },
-      { name: 'file2.jpg', url: '/files/file2.jpg' }
-    ]
-  }
-])
-
-const download = (url) => {
-  console.log('下载:', url)
-}
-</script>
-
-<template>
-  <SmartTable :columns="columns" :data="tableData">
-    <template #attachments="{ row }">
-      <div v-for="(file, index) in row.attachments" :key="index">
-        <el-button type="text" @click="download(file.url)">
-          {{ file.name }}
-        </el-button>
-      </div>
-    </template>
-  </SmartTable>
-</template>
-```
-
-**效果**：
-- 完全自定义列内容
-- 访问完整的行数据
-- 可以包含复杂的交互逻辑
-
----
-
-### TypeScript 类型支持
-
-所有渲染器的 `renderProps` 都有完整的 TypeScript 类型定义：
-
-```typescript
-import type { ColumnConfig, RendererPropsMap } from 'vue3-smart-table'
-
-// 类型安全
-const column: ColumnConfig = {
-  key: 'status',
-  label: '状态',
-  render: 'dict',
-  renderProps: {
-    options: [  // ✅ 类型提示和检查
-      { label: '启用', value: 1 }
-    ]
-  }
-}
-
-// 提取特定渲染器的 props 类型
-type DictProps = RendererPropsMap['dict']
-const dictConfig: DictProps = {
-  options: [],
-  showValue: true
-}
-```
-
----
-
-### 最佳实践
-
-1. **选择合适的渲染器**
-   - 简单映射 → `map`
-   - 需要标签样式 → `dict`
-   - 复杂逻辑 → `formatter`
-   - 自定义内容 → `slot`
-
-2. **性能优化**
-   - 大量数据时避免 `formatter`，使用 `map` 或 `dict`
-   - 复杂自定义内容优先使用 `slot`
-
-3. **用户体验**
-   - 图片显示添加 `placeholder`
-   - 复制功能添加友好的提示文本
-   - 编辑单元格添加合适的 `placeholder`
-
----
-
+## 4. 内置渲染器完整指南
+
+SmartTable 提供 13 种内置渲染器，按功能分为 4 类：
+
+- **📝 展示型** (7种)：html、copy、img、dict、map、formatter、icon
+- **✏️ 编辑型** (3种)：input、input-number、select
+- **🔘 操作型** (2种)：button、link
+- **🔧 扩展型** (1种)：slot
+
+### 快速查找表
+
+| 渲染器 | 类型 | 配置复杂度 | 支持事件 |
+|--------|------|-----------|---------|
+| `html` | 展示 | ⭐ | ❌ |
+| `copy` | 展示 | ⭐⭐ | ❌ |
+| `img` | 展示 | ⭐⭐ | ❌ |
+| `dict` | 展示 | ⭐⭐⭐ | ❌ |
+| `map` | 展示 | ⭐⭐ | ❌ |
+| `formatter` | 展示 | ⭐⭐ | ❌ |
+| `icon` | 展示 | ⭐⭐ | ❌ |
+| `input` | 编辑 | ⭐⭐ | ✅ |
+| `input-number` | 编辑 | ⭐⭐ | ✅ |
+| `select` | 编辑 | ⭐⭐ | ✅ |
+| `button` | 操作 | ⭐ | ✅ |
+| `link` | 操作 | ⭐ | ✅ |
+| `slot` | 扩展 | ⭐⭐⭐⭐ | ❌ |
+
+---
+
+### 📝 展示型渲染器
+
+用于数据展示，不涉及用户交互。
+
+#### 1. `html` - HTML 内容渲染
+
+**功能**：渲染 HTML 内容，支持多行文本截断（最多 2 行）。
+
+**配置**：
+```typescript
+{
+  key: 'description',
+  label: '描述',
+  render: 'html',
+  renderProps: {
+    style?: string   // 自定义样式
+    class?: string   // 自定义类名
+  }
+}
+```
+
+**示例**：
+```typescript
+const columns = [
+  {
+    key: 'content',
+    label: '商品描述',
+    render: 'html'
+  }
+]
+
+const tableData = [
+  {
+    content: '<p>这是一段<strong>加粗</strong>的文本</p>'
+  }
+]
+```
+
+**效果**：
+- 自动截断为 2 行
+- 支持富文本 HTML
+- 超出部分显示省略号
+
+---
+
+#### 2. `copy` - 可复制文本
+
+**功能**：hover 显示复制按钮，点击复制文本到剪贴板。
+
+**配置**：
+```typescript
+{
+  key: 'code',
+  label: '编号',
+  render: 'copy',
+  renderProps: {
+    iconColor?: string        // 图标颜色，默认 '#409EFF'
+    copyTitle?: string        // 复制提示文本，默认 '复制'
+    successText?: string      // 成功提示，默认 '复制成功'
+    errorText?: string        // 失败提示，默认 '复制失败'
+  }
+}
+```
+
+**示例**：
+```typescript
+const columns = [
+  {
+    key: 'orderNo',
+    label: '订单号',
+    render: 'copy',
+    renderProps: {
+      iconColor: '#67C23A',
+      successText: '订单号已复制',
+      errorText: '复制失败，请重试'
+    }
+  }
+]
+```
+
+**效果**：
+- hover 显示复制按钮图标
+- 点击自动复制到剪贴板
+- 使用 ElMessage 提示结果
+- 支持单行文本截断
+
+---
+
+#### 3. `img` - 图片预览
+
+**功能**：图片展示，支持单图/多图预览。
+
+**配置**：
+```typescript
+{
+  key: 'avatar',
+  label: '头像',
+  render: 'img',
+  renderProps: {
+    width?: string | number           // 图片宽度，默认 '80px'
+    height?: string | number          // 图片高度，默认 '80px'
+    fit?: 'contain' | 'cover' | 'fill' | 'none' | 'scale-down'  // 适应方式
+    previewSrcList?: string[]         // 预览图片列表（可选）
+    placeholder?: string              // 无图片时的占位文本
+    style?: string                    // 自定义样式
+  }
+}
+```
+
+**示例 - 单图**：
+```typescript
+const columns = [
+  {
+    key: 'avatar',
+    label: '头像',
+    render: 'img',
+    renderProps: {
+      width: '60px',
+      height: '60px',
+      fit: 'cover'
+    }
+  }
+]
+
+const tableData = [
+  { avatar: 'https://example.com/avatar.jpg' }
+]
+```
+
+**示例 - 多图**：
+```typescript
+const columns = [
+  {
+    key: 'gallery',
+    label: '相册',
+    render: 'img',
+    renderProps: {
+      width: '80px',
+      height: '80px'
+    }
+  }
+]
+
+const tableData = [
+  {
+    gallery: [
+      'https://example.com/img1.jpg',
+      'https://example.com/img2.jpg',
+      'https://example.com/img3.jpg'
+    ]
+  }
+]
+```
+
+**效果**：
+- **单图**：直接显示，点击预览
+- **多图**：显示第一张 + 数量标记（如：+2），点击预览全部
+- 支持 Element Plus Image 的所有预览功能
+- 无图片时显示占位符或空内容
+
+---
+
+#### 4. `dict` - 字典标签映射
+
+**功能**：将值映射为标签显示（使用 ElTag）。
+
+**配置**：
+```typescript
+{
+  key: 'status',
+  label: '状态',
+  render: 'dict',
+  renderProps: {
+    options: Array<{           // 字典配置（必需）
+      label: string            // 显示文本
+      value: any               // 值
+      listClass?: string       // ElTag 类型：'primary' | 'success' | 'warning' | 'danger' | 'info'
+      cssClass?: string        // 自定义类名
+    }>
+    showValue?: boolean        // 是否显示未匹配的值，默认 false
+  }
+}
+```
+
+**示例 - 单值**：
+```typescript
+const columns = [
+  {
+    key: 'status',
+    label: '状态',
+    render: 'dict',
+    renderProps: {
+      options: [
+        { label: '启用', value: 1, listClass: 'success' },
+        { label: '禁用', value: 0, listClass: 'danger' },
+        { label: '审核中', value: 2, listClass: 'warning' }
+      ]
+    }
+  }
+]
+
+const tableData = [
+  { status: 1 }  // 显示：[启用]
+]
+```
+
+**示例 - 多值**：
+```typescript
+const columns = [
+  {
+    key: 'tags',
+    label: '标签',
+    render: 'dict',
+    renderProps: {
+      options: [
+        { label: '重要', value: 'important', listClass: 'danger' },
+        { label: '紧急', value: 'urgent', listClass: 'warning' }
+      ],
+      showValue: true  // 显示未匹配的值
+    }
+  }
+]
+
+const tableData = [
+  { tags: ['important', 'urgent'] }  // 显示：[重要] [紧急]
+]
+```
+
+**效果**：
+- 单值映射为单个标签
+- 多值映射为多个标签
+- 未匹配的值根据 `showValue` 决定是否显示
+- 支持自定义标签颜色和样式
+
+---
+
+#### 5. `map` - 键值映射
+
+**功能**：简单的 key-value 映射。
+
+**配置**：
+```typescript
+{
+  key: 'gender',
+  label: '性别',
+  render: 'map',
+  renderProps: {
+    options: Record<string | number, any>  // 映射配置（必需）
+  }
+}
+```
+
+**示例**：
+```typescript
+const columns = [
+  {
+    key: 'gender',
+    label: '性别',
+    render: 'map',
+    renderProps: {
+      options: {
+        1: '男',
+        2: '女',
+        0: '未知'
+      }
+    }
+  }
+]
+
+const tableData = [
+  { gender: 1 },  // 显示：男
+  { gender: 2 },  // 显示：女
+  { gender: 99 }  // 显示：(空)
+]
+```
+
+**效果**：
+- 根据值映射显示对应文本
+- 未匹配的值显示空字符串
+- 比 `dict` 更简单，适合不需要标签样式的场景
+
+---
+
+#### 6. `formatter` - 自定义格式化
+
+**功能**：使用自定义函数格式化显示。
+
+**配置**：
+```typescript
+{
+  key: 'price',
+  label: '价格',
+  render: 'formatter',
+  formatter: (value: any, row: any) => string  // 格式化函数
+}
+```
+
+**示例**：
+```typescript
+const columns = [
+  {
+    key: 'price',
+    label: '价格',
+    render: 'formatter',
+    formatter: (value, row) => {
+      return `¥${Number(value).toFixed(2)}`
+    }
+  },
+  {
+    key: 'date',
+    label: '日期',
+    render: 'formatter',
+    formatter: (value) => {
+      return new Date(value).toLocaleDateString('zh-CN')
+    }
+  }
+]
+
+const tableData = [
+  { price: 99.9, date: '2024-01-01' }
+]
+```
+
+**效果**：
+- 完全自定义格式化逻辑
+- 可以访问当前行数据
+- 适合复杂的格式化需求
+
+---
+
+#### 7. `icon` - 图标渲染
+
+**功能**：支持多种图标格式。
+
+**配置**：
+```typescript
+{
+  key: 'icon',
+  label: '图标',
+  render: 'icon',
+  renderProps: {
+    style?: string  // 自定义样式
+    size?: number   // 图标大小（像素）
+    class?: string  // 自定义类名
+  }
+}
+```
+
+**示例**：
+```typescript
+const columns = [
+  {
+    key: 'avatarIcon',
+    label: '头像',
+    render: 'icon',
+    renderProps: {
+      style: 'font-size: 32px; color: #409EFF'
+    }
+  }
+]
+
+const tableData = [
+  // 1. 网络图片
+  { icon: 'https://example.com/icon.png' },
+
+  // 2. SVG 源码
+  { icon: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024">...</svg>' },
+
+  // 3. iconfont 类名
+  { icon: 'iconfont icon-user' }
+]
+```
+
+**效果**：
+- 自动识别图标类型
+- 网络图片：显示为 ElImage
+- SVG：直接渲染
+- iconfont：应用类名样式
+
+---
+
+### ✏️ 编辑型渲染器
+
+支持单元格编辑，触发 `cellChange`、`cellBlur`、`cellEnter` 事件。
+
+#### 8. `input` - 可编辑输入框
+
+**配置**：
+```typescript
+{
+  key: 'username',
+  label: '用户名',
+  render: 'input',
+  renderProps: {
+    placeholder?: string   // 占位文本，默认 ''
+    size?: 'large' | 'default' | 'small'  // 尺寸，默认 'small'
+    clearable?: boolean   // 是否可清空，默认 true
+    // ... 其他 ElInput 属性
+  }
+}
+```
+
+**示例**：
+```typescript
+const columns = [
+  {
+    key: 'username',
+    label: '用户名',
+    render: 'input',
+    renderProps: {
+      placeholder: '请输入用户名',
+      clearable: true
+    }
+  }
+]
+```
+
+**事件处理**：
+```vue
+<script setup>
+const handleCellChange = (row, col) => {
+  console.log('值已修改:', row[col.key])
+}
+
+const handleCellBlur = (row, col) => {
+  console.log('失去焦点')
+}
+
+const handleCellEnter = (row, col) => {
+  console.log('回车确认')
+}
+</script>
+
+<template>
+  <SmartTable
+    :columns="columns"
+    :data="tableData"
+    @cellChange="handleCellChange"
+    @cellBlur="handleCellBlur"
+    @cellEnter="handleCellEnter"
+  />
+</template>
+```
+
+---
+
+#### 9. `input-number` - 可编辑数字输入框
+
+**配置**：
+```typescript
+{
+  key: 'age',
+  label: '年龄',
+  render: 'input-number',
+  renderProps: {
+    min?: number          // 最小值
+    max?: number          // 最大值
+    step?: number         // 步长
+    precision?: number    // 精度
+    size?: 'large' | 'default' | 'small'
+    controls?: boolean    // 是否显示增减按钮
+    // ... 其他 ElInputNumber 属性
+  }
+}
+```
+
+**示例**：
+```typescript
+const columns = [
+  {
+    key: 'orderNum',
+    label: '序号',
+    render: 'input-number',
+    renderProps: {
+      min: 0,
+      max: 100,
+      step: 1,
+      controls: false  // 隐藏增减按钮
+    }
+  }
+]
+```
+
+---
+
+#### 10. `select` - 可编辑下拉选择
+
+**配置**：
+```typescript
+{
+  key: 'status',
+  label: '状态',
+  render: 'select',
+  renderProps: {
+    options: Array<{           // 选项配置（必需）
+      label: string
+      value: any
+    }>
+    placeholder?: string       // 占位文本，默认 '请选择'
+    size?: 'large' | 'default' | 'small'
+    clearable?: boolean        // 是否可清空
+    // ... 其他 ElSelect 属性
+  }
+}
+```
+
+**示例**：
+```typescript
+const columns = [
+  {
+    key: 'role',
+    label: '角色',
+    render: 'select',
+    renderProps: {
+      placeholder: '请选择角色',
+      clearable: true,
+      options: [
+        { label: '管理员', value: 'admin' },
+        { label: '普通用户', value: 'user' },
+        { label: '访客', value: 'guest' }
+      ]
+    }
+  }
+]
+```
+
+---
+
+### 🔘 操作型渲染器
+
+用于触发操作或跳转。
+
+#### 11. `button` - 操作按钮
+
+**配置**：
+```typescript
+{
+  key: 'action',
+  label: '操作',
+  render: 'button',
+  renderProps: {
+    label?: string        // 按钮文本
+    type?: 'primary' | 'success' | 'warning' | 'danger' | 'info' | 'text'
+    size?: 'large' | 'default' | 'small'
+    disabled?: boolean
+    // ... 其他 ElButton 属性
+  }
+}
+```
+
+**示例**：
+```typescript
+const columns = [
+  {
+    key: 'edit',
+    label: '编辑',
+    render: 'button',
+    renderProps: {
+      label: '编辑',
+      type: 'primary',
+      size: 'small'
+    }
+  }
+]
+```
+
+**事件处理**：
+```vue
+<script setup>
+const handleCellClick = (row, col) => {
+  if (col.key === 'edit') {
+    console.log('编辑行:', row)
+  }
+}
+</script>
+
+<template>
+  <SmartTable
+    :columns="columns"
+    :data="tableData"
+    @cellClick="handleCellClick"
+  />
+</template>
+```
+
+---
+
+#### 12. `link` - 链接
+
+**配置**：
+```typescript
+{
+  key: 'detail',
+  label: '详情',
+  render: 'link',
+  renderProps: {
+    label?: string        // 链接文本
+    href: string          // 链接地址（必需）
+    blank?: boolean       // 是否新窗口打开，默认 false
+    style?: string        // 自定义样式
+  }
+}
+```
+
+**示例**：
+```typescript
+const columns = [
+  {
+    key: 'url',
+    label: '查看',
+    render: 'link',
+    renderProps: {
+      label: '查看详情',
+      href: 'https://example.com',
+      blank: true,
+      style: 'color: #409EFF'
+    }
+  }
+]
+```
+
+---
+
+### 🔧 扩展型渲染器
+
+用于自定义复杂场景。
+
+#### 13. `slot` - 自定义插槽
+
+**功能**：使用 Vue 插槽完全自定义列内容。
+
+**配置**：
+```typescript
+{
+  key: 'attachments',
+  label: '附件',
+  render: 'slot',
+  slot?: string  // 插槽名称，默认使用 key
+}
+```
+
+**示例**：
+```vue
+<script setup>
+const columns = [
+  {
+    key: 'attachments',
+    label: '附件列表',
+    render: 'slot',
+    slot: 'attachments'
+  }
+]
+
+const tableData = ref([
+  {
+    id: 1,
+    attachments: [
+      { name: 'file1.pdf', url: '/files/file1.pdf' },
+      { name: 'file2.jpg', url: '/files/file2.jpg' }
+    ]
+  }
+])
+
+const download = (url) => {
+  console.log('下载:', url)
+}
+</script>
+
+<template>
+  <SmartTable :columns="columns" :data="tableData">
+    <template #attachments="{ row }">
+      <div v-for="(file, index) in row.attachments" :key="index">
+        <el-button type="text" @click="download(file.url)">
+          {{ file.name }}
+        </el-button>
+      </div>
+    </template>
+  </SmartTable>
+</template>
+```
+
+**效果**：
+- 完全自定义列内容
+- 访问完整的行数据
+- 可以包含复杂的交互逻辑
+
+---
+
+### TypeScript 类型支持
+
+所有渲染器的 `renderProps` 都有完整的 TypeScript 类型定义：
+
+```typescript
+import type { ColumnConfig, RendererPropsMap } from 'vue3-smart-table'
+
+// 类型安全
+const column: ColumnConfig = {
+  key: 'status',
+  label: '状态',
+  render: 'dict',
+  renderProps: {
+    options: [  // ✅ 类型提示和检查
+      { label: '启用', value: 1 }
+    ]
+  }
+}
+
+// 提取特定渲染器的 props 类型
+type DictProps = RendererPropsMap['dict']
+const dictConfig: DictProps = {
+  options: [],
+  showValue: true
+}
+```
+
+---
+
+### 最佳实践
+
+1. **选择合适的渲染器**
+   - 简单映射 → `map`
+   - 需要标签样式 → `dict`
+   - 复杂逻辑 → `formatter`
+   - 自定义内容 → `slot`
+
+2. **性能优化**
+   - 大量数据时避免 `formatter`，使用 `map` 或 `dict`
+   - 复杂自定义内容优先使用 `slot`
+
+3. **用户体验**
+   - 图片显示添加 `placeholder`
+   - 复制功能添加友好的提示文本
+   - 编辑单元格添加合适的 `placeholder`
+
+---
+
 ## 5. 事件
 
 ### 单元格编辑事件
@@ -1150,44 +1146,7 @@ interface SmartTableEmits {
 
 ---
 
-## 7. 主题定制
-
-### CSS 变量
-
-在项目中覆盖 CSS 变量来自定义主题:
-
-```css
-/* 你的样式文件 */
-:root {
-  --st-primary-color: #1890ff;
-  --st-success-color: #52c41a;
-  --st-warning-color: #faad14;
-  --st-danger-color: #ff4d4f;
-  --st-info-color: #8c8c8c;
-
-  /* 文本颜色 */
-  --st-text-primary: #262626;
-  --st-border-color: #d9d9d9;
-  --st-bg-color: #ffffff;
-}
-```
-
-### JavaScript 配置
-
-```typescript
-import { setSmartTableConfig } from 'vue3-smart-table'
-
-setSmartTableConfig({
-  theme: {
-    primaryColor: '#1890ff',
-    successColor: '#52c41a'
-  }
-})
-```
-
----
-
-## 8. 按需引入
+## 6. 按需引入
 
 ### 只引入需要的部分
 
@@ -1220,7 +1179,7 @@ import { getRendererManager, createFunctionalRenderer } from 'vue3-smart-table'
 
 ---
 
-## 9. 高级用法
+## 7. 高级用法
 
 ### 自定义渲染器（3种方式）
 
@@ -1338,7 +1297,7 @@ const permissions = ['user:edit', 'user:view']
 
 ---
 
-## 10. 完整示例
+## 8. 完整示例
 
 ```vue
 <!-- 全局注册 -->