js-request-transform

简介

这是一个为前端使用的数据模型转换层/序列化层。可将后端返回的数据进行统一转换，成为前端方便使用的数据类，同时，也支持提交前将前端的数据反向转换，变成后端可接受的数据。

这两步操作由库封装好，前端只需要配置好对象，就可以直接使用了，用起来无需多个繁琐的步骤。

在我们开发CURD页面时，经常会遇到下面这几种情况，使用本库，可以帮你解决这些烦人的问题：

• 后端返回的某些数据不能直接在组件中使用，需要在设置到组件之前做一次转换。例如，后端接口的某个日期字段，格式是 YYYY-MM-DD 的字符串，在使用组件库时，组件需要传入一个 Date 对象。那么在常规方法中，我们需要在请求数据之后，赋值表单之前，需要手动将所有日期字段转为Date，然后在提交数据之前将所有Date转为YYYY-MM-DD 的字符串，再提交，比较麻烦。

  遇到上面这些情况，我可以使用本库的类型转换功能，在请求后端数据之后，把需要的字段转为我需要的类型，可以转为预设类型，也可以自定义处理，也可以多步流水线处理。

• 后端返回的字段有拼写错误，例如把 videoUrl 写成 vedioUrl （后端英语垃圾），我有强迫症，必须把它改过来。

• 后端的字段都是胡乱写的，例如 abc, x, y, dd, set，如果直接在UI中引用，把我前端的UI相关代码字段弄得乱七八糟的，搞不清楚哪个字段是什么意思，后期维护起来看得眼花缭乱。

• 后端特别喜欢胡乱改字段名称，偏偏这个字段被多个界面引用。例如：有多个界面显示了某个接口的 someString 属性，假如某一天后端吧字段名称 someString 改成了 thatString，那么我们在界面显示的地方也需要修改名称。以上情况如果只是一处两处还好，如果有好多地方都需要修改，那就非常麻烦了

  遇到上面这些情况，我就可以使用本库的字段映射功能，我可以将后端不好或者修改的字段名称映射到我自己的字段名称，前端逻辑和UI只需要引用这个字段，提交的时候会自动转为源字段，这样前端的命名就不会和后端过于耦合，就可以把后端不好的命名和习惯隔离在外！

• 后端返回的数据结构不统一，例如一个资源的接收/提交格式不一致，需要转换。例如：后端在拉取资源时返回了这种数据格式

  {
    "someKey": { "value": 1 },
  }

  但是提交资源时需要这种数据格式

  {
    "someKey": 1,
  }

  遇到上面这种情况，我可以在本库的模型定义中自定义转换格式或者转换器，所有使用到这个资源的数据转换都在一处完成，无需在每个UI中手动写多次转换代码，将转换代码与UI解耦。

• 后端返回一个大结构数据时有些时候居然会缺了几个字段，造成页面显示异常，居然甩锅给前端！

  遇到上面这种情况，我可以在本库的模型定义中，增加严格检查，遇到后端不传某些字段或者字段异常时抛出错误，精准定位哪个字段丢失。

*（关于上面几种情况的解决方法，请参考下方使用案例）

因此，本库就是为解决这些问题所写的，他的主要功能是：将数据转换单独抽离出来，可以统一在这里转换出结构清晰的数据供UI组件使用，而无需与UI组件耦合，无需再重复好几个地方写转换数据的代码。

也可以用来方式习惯不好的后端干扰我们前端的开发，将不好的东西隔离在外面！

主要的建议用法是：将其与您的 request/fecth 请求封装在一起，在请求/提交时自动转换相关数据，这样就无需在调用界面时还需要每个地方手动转换。

特性

• 支持数据双向转换，可以将数据从服务端返回的格式 》转为》 前端所需要的格式，又在提交时 从前端格式 》转为》 服务端需要的格式。
• 支持多种字段类型的转换（字符串、数字、布尔值，Date，dayjs，数组，对象）。
• 支持自定义转换器。
• 支持多转换器流水线转换。
• 支持数组、对象嵌套转换。
• 支持字段名称映射。
• 支持检查数据字段是否存在缺失，这在大量数据缺失某些字段排查时非常有用。

希望此库可以为你的开发带来帮助！

安装

npm i -S @imengyu/js-request-transform

