@hzab/list-render

列表组件，支持传入 schema 进行 CURD 相关组件（列表、新增、编辑、删除）的渲染

• Schema JSON 配置项目：
  • https://codeup.aliyun.com/62046985b3ead41b374a17f7/frontedn_components/Formily/formily-designable-ui
  • clone 之后 npm i
  • npm run dev 启动项目，即可使用该项目进行 Schema JSON 的配置
  • 官方配置地址（配置响应器存在白屏 bug）：https://designable-antd.formilyjs.org/

组件

Tips

• antd 组件样式需要手动引入
• 相关文档可查看 docs 中的文件

示例

import ListRender from "@hzab/list-render";

const listDM = useMemo(
  () =>
    new DataModel({
      getListApi: "/api/v1/userinfo",
      // 可用于替代 getList 的函数，处理自定义数据
      getListFunc() {
        return new Promise((resolve) => {
          resolve({
            list: [{ id: 1, menuName: "name" }],
            pagination: { total: 1, current: 1 },
          });
        });
      },
      createApi: "/api/v1/userinfo",
      getApi: "/api/v1/userinfo/:id",
      updateApi: "/api/v1/userinfo/:id",
      deleteApi: "/api/v1/userinfo/:id",
    }),
  [],
);

// testSchema 为 formily 生成的 schema json
<ListRender schema={testSchema} model={listDM} />;

API

InfoPanel Attributes

| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 | | ----------------- | ---------------- | ---- | --------------- | -------------------------------------------------------------------------------------------------------- | | className | string | 否 | - | 外层 div className | | idKey | string | 否 | id | 唯一值字段的 key | | schema | Object | 是 | - | 字段描述文件，包含各个字段的信息 | | model | Object | 是 | - | 数据模型，包含 CURD 接口信息，传入 DataModel 的实例 | | list | Array | | - | 本地数据源 | | closeAutoRequest | Boolean | | false | 是否关闭加载完毕后自动发起请求。true 时组件 didMount 不自动发起请求 | | hasQuery | Boolean | | true | 是否包含搜索、筛选框、搜索按钮等 | | verticalHeader | Boolean | | false | 搜索项和新增按钮是否处于不同的行等 | | search | String | | - | 传入空字符串时，不包含搜索框；传入非空字符串时，显示搜索框，同时传入的字符串作为搜索框的占位符 | | filters | Array | | [] | 字符串数组，可以包含要筛选的字段 key 值（schema 中的 name），或者字符串 '$timerange'（时间范围筛选专用） | | queryConf | Object | | {} | 设置 query 参数的 key | | createText | String/ReactNote | | 新增 | 新增按钮文案 | | hasCreate | Boolean | | true | 是否显示新增按钮 | | hasAction | Boolean | | true | 是否在表格的最右增加一个“操作”列；hasAction 为 true 时，下面的 hasEdit/hasDel 才会生效 | | hasEdit | Boolean/Function | | true | 是否显示编辑按钮，可传入回调控制当前行是否显示 | | hasDel | Boolean/Function | | true | 是否显示删除按钮，可传入回调控制当前行是否显示 | | hasDelTips | String/Function | | "确认删除该项?" | 删除按钮自定义提示，可传入回调根据当前行数据显示对应提示 | | tableConf | Object | | {} | Table 相关配置 | | tableProps | Object | | {} | 直接传给 Table 的 props，相关 API 可直接参考 antd table 组件 | | fetchOnEdit | Boolean | | true | 展示编辑弹框时，是否会调用一次详情接口进行回填；若为 false，则会使用表格列表接口返回的 row 数据进行回填 | | fetchById | Boolean | | true | 编辑中的详情请求，是否使用 id 作为入参的 key | | dialogConf | Object | | {} | dialog 配置对象 | | schemaScope | Object | | {} | formRender schemaScope props | | components | Object | | {} | formRender components props 自定义组件 | | hasPagination | Boolean | | true | 是否显示分页 | | paginationConf | Object | | {} | 可自定义 Pagination props，进行 pagination 相关设置 | | formInitialValues | Object | | {} | 给新增、编辑对话框中的表单增加默认值 | | Slots | Object | | {} | 组件插槽 | | getFieldListOpt | Object | | {} | getFieldList opt 参数 | | onGetListEnd | Function | | - | 请求列表成功返回的回调 | | onCreateSuc | Function | | - | 新增成功返回的回调 | | onEditSuc | Function | | - | 编辑成功返回的回调 | | onDelSuc | Function | | - | 删除成功返回的回调 | | onFormDialogClose | Function | | - | 表单弹窗关闭回调 | | dialogFormMount | Function | | - | 新增、编辑弹窗 Form 渲染完成回调 | | msgConf | Object | | {} | 新增、编辑、删除、列表查询，详情查询的报错 msg 提示设置 | | i18n | Object | | {} | 文案配置 |

