From ba3dfc720d5ba822460bdea503461354ef4d3b3c Mon Sep 17 00:00:00 2001
From: liuhanchen <liuhanchen@zeyihuoyun.com>
Date: Fri, 16 Jun 2023 15:58:43 +0800
Subject: [PATCH] feat: 更新表格文档

---
 examples/views/docs/component/schema-table.md |  12 +++++++-----
 examples/views/docs/component/table.md        | 304 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---------------------
 2 files changed, 290 insertions(+), 26 deletions(-)

diff --git a/examples/views/docs/component/schema-table.md b/examples/views/docs/component/schema-table.md
index a50b3d3..33c5399 100644
--- a/examples/views/docs/component/schema-table.md
+++ b/examples/views/docs/component/schema-table.md
@@ -130,11 +130,13 @@ export default {
         </template>
       </el-table-column>
     </template>
-    <el-table-column label="右侧的列" width="120">
-      <template #default="{ $index }">
-        第{{ $index + 1 }}行
-      </template>
-    </el-table-column>
+    <template #right>
+      <el-table-column label="右侧的列" width="120">
+        <template #default="{ $index }">
+          第{{ $index + 1 }}行
+        </template>
+      </el-table-column>
+    </template>
   </z-schema-table>
 </template>
 
diff --git a/examples/views/docs/component/table.md b/examples/views/docs/component/table.md
index c0ae9b7..e66686d 100644
--- a/examples/views/docs/component/table.md
+++ b/examples/views/docs/component/table.md
@@ -2,21 +2,23 @@
 
 拓展ElementUI的`el-table`
 
-## 基础用法
+## 原始用法
 
 基本参数与ElementUI的`el-table`相同。
 
-::: snippet 支持来自表单的`size`继承
+::: snippet 相当于直接使用`el-table`
 
 ```html
 <template>
-  <el-form size="mini">
-    <z-table :data="tableData" border>
-      <el-table-column prop="name" label="姓名"></el-table-column>
-      <el-table-column prop="age" label="年龄"></el-table-column>
-      <el-table-column prop="gender" label="性别"></el-table-column>
-    </z-table>
-  </el-form>
+  <z-table size="mini" :data="tableData" border>
+    <el-table-column prop="name" label="姓名" />
+    <el-table-column prop="age" label="年龄" />
+    <el-table-column prop="gender" label="性别">
+      <template #default="{ row }">
+        <el-tag size="mini">{{ row.gender }}</el-tag>
+      </template>
+    </el-table-column>
+  </z-table>
 </template>
 
 <script>
@@ -76,26 +78,37 @@ export default {
 
 ## 追加列
 
-使用配置项时，**新增的列**则默认追加在**配置项列**之后，使用`left`插槽可在表格的最左侧插入列，顺序在**配置项列**之前
+使用配置项时，可以在配置项的左右两边追加列
 
-::: snippet 设置`columns`配置表格列，插槽`header-列字段名`可自定义表头的内容，插槽`cell-列字段名`可自定义列单元格的内容。
+::: snippet 使用`left`插槽在表格配置项的左侧插入列，使用`right`插槽在表格配置项的右侧插入列。
 
 ```html
 <template>
   <z-table :data="tableData" border size="small" :columns="columns">
-    <template #left>
+    <template #prepend>
       <el-table-column type="selection" width="40"></el-table-column>
+    </template>
+    <template #left>
       <el-table-column label="左侧的列">
         <template #default="{ $index }">
-          内容 {{ $index }}
+          左侧内容 {{ $index }}
+        </template>
+      </el-table-column>
+    </template>
+    <template #right>
+      <el-table-column label="右侧的列">
+        <template #default="{ $index }">
+          右侧内容 {{ $index }}
+        </template>
+      </el-table-column>
+    </template>
+    <template #append>
+      <el-table-column label="后置列" width="80">
+        <template #default>
+          <el-button type="text">编辑</el-button>
         </template>
       </el-table-column>
     </template>
-    <el-table-column label="新增的列" width="80">
-      <template #default>
-        <el-button type="text">编辑</el-button>
-      </template>
-    </el-table-column>
   </z-table>
 </template>
 
@@ -121,7 +134,9 @@ export default {
 
 :::
 
-## 可编辑表格
+## 可编辑表格（即将废弃）
+
+> 由于创建时间较早且性能不佳，在2.0.1版本之后不推荐使用，并在若干版本之后废弃
 
 一般用于表格的静态数据编辑，设置`editable`开启可编辑模式，设置`clickable`开启双击编辑
 
@@ -188,6 +203,254 @@ export default {
 
 :::
 
+## 编辑器
+
+表格单元格可通过`editor`参数来配置编辑器，默认与表格数据值双向绑定
+
+::: snippet 设置`items`配置编辑器列
+
+```html
+<template>
+  <div>
+    <div>{{ tableData }}</div>
+    <z-table :data="tableData" border size="small" :columns="columns" :editor="editor" />
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      tableData: [
+        { name: '张三', age: '31', gender: '男' },
+        { name: '李四', age: '27', gender: '女' },
+        { name: '王五', age: '16', gender: '男' },
+      ],
+      columns: [
+        { prop: 'name', label: '姓名' },
+        { prop: 'age', label: '年龄' },
+        { prop: 'gender', label: '性别' },
+      ],
+      editor: {
+        items: [
+          { is: 'el-input', prop: 'name', attrs: { placeholder: '请输入' }, props: { size: 'mini', clearable: true } },
+          { is: 'el-input-number', prop: 'age', attrs: { style: 'width: 100%' }, props: { size: 'mini', clearable: true } },
+        ]
+      }
+    };
+  },
+}
+</script>
+```
+
+:::
+
+## 编辑器对象取值与赋值
+
+编辑器可对深层对象进行双向绑定，通过`deep`参数来配置
+
+::: snippet 表格配置项也支持对象的深层取值
+
+```html
+<template>
+  <div>
+    <div>{{ tableData }}</div>
+    <z-table :data="tableData" border size="small" :columns="columns" :editor="editor" />
+  </div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      tableData: [
+        { name: '张三', info: { age: 27, gender: '女', district: { city: '上海市' } } },
+        { name: '李四', info: { age: 19, gender: '男', district: { city: '北京市' } } },
+      ],
+      columns: [
+        { prop: 'name', label: '姓名' },
+        { prop: 'info.age', label: '年龄' },
+        { prop: 'info.gender', label: '性别' },
+      ],
+      editor: {
+        deep: true,
+        items: [
+          { is: 'el-input', prop: 'name', attrs: { placeholder: '请输入' }, props: { size: 'mini', clearable: true } },
+          { is: 'el-input-number', prop: 'info.age', attrs: { style: 'width: 100%' }, props: { size: 'mini', clearable: true } },
+        ]
+      }
+    };
+  },
+}
+</script>
+```
+
+:::
+
+## 编辑器条件渲染
+
+编辑器支持通过行内的某些数值来进行条件渲染，支持配置`if`来进行条件渲染。
+
+::: snippet `if`同时支持**boolean**和**function**两种类型，其中**function**可拿到当前行数据
+
+```html
+<template>
+  <z-table :data="tableData" border size="small" :columns="columns" :editor="editor" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      tableData: [
+        { name: '张三', info: { age: 27, gender: '女', district: { city: '上海市' } } },
+        { name: '李四', info: { age: 19, gender: '男', district: { city: '北京市' } } },
+      ],
+      columns: [
+        { prop: 'name', label: '姓名' },
+        { prop: 'info.age', label: '年龄' },
+        { prop: 'info.gender', label: '性别' },
+      ],
+      editor: {
+        deep: true,
+        items: [
+          { is: 'el-input', prop: 'name', attrs: { placeholder: '请输入' }, props: { size: 'mini', clearable: true }, if: ({ row, index }) => index > 0 },
+          { is: 'el-input-number', prop: 'info.age', attrs: { style: 'width: 100%' }, props: { size: 'mini', clearable: true }, if: false },
+        ]
+      }
+    };
+  },
+}
+</script>
+```
+
+:::
+
+## 编辑器条件渲染扩展
+
+除了`if`之外，`props`、`attrs`、`on`都支持条件渲染
+
+::: snippet 同时支持**boolean**和**function**两种类型，其中**function**可拿到当前行数据
+
+```html
+<template>
+  <z-table :data="tableData" border size="small" :columns="columns" :editor="editor" />
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      tableData: [
+        { name: '', info: { age: 18, gender: '女', district: { city: '上海市' } } },
+        { name: '', info: { age: 27, gender: '男', district: { city: '北京市' } } },
+      ],
+      columns: [
+        { prop: 'name', label: '姓名' },
+        { prop: 'info.age', label: '年龄' },
+        { prop: 'info.gender', label: '性别' },
+      ],
+      editor: {
+        deep: true,
+        items: [
+          { is: 'el-input', prop: 'name', attrs: ({ row }) => ({ placeholder: '请输入' + (row.info.gender === '女' ? 'MM' : 'GG') + '的姓名' }), props: { size: 'mini', clearable: true } },
+          { is: 'el-input', prop: 'info.age', props: ({ row }) => (row.info.gender === '女' ? { size: 'mini', disabled: true } : { size: 'mini', clearable: true }) },
+        ]
+      }
+    };
+  },
+}
+</script>
+```
+
+:::
+
+## 编辑器校验
+
+编辑器默认支持`el-form`的单元格校验，配置`editor`参数中的`validate`开启校验模式，配置`editor`参数中的`path`设置当前表格在form表单中的路径，表头会根据rules自动判断是否必填项追加`*`号
+
+::: snippet 配置编辑器`editor`下的`rules`设置单元格的校验规则，也可以在`items`的`rules`中配置用以支持条件渲染
+
+```html
+<template>
+  <el-form ref="form" :model="form">
+    <el-form-item label="ID" prop="id">
+      <el-input :value="form.id" type="text" disabled />
+    </el-form-item>
+    <z-table :data="form.list" border size="small" :columns="columns" :editor="editor" />
+    <el-form-item>
+      <el-button size="mini" @click="handleValidate">校验</el-button>
+    </el-form-item>
+  </el-form>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      form: {
+        id: 'test',
+        list: [
+          { name: '', age: 18, gender: '女', },
+          { name: '', age: 27, gender: '男' },
+        ]
+      },
+      columns: [
+        { prop: 'name', label: '姓名', showOverflowTooltip: true },
+        { prop: 'age', label: '年龄', showOverflowTooltip: true },
+        { prop: 'gender', label: '性别', showOverflowTooltip: true },
+      ],
+      editor: {
+        path: 'list',
+        validate: true,
+        rules: {
+          name: [{ required: true, message: '请输入姓名' }],
+        },
+        items: [
+          { is: 'el-input', prop: 'name', attrs: { placeholder: '请输入姓名' }, props: { size: 'mini', clearable: true } },
+          {
+            is: 'el-input',
+            prop: 'age',
+            props: { size: 'mini', clearable: true },
+            rules: ({ row = {} }) => {
+              if (row.gender === '女') {
+                return [{
+                  validator: (rule, value, callback) => {
+                    if (value < 14) {
+                      callback(new Error('还年轻'));
+                    }
+                    if (value > 18) {
+                      callback(new Error('永远18岁'));
+                    }
+                    callback();
+                  },
+                }];
+              } else {
+                return [{ required: true, message: '请输入年龄' }]
+              }
+            }
+          },
+        ]
+      }
+    };
+  },
+  methods: {
+    handleValidate() {
+      this.$refs.form.validate(valid => {
+        if (valid) {
+          this.$message.success('校验通过');
+        } else {
+          this.$message.error('校验失败');
+        }
+      });
+    }
+  }
+}
+</script>
+```
+
+:::
+
 ## API
 
 ## Attribute 属性
@@ -195,6 +458,5 @@ export default {
 参数|说明|类型|可选值|默认值
 -|-|-|-|-
 data | 表格数据 | Array | - | -
-value | 表格数据（支持v-model） | Array | - | []
 columns | 表格列配置 | Array | - | []
-type | 表格类型 | String | normal、editable | normal
\ No newline at end of file
+editor | 编辑器配置 | Object | - | -
\ No newline at end of file
--
libgit2 0.21.0