使用方法

你可以将其与您的 request/fecth 请求封装在一起，在请求/提交时自动转换相关数据，这样就无需在调用界面时还需要每个地方手动转换。

基础使用案例

下面这个案例演示了数据双向转换与接口封装的功能。

使用方法简要概括是：

1. 首先定义模型
   1. 对于接口返回的一个资源，例如产品、分类，你可以使用一个数据模型（DataModel）来描述，数据模型可以嵌套（对于多个相似子对象可以独立模型然后作为子字段引用）。
   2. 根据你的严格要求，设置不同的转换策略
      1. 如果你只需要转换几个字段，不考虑整体数据检查安全，可以使用默认的转换策略或者 warning 开头的转换策略
      2. 如果你对所有字段有严格要求，需要每个字段格式全部正确，不能有任何字段缺失，可以使用 strict 开头的转换策略
2. 定义转换表。你可以参考下方示例代码设置直接需要转换的字段。
3. 定义字段。如果需要 TypeScript 定义或者是默认值，你还需要在 DataModel 上定义字段以及默认值。
4. 编写接口，你可以参考下方示例代码在自己的接口中加入转换入口，将后端返回/前端上传字段进行转换。

import { DataModel, transformDataModel } from '@imengyu/js-request-transform';

//这是我的数据模型定义
// ShopProduct
//  - ShopProductDetail
//商品
export class ShopProduct extends DataModel {
  constructor() {
    super();
    /**
     * 设置转换策略，支持多个 策略以满足您的使用需求。
     * * default 默认模式（松散模式）：对于在转换表中定义的字段，进行转换，如果转换失败不会给出警告，未在表中定义的字段数据按原样返回。
     * * strict-required 全部严格模式：在转换表中的字段，进行转换，如果未定义或者转换失败，则抛出异常。未在表中定义的数据会被忽略，不会写入对象。
     * * strict-provided 仅提供字段严格模式：在转换表中的字段同 strict-required，未在表中定义的字段数据按原样返回。
     * * warning 仅警告：同 default，但会在转换失败时给出警告。
     * * warning-required 警告：同 strict-required，但会在转换失败时给出警告而不是异常。
     * * warning-provided 警告：同 strict-provided，但会在转换失败时给出警告而不是异常。
     */
    this._convertPolicy = 'default';
    //定义转换表
    this._convertTable = {
      category: {
        /**
         * 这里对 category 字段进行处理的目的同简介中的[情况2]，
         * 因为返回数据时是一个对象，提交时只有一个id，我们不希望与UI界面处理的地方过于耦合，
         * 所以对界面只使用统一的 category_id ，在提交时自动处理。
         */
        customToClientFn: (v: KeyValue) => {
          this.category_name = v?.name as string || '';
          this.category_id = v?.id as number || 0;
          return undefined;
        },
        serverSide: 'undefined',
      },
      category_id: { serverSide: 'number' },
      category_name: { serverSide: 'undefined' },//服务器端用不到我们单独设置的category_name
      name: { clientSide: 'string', serverSide: 'string' },
      description: { clientSide: 'array', serverSide: 'string' },
      //这是[情况1]的解决方案，对传入传出的日期进行转换，这样在表单组件中可以直接使用 数据.startSolidDate 数据.endSolidDate 来设置日期，无需再手动转换
      startSolidDate: { clientSide: 'dayjs'， serverSide: 'string', clientSideDateFormat: 'YYYY-MM-DD', serverSideDateFormat: 'YYYY-MM-DD' },
      endSolidDate: { clientSide: 'dayjs'， serverSide: 'string', clientSideDateFormat: 'YYYY-MM-DD', serverSideDateFormat: 'YYYY-MM-DD' },
      //这是嵌套数组对象的情况，在类型是 'array' 或者 'object' 时，只需要提供 clientSideChildDataModel，转换时会自动递归转换成对应的类型。
      details: { clientSide: 'array', clientSideChildDataModel: ShopProductDetail, serverSide: 'array' },
    };
  }