• fetchOnEdit 展示编辑弹框时，是否会调用一次详情接口进行回填（某些场景下，列表接口只返回部分部分字段，只有详情接口会返回全部字段）；若为 false，则会使用表格列表接口返回的 row 数据进行回填

tableConf

| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 | | ------------- | ------------- | ---- | ------ | -------------------------------------------------------------------------------------------- | | colConf | Object | | {} | 指定各列的配置（比如列宽），key 为字段的 name。可以指定名为 “_$actions”的字段来设置“操作”列 | | rowSelection | Object | | {} | 选择功能的配置。参考 antd table rowSelection 参数 | | scroll | Object | | {} | 表格是否可滚动，也可以指定滚动区域的宽、高。参考 antd table scroll 参数 | | expandable | Object | | {} | 配置展开属性。参考 antd table expandable 参数 | | onRow | Object | | {} | 设置行属性。参考 antd table onRow 参数 | | orderColType | string | | - | 序号列数据类型：page（按当前页的序号）、all（按所有页的序号） | | orderColWidth | string/number | | - | 序号列 width 的参数 |

tableConf.colConf[xxx]

| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 | | -------- | -------------- | ---- | ------ | ------------------------------------------------------------ | | ellipsis | boolean/Object | | - | 当前列是否超出隐藏，true 或 { showTitle: true } 开启超出隐藏 |

queryConf

| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 | | ----------------- | ----------------------------- | ---- | ------ | -------------------------- | | hasReset | boolean | | false | 是否有重置按钮 | | queryMap | Function | | - | query 数据提交前的处理函数 | | beforeQuerySearch | Function ｜ Promise<boolean> | | - | 点击搜索按钮前触发的函数 |

model

| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 | | -------- | -------- | ---- | ------ | ------------ | | query | Object | 否 | | get 请求参数 |

i18n

| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 | | ----------- | -------- | ---- | ------------- | ---------------- | | createText | string | 否 | 新增 | 新增按钮文案 | | tableEdit | string | 否 | 编辑 | 表格编辑按钮文案 | | tableDel | string | 否 | 删除 | 表格删除按钮文案 | | tableDelTip | string | 否 | 确认删除该项? | 表格删除提示文案 |

Slots 插槽

• 用于在指定位置添加所需的组件

| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 | | ------------------ | -------- | ---- | ------ | ------------------------------------ | | headerActionPrefix | Function | 否 | | 新增按钮左侧插槽 | | headerActionSuffix | Function | 否 | | 新增按钮右侧插槽 | | tableActionsSlot | Function | 否 | | 操作列插槽，会覆盖操作列 | | actionPrefixSlot | Function | 否 | | 操作列 编辑按钮左侧插槽 | | actionCenterSlot | Function | 否 | | 操作列 编辑、删除按钮中间插槽 | | actionSuffixSlot | Function | 否 | | 操作列 删除按钮右侧插槽 | | FormSlot | Function | 否 | | 新增、编辑弹窗插槽 | | dialogFooterPre | Function | 否 | | 新增、编辑弹窗确认及取消按钮左侧插槽 | | dialogFooterCenter | Function | 否 | | 新增、编辑弹窗确认及取消按钮中间插槽 | | dialogFooterSuffix | Function | 否 | | 新增、编辑弹窗确认及取消按钮右侧插槽 |

// Slots 按需添加
const Slots = {
  headerActionPrefix() {
    return (<div>headerActionPrefix</div>)
  },
  actionPrefixSlot(props) {
    const { text, record, index, onEdit, onDel } = props;
    return (<div>actionPrefixSlot</div>)
  },
  dialogFooterPre(props) {
    const {
      cancel,
      onOk,
      close,
      form,
      validate,
    } = props?.options || {};
    return (<div>dialogFooterPre</div>)
  }
};

<ListRender schema={schema} model={listDM} Slots={Slots} />

dialogConf

| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 | | ------------ | ------------- | ---- | ------ | --------------------------------------------------- | | width | number/string | 否 | | 弹窗宽度 | | okText | string | 否 | | 弹窗底部确定按钮文案 | | cancelText | string | 否 | | 弹窗底部取消按钮文案 | | footer | Array | 否 | | 自定义弹窗底部按钮 | | beforeSubmit | Function | 否 | | 提交前的回调， return false; 表示拦截，不进行请求。 |

paginationConf

• 默认参数参考 antd pagination 组件

| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 | | --------------- | -------- | ---- | ----------------- | ------------------ | | pageSizeOptions | Array | 否 | [10, 20, 50, 100] | 可选 pageSize 数组 |

getFieldListOpt

| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 | | -------- | ----------- | ---- | ----------------------------------------- | ---------------------------------------------------------------------- | | boxList | Array/false | 否 | "FormGrid", "FormGrid.GridColumn", "Card" | 配置内容需要大屏的父容器，如 "FormGrid", "FormGrid.GridColumn", "Card" |

Table ref Methods

• 可使用 ref 获取并触发执行

| 函数名 | 参数 | 说明 | | ------------- | ----- | -------------------------------------------- | | onSearch | query | 重置页码至 1，并刷新列表 | | getList | query | 获取当前页列表数据 | | forceUpdate | - | 强制重渲染列表，解决枚举数据渲染不正常的问题 | | formDialogRef | - | 新增、编辑 弹窗 form-dialog 的 ref | | queryRef | - | 筛选条件 query-render 的 ref | | onCreate | - | 手动触发新增按钮相关操作 | | onEdit | row | 手动触发编辑按钮相关操作 | | onDel | row | 手动触发删除按钮相关操作 |

Schema

• 字段文档：https://react.formilyjs.org/api/shared/schema#%E5%86%85%E7%BD%AE%E8%A1%A8%E8%BE%BE%E5%BC%8F%E4%BD%9C%E7%94%A8%E5%9F%9F

Schema Scope

• 用于传入参数给到响应器使用

常用示例

字段显隐 x-display

• visible: 显示（默认状态）
• hidden: 半隐藏。字段可赋值，可监听，但表单项隐藏
• none: 全隐藏。字段完全不可用。

{
  "form": {
    "labelCol": 6,
    "wrapperCol": 12
  },
  "schema": {
    "type": "object",
    "properties": {
      "test": {
        "type": "string",
        "title": "Input",
        "x-decorator": "FormItem",
        "x-component": "Input",
        "x-validator": [],
        "x-component-props": {},
        "x-decorator-props": {},
        "x-reactions": {},
        "x-designable-id": "1zlm9bu3fpg",
        "x-index": 0,
        "name": "test",
        "x-display": "none"
      }
    },
    "x-designable-id": "ldzb3lu81dx"
  }
}

字段在表格中隐藏 inTable

• true: 在表格中展示（默认）
• false: 在表格中隐藏

{
  "form": {},
  "schema": {
    "type": "object",
    "properties": {
      "test": {
        "type": "string",
        "title": "Input",
        "x-decorator": "FormItem",
        "x-component": "Input",
        "x-validator": [],
        "x-component-props": {},
        "x-decorator-props": {},
        "x-reactions": {},
        "x-designable-id": "1zlm9bu3fpg",
        "x-index": 0,
        "name": "test",
        "inTable": false
      }
    },
    "x-designable-id": "ldzb3lu81dx"
  }
}

字段动态显隐——响应器

编辑表单中才显示

• 通过 scenario 获取当前表单环境变量
• 属性响应中，显示/隐藏配置：scenario === 'edit'

{
  "form": {},
  "schema": {
    "type": "object",
    "properties": {
      "test": {
        "type": "string",
        "title": "Input",
        "x-decorator": "FormItem",
        "x-component": "Input",
        "x-validator": [],
        "x-component-props": {},
        "x-decorator-props": {},
        "x-reactions": {
          "dependencies": [
            {
              "property": "value",
              "type": "any"
            }
          ],
          "fulfill": {
            "state": {
              //当涉及三层及以上的时，请使用 display，3依赖于2,2依赖于1时，编辑设置值时，3依赖于2的赋值，不会捕捉到
              // 例："display": "{{$deps.hasECert === 1  ? \"visible\" : \"hidden\"}}"
              "visible": "{{scenario === 'edit'}}"
            }
          }
        },
        "x-designable-id": "1zlm9bu3fpg",
        "x-index": 0,
        "name": "test"
      }
    },
    "x-designable-id": "ldzb3lu81dx"
  }
}

响应器中可用的参数

| 参数名 | 说明 | | ----------- | ------------------------------------------------------------------------------------------------------ | | scenario | 环境参数，当前表单的环境：create、edit、query | | $self | 代表当前字段实例，可以在普通属性表达式中使用，也能在 x-reactions 中使用 | | $form | 代表当前 Form 实例，可以在普通属性表达式中使用，也能在 x-reactions 中使用 | | $deps | 只能在 x-reactions 中的表达式消费，与 x-reactions 定义的 dependencies 对应，数组顺序一致 | | $values | 代表顶层表单数据，可以在普通属性表达式中使用，也能在 x-reactions 中使用 | | $observable | 用于创建响应式对象，使用方式与 observable 一致 | | $memo | 用于创建持久引用数据，使用方式与 autorun.memo 一致 | | $effect | 用于响应 autorun 第一次执行的下一个微任务时机与响应 autorun 的 dispose，使用方式与 autorun.effect 一致 | | $props | 用于对房钱字段实例设置组件 props |

