通用列表 · ElementPlus

核心 API 请查阅 通用列表-基础篇，本文档仅说明 ElementPlus 框架下的特化配置。

导入路径

import { $initHook, $JiessTable } from '@jiess/plus/vue3';

ElementPlus 表格组件映射

Jiess 概念	ElementPlus 组件	说明
$JiessTable	el-table + el-pagination	PC 端表格 + 分页
$Search	el-form (inline)	搜索栏
$field	el-table-column	表格列
$tools	el-button 组	操作按钮

ElementPlus 特有属性

表格透传属性

$JiessTable({
    rowKey: 'id',
    action: '/api/users',
    // 以下透传给 el-table
    border: true,
    stripe: true,
    size: 'small',
    highlightCurrentRow: true,
    tooltipEffect: 'dark',
    // 以下透传给 el-pagination
    layout: 'total, sizes, prev, pager, next, jumper',
    pageSizes: [10, 20, 50, 100],
});

列透传属性

$JiessTable({
    $fields: [
        {
            $label: '姓名',
            $name: 'name',
            $width: 120,
            // 以下透传给 el-table-column
            fixed: 'left',
            sortable: 'custom',
            showOverflowTooltip: true,
            align: 'center',
        },
    ],
});

自定义列渲染（JSX）

$JiessTable({
    $fields: [
        {
            $label: '操作',
            $TableField: {
                render(row) {
                    return (
                        <el-space>
                            <el-button type="primary" onClick={() => edit(row)}>编辑</el-button>
                            <el-button type="danger" onClick={() => del(row)}>删除</el-button>
                        </el-space>
                    );
                },
            },
        },
    ],
});

注意事项

事项	说明
el-pagination	分页参数自动映射：fieldPage→current-page、fieldPageSize→page-size
表格高度	通过 height/maxHeight 控制固定高度和最大高度
el-table-column type	支持 selection/index/expand 等内置列类型

实战示例

示例1：完整 CRUD 列表示例（搜索 + 表格 + 分页 + 操作）

$JiessTable({
    rowKey: 'id',
    action: '/api/users',
    border: true,
    stripe: true,
    size: 'small',
    // 搜索栏配置
    $search: {
        $content: {
            $keyword: {
                $label: '关键词',
                clearable: true,
            },
            status: {
                $Select: {
                    $label: '状态',
                    options: [
                        { label: '全部', value: '' },
                        { label: '启用', value: 1 },
                        { label: '禁用', value: 0 },
                    ],
                    clearable: true,
                },
            },
        },
    },
    // 表格列配置
    $fields: [
        { $label: '姓名', $name: 'name', $width: 120, sortable: 'custom' },
        { $label: '邮箱', $name: 'email', $width: 200, showOverflowTooltip: true },
        { $label: '手机号', $name: 'phone', $width: 140 },
        { $label: '状态', $name: 'status', $width: 80, align: 'center' },
        { $label: '角色', $name: 'role', $width: 100 },
        {
            $label: '创建时间',
            $name: 'createTime',
            $width: 180,
            sortable: 'custom',
        },
        {
            $label: '操作',
            $TableField: {
                render(row) {
                    return (
                        <el-space>
                            <el-button type="primary" size="small" onClick={() => editRow(row)}>编辑</el-button>
                            <el-button type="danger" size="small" onClick={() => deleteRow(row)}>删除</el-button>
                        </el-space>
                    );
                },
            },
        },
    ],
    // 分页配置
    layout: 'total, sizes, prev, pager, next, jumper',
    pageSizes: [10, 20, 50],
});

示例2：多选 + 批量操作

$JiessTable({
    rowKey: 'id',
    action: '/api/users',
    border: true,
    // 工具栏（顶部操作区）
    $header: {
        $left: {
            $Button: {
                children: '批量删除',
                type: 'danger',
                onClick: () => {
                    // selectedRows 为勾选的行数据数组
                    const ids = selectedRows.value.map(r => r.id);
                    batchDelete(ids).then(() => tableRef.value.doLoad());
                },
            },
            $Button: {
                children: '批量启用',
                type: 'success',
                onClick: () => {
                    const ids = selectedRows.value.map(r => r.id);
                    batchEnable(ids).then(() => tableRef.value.doLoad());
                },
            },
        },
        $right: {
            $Button: {
                children: '新增',
                type: 'primary',
                onClick: () => dialog.open({ /* 新增表单 */ }),
            },
        },
    },
    // 列表项配置
    $fields: [
        // 必须指定 type: 'selection' 启用选择框
        {
            $label: '',
            $name: '',
            type: 'selection',
            $width: 55,
        },
        { $label: '姓名', $name: 'name', $width: 120 },
        { $label: '邮箱', $name: 'email', $width: 200 },
        { $label: '状态', $name: 'status', $width: 80 },
    ],
});

示例3：展开行（嵌套详情）

$JiessTable({
    rowKey: 'id',
    action: '/api/orders',
    border: true,
    $fields: [
        { $label: '订单号', $name: 'orderNo', $width: 180 },
        { $label: '客户', $name: 'customerName', $width: 120 },
        { $label: '金额', $name: 'amount', $width: 100 },
        { $label: '状态', $name: 'status', $width: 80 },
    ],
    // el-table 展开行配置
    expand: true,
    // 展开行渲染内容（如订单明细子表格）
    expandRowKeys: [],
    rowExpand: (row) => {
        return (
            <el-table data={row.items} border size="small">
                <el-table-column prop="productName" label="商品名称" />
                <el-table-column prop="price" label="单价" width="100" />
                <el-table-column prop="qty" label="数量" width="80" />
                <el-table-column prop="subtotal" label="小计" width="100" />
            </el-table>
        );
    },
});

下一步

• 通用列表-基础篇 — 列表核心 API（分页/搜索/排序/数据请求）