  //下方是设置一些默认值，通常是你在创建一个新对象时这个对象所带有的默认值，这配合表单很好用，就无需为表单手动设置默认值了。
  //同时，定义字段后会有类型提示。
  name = '';
  description = '';
  category_id = null as null|number;
  category_name = '';
  startSolidDate = dayjs();
  endSolidDate = dayjs();
  details = [] as ShopProductDetail[];
}
//商品详情
//下面是作者工作项目中的一个示例
export class ShopProductDetail extends DataModel {
  constructor() {
    super();
    this._convertPolicy = 'default';
    this._blackList.toServer.push(
      'level_names',
    );
    this._convertTable = {
      name: { clientSide: 'string', serverSide: 'string' },
      description: { clientSide: 'array', serverSide: 'string' },
      //同上的category字段，为了统一获取与提交，界面只使用 level_ids。
      levels: {
        customToClientFn: (v: KeyValue[]) => {
          this.level_names = v?.map(k => k.name as string) || [];
          this.level_ids = v?.map(k => k.id as number) || [];
          return undefined;
        },
        serverSide: 'undefined',
      },
      //这里是为了: 作者公司项目后端上传图片是不一样的，获取的时候是完整的 URL （例如https://xxxx.com/aaaaa.png）, 提交的时候是
      //相对路径 （例如/aaaaa.png），所以我这里需要这样处理，把路径中的host去掉。
      //当然，如果你的数据也有不满足要求的地方，你也可以参考这个写法自定义处理数据。
      images: {
        customToServerFn(source: string[]) { return source.map(k => removeUrlOrigin(k)); },
        customToClientFn(source) { return source }
      },
    };
  }

  name = '';
  description = '';
  images = [] as string[];
  level_names = [] as string[];
  level_ids = [] as number[];
}

//这是接口定义
export class ShopApi {
  /**
    * 获取商品信息
    * @param id 商品信息id
    * @returns 
    */
  getShopProduct(id: number) : Promise<ShopProduct> {
    return axios.get(`/product/${id}`)
      //使用 transformDataModel 将源json数据转为我们需要的对象
      .then((d) => transformDataModel(ShopProduct, d.data))；

      //也可直接创建对象后转换
      //.then((d) => {
      //  return new ShopProduct().fromServerSide(d.data);
      //})；
  }
  /**
    * 更新商品信息
    * @param id 商品信息id
    * @param info 商品信息对象
    * @returns 
    */
  updateShopProduct(id: number, info: ShopProduct) : Promise<void> {
    //使用 toServerSide 将对象转为服务器可接受的格式
    return axios.post(`/product/${id}`, info.toServerSide());
  }
}

在实际页面中调用, 这里使用了 vue3 和 ant-desgin-vue。这只是一个展示数据转换使用的 Demo ，实际上的表单比这个复杂的多。

<template>
  <a-form
    :model="formState"
    name="basic"
    :label-col="{ span: 8 }"
    :wrapper-col="{ span: 16 }"
    autocomplete="off"
    @finish="onFinish"
    @finishFailed="onFinishFailed"
  >
    <a-form-item
      label="名称"
      name="name"
      :rules="[{ required: true, message: '请输入名称' }]"
    >
      <a-input v-model:value="formState.name" />
    </a-form-item>
    <a-form-item name="date-picker" label="开始售卖日期">
      <a-date-picker v-model:value="formState.startSolidDate" />
    </a-form-item>
    <a-form-item name="date-picker" label="停止售卖日期">
      <a-date-picker v-model:value="formState.endSolidDate" />
    </a-form-item>

    <!--篇幅有限，其他表单项未显示-->

    <a-form-item :wrapper-col="{ offset: 8, span: 16 }">
      <a-button type="primary" html-type="submit">提交</a-button>
    </a-form-item>
  </a-form>
</template>

<script setup lang="ts">
import { defineComponent, reactive, onMounted } from 'vue';
import { useRoute } from 'vue-router'
import { ShopApi, ShopProduct } from 'api/ShopApi'; //ShopApi 就是上面的文件

const formState = ref<ShopProduct>(new ShopProduct());

const route = useRoute();
const id = parseInt(route.query.id as string);

//加载数据
onMounted(() => {
  ShopApi.getShopProduct(id).then((res) => {
    formState.value = res; //因为经过转换，返回的res类型直接就是 ShopProduct, 无需特殊处理，表单组件可以直接使用
  }).catch((e) => {
    console.error('Failed:', e);
  })

  //上面是加载数据的情况，你可以仅使用 new ShopProduct() ，用作添加数据时的默认值。
  //这样 formState 的值就是你在 ShopProduct 中设置的默认值，表单组件中的值也是你设置的默认值。
  //提交也是一样的。
})

