# @hzab/data-model

组件模板

- Node.js ≥ 24

## 安装

```bash
pnpm add @hzab/data-model
```

本包同时发布到**公共 npm**（`registry.npmjs.org`，public access）与企业私有源（ld / old）。
默认源可直接安装，无需额外配置；若团队要求走内网源，见[消费方接入指南](../../../docs/consumer-access.md#2-可选改为从企业私有源安装)。

消费方需自备 peerDependencies：`axios`、`js-cookie`、`react`（本包不会随包安装）。

引入方式见下方「组件」章节。

> **发布形态**：本包在本仓以**源码直出**方式发布——`main` 指向 `src`，由消费方打包器编译
> TypeScript 与 `.less` 样式；`@hzab/data-model/src/*` 深路径同样可直接引用。随包发布的 `dist/` 仅用于
> 类型解析（`types` → `dist/index.d.ts`），不是运行时入口。

# 组件

## 示例

```jsx
import DataModel, {
  // 设置 token 到 localStorage 及 cookie，可以设置 opt.hasCookie（setToken(token, { hasCookie: false })） 关闭设置 token 到 cookie 上
  setToken,
  // 从 cookie 或 localStorage 获取 token
  getToken,
  // 设置默认兜底的错误信息
  setDefaultErrMsg,
  // 设置默认网络异常的错误信息
  setNetworkErrMsg,
  // 设置 DataModel 中默认的 axios
  setDefaultAxios,
} from "@hzab/data-model";

const listDM = new DataModel({
  // query 参数
  query,
  // 新增接口 post url
  createApi,
  // 新增接口 post 入参枚举函数
  createMap,
  // 详情接口 get url
  getApi,
  // 详情接口 get 出参枚举函数
  getMap,
  // 详情接口 get url
  getListApi,
  // 列表接口 get 出参枚举函数
  getListMap,
  // 列表请求函数
  getListFunc,
  // put 编辑接口 url
  updateApi,
  // put 编辑接口 入参枚举函数
  updateMap,
  // patch 编辑接口 url
  patchApi,
  // patch 编辑接口 入参枚举函数
  patchMap,
  // 删除接口 delete url
  deleteApi,
  // 批量删除接口 delete url
  multipleDeleteApi,
  // 统一 response 回调，用于处理定制 response 格式
  handleResponse,
  // axios 实例对象
  axios,
  // axios 相关配置
  axiosConf,
  // getList 接口 axios 相关配置
  getListAxiosConf,
  // get 接口 axios 相关配置
  getAxiosConf,
  // create 接口 axios 相关配置
  createAxiosConf,
  // update 接口 axios 相关配置
  updateAxiosConf,
  // patch 接口 axios 相关配置
  patchAxiosConf,
  // delete 接口 axios 相关配置
  deleteAxiosConf,
  // multipleDelete 接口 axios 相关配置
  multipleDeleteAxiosConf,
  // 列表接口 get 入参枚举函数
  getListReqMap,
  // 列表接口 get 出参枚举函数
  getListResMap,
  // 详情接口 get 入参枚举函数
  getReqMap,
  // 详情接口 get 出参枚举函数
  getResMap,
  // 新增接口 post 入参枚举函数
  createReqMap,
  // 新增接口 post 出参枚举函数
  createResMap,
  // 编辑接口 put 入参枚举函数
  updateReqMap,
  // 编辑接口 put 出参枚举函数
  updateResMap,
  // patch 编辑接口 put 入参枚举函数
  patchReqMap,
  // patch 编辑接口 put 出参枚举函数
  patchResMap,
  // 删除接口 delete 入参枚举函数
  deleteReqMap,
  // 删除接口 delete 出参枚举函数
  deleteResMap,
  // 批量删除接口 delete 入参枚举函数
  multipleDeleteReqMap,
  // 批量删除接口 delete 出参枚举函数
  multipleDeleteResMap,
  // 是否返回完整的接口数据（response.data）
  isResponseData,
  // 是否直接返回 response
  isResponse,
});

// useDataModel，解决 hooks 写法 model 重复实例化导致 query 丢失的问题
function Demo({ orgId }) {
  // 第一个入参同 new DataModel，第二个参数为需要监听的动态参数数组
  const model = useDataModel(
    // 初始值
    {
      getListApi: "/getList",
      query: { orgId },
    },
    {
      // 动态的 params 数据
      effectParams: { orgId },
      // 动态 query 数据
      effectQuery: { orgId },
      // 动态数据监听的值
      effectTargets: [orgId],
    },
  );
  return <ListRender model={model} />;
}
```

#### 重复请求拦截

```tsx
import RequestCache from "@hzab/data-model/RequestCache";
import { AxiosRequestConfigWithCache, setAxRequest } from "@hzab/data-model";

const requestCache = new RequestCache({ options: { cacheTTL: 2000 } });

setAxRequest((config: AxiosRequestConfigWithCache) => {
  // 拦截 get 请求
  if (config.method.toLowerCase() === "get") {
    return requestCache.handleAxRequest(config);
  }
  return config;
});
```

## DataModel

| 参数                    | 类型     | 必填 | 默认值 | 说明                                           |
| ----------------------- | -------- | ---- | ------ | ---------------------------------------------- |
| query                   | Object   | 否   | -      | query 参数对象                                 |
| createApi               | string   | 否   | -      | post 接口地址                                  |
| getApi                  | string   | 否   | -      | 详情 get 接口地址                              |
| getListApi              | string   | 否   | -      | 列表 get 接口地址                              |
| updateApi               | string   | 否   | -      | put 接口地址                                   |
| patchApi                | string   | 否   | -      | patch 接口地址                                 |
| deleteApi               | string   | 否   | -      | delete 接口地址                                |
| multipleDeleteApi       | string   | 否   | -      | 批量删除 delete 接口地址                       |
| createMap               | Function | 否   | -      | createApi 接口提交前的处理函数                 |
| getMap                  | Function | 否   | -      | getApi 接口返回结果的处理函数                  |
| getListMap              | Function | 否   | -      | getListApi 接口返回结果的处理函数              |
| getListFunc             | Function | 否   | -      | 自定义的列表请求函数，优先级高于 getListApi    |
| updateMap               | Function | 否   | -      | updateApi 接口提交前的处理函数                 |
| patchMap                | Function | 否   | -      | patchApi 接口提交前的处理函数                  |
| axios                   | Object   | 否   | -      | axios 实例对象                                 |
| axiosConf               | Object   | 否   | -      | axios 相关配置                                 |
| getListAxiosConf        | Object   | 否   | -      | getList 接口 axios 相关配置                    |
| getAxiosConf            | Object   | 否   | -      | get 接口 axios 相关配置                        |
| createAxiosConf         | Object   | 否   | -      | create 接口 axios 相关配置                     |
| updateAxiosConf         | Object   | 否   | -      | update 接口 axios 相关配置                     |
| patchAxiosConf          | Object   | 否   | -      | patch 接口 axios 相关配置                      |
| deleteAxiosConf         | Object   | 否   | -      | delete 接口 axios 相关配置                     |
| multipleDeleteAxiosConf | Object   | 否   | -      | multipleDelete 接口 axios 相关配置             |
| getListReqMap           | Function | 否   | -      | 列表接口 get 入参枚举函数                      |
| getListResMap           | Function | 否   | -      | 列表接口 get 出参枚举函数                      |
| getReqMap               | Function | 否   | -      | 详情接口 get 入参枚举函数                      |
| getResMap               | Function | 否   | -      | 详情接口 get 出参枚举函数                      |
| createReqMap            | Function | 否   | -      | 新增接口 get 入参枚举函数                      |
| createResMap            | Function | 否   | -      | 新增接口 get 出参枚举函数                      |
| updateReqMap            | Function | 否   | -      | 编辑接口 get 入参枚举函数                      |
| updateResMap            | Function | 否   | -      | 编辑接口 get 出参枚举函数                      |
| patchReqMap             | Function | 否   | -      | patch 接口 get 入参枚举函数                    |
| patchResMap             | Function | 否   | -      | patch 接口 get 出参枚举函数                    |
| deleteReqMap            | Function | 否   | -      | 删除接口 get 入参枚举函数                      |
| deleteResMap            | Function | 否   | -      | 删除接口 get 出参枚举函数                      |
| multipleDeleteReqMap    | Function | 否   | -      | 批量删除接口 get 入参枚举函数                  |
| multipleDeleteResMap    | Function | 否   | -      | 批量删除接口 get 出参枚举函数                  |
| isResponseData          | boolean  | 否   | -      | 是否返回完整的接口数据（response.data）        |
| isResponse              | boolean  | 否   | -      | 是否直接返回 response                          |
| handleResponse          | Function | 否   | -      | 统一 response 回调，用于处理定制 response 格式 |

## useDataModel

| 参数              | 类型   | 必填 | 默认值 | 说明                             |
| ----------------- | ------ | ---- | ------ | -------------------------------- |
| initParams        | Object | 是   | -      | 初始参数，通同 DataModel         |
| opt               | Object | 否   | -      | 配置参数                         |
| opt.effectTargets | Object | 否   | -      | 动态数据监听的目标               |
| opt.effectParams  | Object | 否   | -      | 动态的 params 数据，包含了 query |
| opt.effectQuery   | Object | 否   | -      | 动态的 query 数据                |

## array-data-model

- 参数通 DataModel

### query 配置

| 参数                  | 类型                                      | 必填 | 默认值 | 说明                                                      |
| --------------------- | ----------------------------------------- | ---- | ------ | --------------------------------------------------------- |
| sortKey/orderByColumn | string/Object/Array[string]/Array[Object] | 否   | -      | 排序字段，支持多维度排序，按照传入的顺序排优先级          |
| sortType/isAsc        | string/Object                             | 否   | -      | 排序规则，支持对象配置各字段排序规则 正序: asc 倒序: desc |

### sortKey/orderByColumn Object 配置

| 参数          | 类型     | 必填 | 默认值 | 说明                                                                                                                                      |
| ------------- | -------- | ---- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| path          | string   | 否   | -      | path 取值路径字符串                                                                                                                       |
| type          | string   | 否   | -      | 值类型 用于进行内部相关转换 date                                                                                                          |
| customFormat  | Function | 否   | -      | 自定义数据处理函数                                                                                                                        |
| customCompare | Function | 否   | -      | 自定义数据对比函数 (a, b)=>number，如果 a 小于 b，返回值为负数，如果 a 大于 b，返回值为正数，如果两个元素相等，返回值为 0。NaN 被视为 0。 |

- type 目前支持的类型: date