DataModel

Tips

• 若存在 axios 相关配置失效的问题，请在选择一下任意一种方式解决；
  • 在入口文件设置 DataModel 默认的 axios 为已配置好的 axios；
  • 在入口文件对 DataModal 的 axios 进行配置;

// 设置 DataModel 默认的 axios 为已配置好的 axios；
import axios from "axios";
import { setDefaultAxios } from "@hzab/list-render";

setDefaultAxios(axios);

// 配置 DataModal 的 axios;
import axios from "axios";
import { axios as ax } from "@hzab/list-render";

setAxRequest(axios);
setAxRequest(ax);

setAxResponse(axios);
setAxResponse(ax);

// axios 守卫
export function setAxRequest(_ax) {
  _ax.interceptors.request.use((config) => {
    const { url = "" } = config;

    if (/^\/api\/v\d+\/user\//.test(url)) {
    } else if (url.startsWith("/api")) {
      config.baseURL = cfg.businessApi;
    }

    return config;
  });
}

// 请求到结果的拦截处理;
export function setAxResponse(_ax) {
  _ax.interceptors.response.use(
    (res) => {
      // const navigateApi = useNavigate()
      // const locationApi = useLocation();
      if (res.data.code == 401) {
        message.error(res._message || "验证信息失效，请重新登录");
        // TODO: 页面跳转
        return res;
      }
      return res;
    },
    (error) => {
      console.error("Error axios response: ", error);
      message.error(error._message || "网络异常,请稍后再试");
    },
  );
}

export function setAxToken(_ax, token) {
  _ax.defaults.headers.Authorization = token;
}

export function setAxiosToken(token) {
  setAxToken(ax, token);
  setAxToken(axios, token);
}

export default axios;

使用

import { DataModel } from "@hzab/list-render";

// 生成实例
const dataModel = new DataModel({
  createApi: "api",
  createMap(data) {
    return data;
  },
  getApi: "api",
  getMap(res) {
    return res;
  },
  getListApi: "getListApi",
  getListMap(item) {
    return item;
  },
  updateApi: "updateApi",
  updateMap(data) {
    return data;
  },
  deleteApi: "deleteApi",
  multipleDeleteApi: "multipleDeleteApi",
  query: { pageNumber: 1, pageSize: 10 },
  axiosConf: {
    timeout: 10000,
  },
});
// 调用方式
async function test() {
  const createRes = await dataModel.create();
  const getRes = await dataModel.get();
  const getListRes = await dataModel.getListApi();
  const updateRes = await dataModel.update();
  const deleteRes = await dataModel.delete();
  const multipleDeleteRes = await dataModel.multipleDelete();
}

属性 Props

| 属性名称 | 属性类型 | 必须 | 默认值 | 描述 | | ----------------- | -------- | ---- | ------ | ----------------------------------------------------------------------- | | createApi | String | | | post 请求的 api，dataModel. | | createMap | Function | | | post 请求提交前的处理函数 | | getApi | String | | | get 请求的 api | | getMap | Function | | | 处理 get 返回结果，处理完需要把结果返回 | | getListApi | String | | | getList 获取列表的 api，返回列表数据和 pagination 数据 | | getListMap | Function | | | getList 结果 map 的回调函数，参数为结果每一项数据，处理完需要把结果返回 | | getListFunc | Function | | | 可用于替代 getList 的函数，处理自定义数据，参数为 query | | updateApi | String | | | put 请求的 api | | updateMap | Function | | | put 请求提交前的处理函数 | | deleteApi | String | | | delete 请求的 api | | multipleDeleteApi | | | | 批量删除请求的 api，使用的 axios({ method: 'DELETE' }) 发请求 | | query | | | | get 请求的参数 | | axiosConf | Object | | | axios 的配置项 |

组件开发流程

• 在 config/webpack.config/webpack.config.dev.js 中按需修改 alias 配置的包名，便于本地调试
• 在 src/typings.d.ts 中按需修改 declare module 配置的包名，解决 ts 报错问题
• npm run dev

文件目录

• example 本地开发测试代码
• src 组件源码
• lib 组件打包编译后的代码

命令

• 本地运行：npm run dev
• 测试环境打包编译：npm run build-flow-dev
• 生产环境打包编译：npm run build

发布

• 在 config/webpack.config/webpack.config.prod.js 中按需修改 entry 配置的文件名
• 编译组件：npm run build
• 命令：npm publish --access public
• 发布目录：
  • lib
  • src

迭代发布命令

• 0.0.x: npm run publish-patch
• 0.x.0: npm run publish-minor
• x.0.0: npm run publish-major

配置

配置文件

webpack 配置文件

• config/webpack.config.js