//提交
const async onFinish = () => {
  //提交时同样也无需再写转换，因为转换已经在 ShopProduct 中完成
  try {
    await ShopApi.updateShopProduct(id, formState);
  } catch (e) {
    console.error('Failed:', e);
  }
};
const onFinishFailed = (errorInfo: any) => {
  console.error('Failed:', errorInfo);
};
</script>

类型转换功能

基础类型转换

你可以在 _convertTable 中指定每个字段的转换目标格式，格式分为从服务端转为客户端（clientSide）和客户端转到服务端（serverSide）； 目标格式可以是内置的转换器，也可以是自定义注册的转换器。

this._convertTable = {
  stringToBoolean: { clientSide: 'boolean', serverSide: 'string' },
  stringToDate: { clientSide: 'date', serverSide: 'string' },
}

嵌套类型转换

字段可以是数组，数组中的元素可以是嵌套的模型对象。你只需要指定 clientSideChildDataModel 或者 serverSideChildDataModel，并 指定转换类型为 'array'，转换后目标字段中就是嵌套转换好的模型对象数组

this._convertTable = {
  keys: {
    clientSide: 'array',
    clientSideChildDataModel: PlayScriptProcessNodeKeyFrame,
    serverSide: 'undefined',
    serverSideRequired: false,
  },
}

同理字段可以是子对象，同样会为你自动嵌套转换好。

this._convertTable = {
  key: {
    clientSide: 'array',
    clientSideChildDataModel: ChildDataModel,
    serverSide: 'undefined',
    serverSideRequired: false,
  },
}

多转换器

一个字段可以由多个转换器逐步转换，这可以实现很多功能。例如下方示例先将输入的字符串转为 Date 对象， 如果转换失败或者源对象未提供，则调用 addDefaultValue 默认转换器添加默认值。

• addDefaultValue 处于多转换器数组第一个时，字段空预检会跳过。

this._convertTable = {
  createDate: [
    {
      clientSide: 'date',
    },
    {
      clientSide: 'addDefaultValue',
      clientSideParam: {
        defaultValue: new Date(),
      } as ConverterAddDefaultValueParams
    },
  ],
}

回调指定转换器

当多个字段都要使用相同的转换配置时，一个个在 _convertTable 中指定会比较麻烦， 因此提供了 _convertKeyType 回调用于根据字段名称批量返回转换配置功能。

this._convertKeyType = (key, direction) => {
  if (direction === 'client' && key.startsWith('date')) {
    return {
      clientSide: 'date', serverSide: 'string'
    }
  }
};

自定义转换器

你可以注册自己的转换器步骤，实现更多的功能。

例如，下方是一个将数值乘或者除指定倍数的转换器（已内置到库中），他满足了后端数据与前端UI组件显示数值倍数不一样的问题。

import { DataConverter } from '';

DataConverter.registerConverter({
  targetType: 'multiple',
  key: 'Multiple',
  converter(source, key, type, childDataModel, dateFormat, required, _params, options, debugKey, debugName)  {
    const params = _params as unknown as ConverterMultipleParams;
    return DataConverter.makeSuccessConvertResult(params.type === 'divide' ? 
      (source as number / params.multiple) :
      (source as number * params.multiple)
    );
  },
});

字段映射功能

字段映射功能用于将后端的字段映射到前端自己写的、语义明确的字段名上面。

可以使用 _nameMapperServer 或者 _nameMapperClient 设置单个方向的名称映射。

this._nameMapperServer = {
  'ename': 'eventName',
};

也可以使用 setNameMapper 函数设置双向的转换。

this.setNameMapper({
  'ename': 'eventName',
});

严格检查功能

你可以设置严格模式，用于严格字段检查和转换。在严格模式下会检查缺失的字段，或者传入类型不正确的字段。

• strict-required 全部严格模式：在转换表中的字段，进行转换，如果未定义或者转换失败，则抛出异常。未在表中定义的数据会被忽略，不会写入对象。
• strict-provided 仅提供字段严格模式：在转换表中的字段同 strict-required，未在表中定义的字段数据按原样返回。

