使用教程

TableRender

易用且轻量的中后台列表解决方案，常用于搜索列表页快速生成

简介

1. 真正开箱即用：以最简单的 API 配置请求和表头的字段，就能生成一个好用搜索列表。
2. XRender 生态：搜索筛选能力用 FormRender 来提供，以最小成本快速生成上侧搜索面板。
3. 无缝习惯使用：表格能用 Ant Design Table 来提供，降低用户使用成本。

安装

table-render 依赖 ant design，单独使用不要忘记安装～

npm i table-render --save

代码演示

/**
 * transform: true
 * defaultShowCode: false
 * background: 'rgb(245,245,245)'
 */
import React from 'react';
import { Table, Search, withTable } from 'table-render';
const dataSource = [];
for (let i = 0; i < 6; i++) {
  dataSource.push({
    id: i.toString(),
    title: `标题${i + 1}`,
    created_at: new Date().getTime(),
  });
}
// 详细可见 form-render 的使用
const schema = {
  type: 'object',
  properties: {
    title: {
      title: '标题',
      type: 'string',
      width: '30%',
      labelWidth: 45
    },
    created_at: {
      title: '创建时间',
      type: 'string',
      format: 'date',
      width: '30%',
    },
  },
};
// 配置完全透传 antd table
const columns = [
  {
    title: '标题',
    dataIndex: 'title',
  },
  {
    title: '创建时间',
    key: 'since',
    dataIndex: 'created_at',
    valueType: 'date',
  },
  {
    title: '操作',
    render: (row, record) => <a onClick={() => alert(row.title)}>编辑</a>,
  },
];
const Wrapper = () => {
  const searchApi = () => {
    return {
      rows: dataSource,
      total: dataSource.length,
    };
  };
  return (
    <>
      <Search schema={schema} api={searchApi} />
      <Table headerTitle="最简表格" columns={columns} rowKey="id" />
    </>
  );
};
export default withTable(Wrapper);

API

WithTable

TableRender 在底层使用了 Context 管理内部状态，withTable 是 Context Provider 高阶组件形式的语法糖，用户需要使用 withTable 包裹表格组件

import { withTable，useTable } from 'table-render';
const Page = () => {
  const { refresh } = useTable();
}
export default withTable(Page)

Search

我们将搜索相关的能力放到 <Search /> 上面配置，包括对应的搜索筛选表单的渲染

Api

api 有两个入参：params、sorter，分别是表单筛选项的值、排序参数。api 需要返回一个对象，此对象中必须要有 rows 和 total。 表单查询时 api 会被自动调用，同时带入最新的表单值和其他查询参数

```jsx | pure const searchApi = async (params, sorter) => { const result = await getTableData(params, sorter);

return { rows: result.list, // rows 对应表格的 tableSource，必须返回 total: result.total, // total 对应数据的总数，用于分页，必须返回 } }

可以通过数组形式传入多个 `api` 函数，Table-Render 会自动生成对应的 tab
```jsx | pure
const searchHotel = async (params) => {
  const result = await getHotelData(params);
  return {
    rows: result.list,
    total: result.total,
  }
}
const searchPeople = async (params) => {
  const result = await getPeopleData(params);
  return {
    rows: result.list,
    rows: result.totla,
  }
}
// 需要额外的 name 属性，作为 tab 的名称
<Search 
  api={[
    { name: '酒店数据', api: searchHotel },
    { name: '人员数据', api: searchPeople },
  ]}
/>

Table

支持所有 antd table 的 props，但是dataSource, loading, pagination这几个参数是内部状态，不需要填写

Columns

columns 为 antd 已有的 props，支持 antd 所有的 columns 配置，同时也提供了一些更方便的 api，加快书写

ValueType

TableRender 封装了一些常用的值类型来减少重复的 render 操作，配置一个 valueType 即可展示格式化响应的数据

  const columns = [
    {
      title: '酒店GMV',
      dataIndex: 'money',
      valueType: 'money', // 自动将格式转换为 '¥0,0.00'  
    },
    {
      title: '成立时间',
      dataIndex: 'created_at',
      valueType: 'date', // 自动将格式转换为 'YYYY-MM-DD' 
    },
    // ...
  ]

Enum

当前列值的枚举，方便处理表格值的映射

const columns = [
  {
    title: '酒店状态'
    dataIndex: 'state',
    enum: {
      open: '营业中',   // 自动将 open 转换为 营业中
      closed: '已打烊', // 自动将 closed 转换为 已打烊
    },
  },
  // ...
]

UseTable

可通过 useTable 获取如下 table-render 的 context

导出 useTable 以及对应的方法

  import { useTable } from 'table-render';
  const { refresh, tableState, setTable } = useTable();

TableState

表单的全局状态 tableState 包含的如下的数据

  {
    loading: false, // 表单是否在加载中
    search: {},     // 选项数据
    searchApi,      // 搜索用的api
    tab: 0,         // 如果 searchApi 为多个，会自动生成相应个数的 tab，这里代表的是当前的 tab 的 key
    dataSource: [], // 表格的数据
    extraData: { }, // 自定义的扩展信息
    pagination: {
      current: 1,   // 当前页码
      pageSize: 10, // 当前页数
      total: 100,   // 总数
    },
  }

Refresh

主动触发表单刷新的方法

type Refresh = (
  config?: { 
    stay: boolean, // 刷新之后是否停留在目前的页码上，默认 false，回到第一页
    tab: number    // searchApi 有多个时，用于强制搜索某个 tab 对应的 searchApi
  },
  search?: any     // 额外传递给 searchApi 的参数
) => Promise<void>;
const { refresh } = useTable();
const onClick = () => {
  refresh({ stay: true }); // 刷新数据，但停留在现有的页码
}

ChangeTab

手动切换当前 tab 的方法

  type ChangeTab = (
    tab: number
  ) => Promise<void>;
  const { changeTab } = useTable();
  const onClick = () => {
    changeTab(1);   // 手动切换到对应tab
  };