this._convertPolicy = 'strict-required';

自定义转换功能

有多个回调函数允许进行自定义转换。

export class ShopProductDetail extends DataModel {
  constructor() {
    super();
    this._convertPolicy = 'default';
    this._blackList.toServer.push(
      'level_names',
    );
    this._convertTable = {
      name: { clientSide: 'string', serverSide: 'string' },
      description: { clientSide: 'array', serverSide: 'string' },
      //同上的category字段，为了统一获取与提交，界面只使用 level_ids。
      levels: {
        customToClientFn: (v: KeyValue[]) => {
          this.level_names = v?.map(k => k.name as string) || [];
          this.level_ids = v?.map(k => k.id as number) || [];
          return undefined;
        },
        serverSide: 'undefined',
      },
      //这里是为了: 作者公司项目后端上传图片是不一样的，获取的时候是完整的 URL （例如https://xxxx.com/aaaaa.png）, 提交的时候是
      //相对路径 （例如/aaaaa.png），所以我这里需要这样处理，把路径中的host去掉。
      //当然，如果你的数据也有不满足要求的地方，你也可以参考这个写法自定义处理数据。
      images: {
        customToServerFn(source: string[]) { return source.map(k => removeUrlOrigin(k)); },
        customToClientFn(source) { return source }
      },
    };
  }

  name = '';
  description = '';
  images = [] as string[];
  level_names = [] as string[];
  level_ids = [] as number[];
}

API 参考

接口参考

DataModel

实例属性

|参数|说明|类型|默认值| |--|--|--|--| |_dontSendToServerIfEmpty|设置是否 子字段参数为空，则不传值至服务器|boolean|false| |_afterSolveServer|从服务端转换后的后处理回调|function|-| |_afterSolveClient|从本地端转换后的后处理回调。data 是最终转为服务器端的数据，可自由修改。|(data: KeyValue) => void|-| |_defaultDateFormat|统一设置默认的日期格式|string|-| |_convertTable|数据字段转换表。key类中的为属性名称，值是转换信息。|Record<string,DataConvertItem> |-| |_convertKeyType|自定义字段转换类型，这在对象的属性个数不确定时很有用。此函数返回的类型优先级比 _convertTable 高。|(key: string, direction: ConverterDataDirection) => DataConvertItem|-| |_nameMapperServer|字段的名称映射表(服务端至客户端)，左边是服务端名称，右边是客户端名称。效果：服务端字段是 a ，客户端转换 a 之后会把它 赋值到名称为 b 的属性。|{ [index: string]: string }|-| |_nameMapperClient|字段的名称映射表(客户端至服务端)，左边是客户端名称，右边是名称服务端。效果：客户端字段是 a ，转换 a 到服务端数据之后会把它 赋值到名称为 b 的属性。|{ [index: string]: string }|-| |_convertPolicy|转换策略。|ConvertPolicy|-| |_blackList|字段黑名单表。黑名单中的字段不会被转换也不会被拷贝至目标中。分为：到服务器的黑名单与到前端的黑名单|{ toServer: string[] toClient: string[] }|-| |_lastServerSideData|获取上次创建的服务端原始数据|ConvertPolicy|-|

实例方法

getLastServerSideData() : KeyValue|null

同 _lastServerSideData，但此函数会创建一个克隆版本。

keyValue() : KeyValue

获取模型数据为纯JSON（不包括隐藏属性，函数等）。

rawData() : KeyValue|null

同 getLastServerSideData。

fromServerSide(data : KeyValue|null|undefined, nameKeySup?: string) : DataModel

从服务端数据创建前端使用的数据模型。

|参数|说明|类型|默认值| |--|--|--|--| |data|服务端数据|KeyValueornullorundefined|-| |nameKeySup|键值前缀，用于调试|string|-|

toServerSide(nameKeySup?: string) : DataModel

转换当前数据模型为服务端格式。

|参数|说明|类型|默认值| |--|--|--|--| |nameKeySup|键值前缀，用于调试|string|-|

clone()

克隆一份。

set(key: string, value: unknown)

在实例上通过字符串设置或增加对象中的属性。

访问路径支持：

• 支持点 “.” 表示子级属性。
• 支持数组 “[x]” 表示数组的第 x 个数据。

例如：a.listData[0].title

|参数|说明|类型|默认值| |--|--|--|--| |key|访问路径|string|-| |value|值|unknown|-|

get(key: string, defaultValue?: unknown): unknown

在实例上获取属性。

访问路径支持：

• 支持点 “.” 表示子级属性。
• 支持数组 “[x]” 表示数组的第 x 个数据。

|参数|说明|类型|默认值| |--|--|--|--| |key|访问路径|string|-| |defaultValue|默认值|unknown|-|

转换表

转换表 _convertTable 的 key 是属性的名称，value 是转换数据：DataConvertItem

DataConvertItem：

|参数|说明|类型|默认值| |--|--|--|--| |serverSide|指定当前key转为服务端的数据类型|string| |serverSideRequired|指定当前key是否是必填，逻辑如图同 _convertPolicy 设置为 *-required 时。|boolean| |serverSideDateFormat|当前key类型是dayjs时，自定义日期格式|string| |serverSideChildDataModel|当 serverSide 为 array/object 时，子项目要转换成的类型|(new () => DataModel)orstring| |customToServerFn|自定义前端至服务端转换函数，指定此函数后 serverSide 属性无效|DataConvertCustomFn| |clientSide|指定当前key是否是必填，逻辑如图同 _convertPolicy 设置为 *-required 时。|boolean| |clientSideRequired|指定当前key转为前端时的数据类型|string| |clientSideDateFormat|当前key类型是dayjs时，自定义日期格式|string| |serverSideChildDataModel|当 clientSide 为 array/object 时，子项目要转换成的类型|(new () => DataModel)orstring| |customToClientFn|自定义服务端至前端转换函数，指定此函数后 clientSide 属性无效|DataConvertCustomFn| |forceApply|设置强制转换字段名。默认情况下源数据中没有的字段不会调用转换器，如果你需要为不存在的字段设置默认值或者调用指定自定义转换器，可以使用此功能强制调用转换器，搭配 addDefaultValue 转换器。为字段设置转换器。当处于数组转换器中时，只判断第一个的 forceApply 值。默认：false|booleanorundefined|

DataConvertCustomFn

|参数|说明|类型|默认值| |--|--|--|--| |source|源数据|unknown|-| |item|当前转换表条目|DataConvertItem|-| |source|其他参数|ConvertItemOptions|-| |返回|转换完成的数据|unknown|-|

ConvertPolicy

转换模式

• default 默认模式（松散模式）：对于在转换表中定义的字段，进行转换，如果转换失败不会给出警告，未在表中定义的字段数据按原样返回。
• strict-required 全部严格模式：在转换表中的字段，进行转换，如果未定义或者转换失败，则抛出异常。未在表中定义的数据会被忽略，不会写入结果。
• strict-provided 仅提供字段严格模式：在转换表中的字段同 strict-required，未在表中定义的字段数据按原样返回。
• warning 仅警告：同 default，但会在转换失败时给出警告。
• warning-required 警告：同 strict-required，但会在转换失败时给出警告而不是异常。
• warning-provided 警告：同 strict-provided，但会在转换失败时给出警告而不是异常。

DataConverter

转换器构建方法。

configDayJsTimeZone

设置 dayjs 默认时区

参考 https://dayjs.gitee.io/docs/zh-CN/plugin/timezone

|参数|说明|类型|默认值| |--|--|--|--| |timezone|时区名称|string|-|

registerConverter

注册一个自定义数据转换器。

支持注册自定义类型转换器，在转换一个字段时，会依次调用转换器，如果有一个转换器转换成功，则停止转换。先注册的优先级最高。

|参数|说明|类型|默认值| |--|--|--|--| |config|转换器数据|ConverterConfig|-|

ConverterConfig

|参数|说明|类型|默认值|必填| |--|--|--|--|--| |targetType|当前转换器所接受的源数据类型|string|-|是| |key|唯一键值，用于取消注册，不提供的话则无法移除。|string|-|-| |preRequireCheckd|当转换策略是必填时，此回调用于自定义类型检测是否提供。|function|-|是| |converter|转换器主体函数|ConverterHandler|-|是|

preRequireCheckd 回调定义

|参数|说明|类型| |--|--|--| |source|源数据|unknown| |返回|返回为 undefined 时表示无错误，其他情况表示错误信息|unknown|

ConverterHandler 定义

|参数|说明|类型| |--|--|--| |source|源数据|unknown| |key|当前处理数据的完整键值，用于调试|string| |type|转换类型|string| |childDataModel|子数据的类型|(new () => DataModel)orstringornullorundefined| |dateFormat|当前字段的日期格式，可能为空，为空时可使用 options.defaultDateFormat|string| |required|是否有必填标志|boolean| |options|其他附加属性|ConvertItemOptions|

ConvertItemOptions

|参数|说明|类型| |--|--|--| |direction|当前模型的转换方向|ConverterDataDirection| |defaultDateFormat|当前模型的默认日期格式|string| |policy|当前模型的转换策略|ConvertPolicy|

unregisterConverter

取消注册指定的数据转换器

|参数|说明|类型|默认值| |--|--|--|--| |key|转换器注册时提供的key|string|-| |targetType|转换器目标类型|string|-|

makeSuccessConvertResult

在自定义转换器中返回成功结果。

|参数|说明|类型|默认值|必填| |--|--|--|--|--| |res|返回结果|unknown|-|是|

makeFailConvertResult

在自定义转换器中返回失败结果。

|参数|说明|类型|默认值|必填| |--|--|--|--|--| |error|错误信息|string or Error|-|否|

transformDataModel

用于从服务端转为客户端数据，同 new DataModel().fromServerSide(source)。

|参数|说明|类型|默认值| |--|--|--|--| |c|需要转换的目标类型|(new () => T) or FastTemplateDataModelDefine|-| |source|源数组|KeyValue|-| |userOptions|源数组|其他转换自定义配置|-|

返回：T

transformArrayDataModel

用于从服务端转为客户端数据，将数组转为模型数组。

|参数|说明|类型|默认值| |--|--|--|--| |c|需要转换的目标类型|new () => T|-| |source|源数组|KeyValue[]|-| |userOptions|源数组|其他转换自定义配置|-|

返回：T[]

transformWithConverter

用于从服务端转为客户端数据，将JSON数据根据转换器名称转为指定数据模型或者基本类型。

|参数|说明|类型|默认值| |--|--|--|--| |converterName|转换器名称|string|-| |source|源数据实例|any|-| |sourceKeyName|标识数据名称，用于异常显示|string|'root'| |arrayChildDataModel|当是数组或者集合等嵌套对象时，指定子对象的数据类型|ChildDataModel|undefined| |defaultDateFormat|默认日期格式|string|'YYYY-MM-DD HH:mm:ss'| |defaultConvertPolicy|默认转换策略|ConvertPolicy|'strict-required'| |userOptions|源数组|其他转换自定义配置|-|

内置转换类型定义

这些内置注册都可以取消注册，除特殊说明，他们的键值是 Default[TypeName] ，例如 undefined 的取消注册键值是 DefaultUndefined。

• undefined 相当于黑名单，永远都会转换为 undefined 。
• null 强制转换为 null 。
• string 转换为字符串。
• number 转换为数字类型。
• boolean 转换为布尔值类型。
• object 转换为对象。 可以指定 clientSideChildDataModel 或者 serverSideChildDataModel 来指定此对象要强制转为那个数据模型。 如果源对象是空数组，则转换为 null，其他类型无法转换。
• array 转换为数组，源对象必须是数组类型。 可以指定 clientSideChildDataModel 或者 serverSideChildDataModel 来指定此数组的每个子条目要强制转为那个数据模型。
• date 转换为 Date。
  • 如果输入是字符串，则会尝试使用日期格式进行转换。
  • 如果输入是数值时间戳，则会使用 new Date(time) 进行转换。
• json 转换为JSON数组，不进行内置递归对象处理。
• dayjs 转换为dayjs对象。
• addDefaultValue 用于当转换值为空时添加默认值，参数类型定义是 ConverterAddDefaultValueParams ，取消注册键值是 AddDefaultValue。
• multiple 乘或者除倍数转换器，参数类型定义是 ConverterMultipleParams ，取消注册键值是 Multiple。