@acimini/cm-utils 中文文档教程

Question

CmUtils

CmUtils 是一个库，包含一些用于管理对象和数组的实用函数。\ 有了这个库，我们有：

• functions and pipes that check if an element is undefined, null or empty (they work on objects, arrays and variables)
• function to merge two objects or two arrays
• function to clone an object
• functions to remove duplicates in an array and check if two elements are equal
• function to convert a json (maybe from an api) to a specific typescript class and vice versa
• functions to find, update and remove properties deep into an object

这是基于：

• Angular 9

Index

1. Install
2. How to use
3. Utility functions
   • isUndefined
   • isNull
   • isNil
   • isEmpty
   • isNilty
   • merge
   • cloneClass
   • isEqual
   • uniqueBy
   • deserialize
   • serialize
   • deepFind
   • deepUpdate
   • deepRemove
4. Pipes
5. Authors
6. License

Install

npm install @acimini/cm-utils --save

在你的应用程序

import { CmUtilsModule } from '@acimini/cm-utils';

@NgModule({
  imports: [ CmUtilsModule ],
  ...
})

How to use

First define your model

 import {CmUtilsProperty} from '@acimini/cm-utils';

 class SubClassName {
   @CmUtilsProperty(String) subkey1: string;
   @CmUtilsProperty(Boolean) subkey2: boolean;
 }

 class ClassName {
   @CmUtilsProperty(String) key1: string;
   @CmUtilsProperty(SubClassName) key2: SubClassName;
   @CmUtilsProperty(Number) key3: number;
   @CmUtilsProperty(String) key4: string[];
   @CmUtilsProperty(SubClassName) key5: SubClassName[];
 }

中导入 CmUtilsProperty 装饰器中的第一个参数告诉实用程序函数属性的类型是什么.\ 在比较打字稿类型和装饰器类型的表格下方：

Decorator type	TypeScript type
String	string
Number	number
Boolean	boolean
ClassName	ClassName
Any	any
Multi	multi types
Tuple	tuple types

Multi types

多类型用于那些可以同时具有多种类型的变量。 例如，可以是字符串或数字的变量。\ 在这种情况下，模型定义将是

 import {CmUtilsProperty, Multi} from '@acimini/cm-utils';

 class ClassName {
   @CmUtilsProperty(new Multi(String, Number)) key1: string | number;
 }

Tuple types

元组类型，这些变量是具有定义数量的不同类型元素的数组。 例如，一个变量是一个数组，第一个元素为字符串，第二个元素为数字。\ 在这种情况下，模型定义将

 import {CmUtilsProperty, Tuple} from '@acimini/cm-utils';

 class ClassName {
   @CmUtilsProperty(new Tuple(String, Number)) key1: [string, number];
 }

Use utility functions

 import {CmUtilsService} from '@acimini/cm-utils';

 const firstObj = new ClassName();
 const secondObj = new ClassName();
 ...

 const newObj = CmUtilsService.mergeObj(firstObj, secondObj);
 ...

Utility functions

isUndefined

检查元素是否未定义。

 const elem = new ClassName();
...
 CmUtilsService.isUndefined(elem) 

如果未定义则返回 true，否则返回 false

isNull

检查元素是否为 null。

 const elem = new ClassName();
...
 CmUtilsService.isNull(elem) 

如果它为 null，则返回 true，否则返回 false

isNil

检查元素是否为 null 或未定义。

 const elem = new ClassName();
...
 CmUtilsService.isNil(elem) 

如果未定义或为 null，则返回 true，否则返回 false

isEmpty

检查元素是否为空。 它可以与字符串、数组和对象一起使用。

 const elem = new ClassName();
...
 CmUtilsService.isEmpty(elem) 

如果它为空则返回 true，否则返回 false

isNilty

检查元素是否为 null 或 undefined 或为空。 它可以与字符串、数组和对象一起使用。

 const elem = new ClassName();
...
 CmUtilsService.isNilty(elem)

如果它是未定义的或 null 或空的，它返回 true，否则返回 false

merge

合并两个项目（数组或对象）。

 const firstItem: ClassName = new ClassName();
 const secondItem: ClassName = new ClassName();
...
 CmUtilsService.merge(firstItem, secondItem)

它将第一项合并到第二项中。

array merge strategy

默认情况下，数组被合并到目标数组中，将那些在源数组中但不在目标数组中的元素推送到目标数组中。 例如：

[1,3,5] merge into [1,2,3] become [1,2,3,5]

可以通过两种方式改变这种行为：

• passing a merger function as third parameter in merge method
• passing a merger function into CmUtilsProperty decorator

在这两种情况下合并函数必须以这种方式定义：

function merger (item, sourceArray, destinationArray) {
    // do something 
}

如果我们调用 merge 方法合并两个数组，或者我们想要合并两个对象并对数组的所有属性应用相同的合并策略，则第一种情况很有用。

function merger (item, sourceArray, destinationArray) {
    // do something 
}

CmUtilsService.merge(firstArray, secondArray, merger)

如果我们想要合并两个对象并对不同的属性应用不同的合并策略，则第二种情况很有用。

class ClassName {
   @CmUtilsProperty(String) key1: string;
   @CmUtilsProperty(Number) key2: number;
   @CmUtilsProperty(String, {arrayMerger: merger}) key3: string[];
 }

function merger (item, sourceArray, destinationArray) {
    // do something 
}

const firstObject: ClassName = new ClassName();
const secondObject: ClassName = new ClassName();

CmUtilsService.merge(firstObject, secondObject)

可以将自定义合并定义为合并方法的第三个参数，并将其他合并定义为装饰器中的属性。\ 在这种情况下，将使用第一次合并，直到该属性没有自己的为止。

cloneClass

克隆具有特定类的对象。 \ 可以将不同的类作为第二个参数传递。 如果未提供，则克隆的对象将具有与用于克隆的对象相同的类。

 const obj: ClassName = new ClassName();
...
 CmUtilsService.cloneClass(obj, optionalClass)

它返回克隆的对象。

注意：当用于克隆的类比结果对象的类具有更多或更少的属性时，第二个参数很有用，并且共同的属性具有相同的类型。 这意味着如果共同的属性具有不同的类型，则此方法无用（对于这种情况，请检查序列化程序方法）。

isEqual

检查两个项目是否相等。

 const firstElem: ClassName = new ClassName();
 const secondElem: ClassName = new ClassName();
...
 CmUtilsService.isEqual(firstElem, secondElem)

如果元素相等则返回 true，否则返回 false。

uniqueBy

检查数组中的重复项并将其删除。 \ 可以使用函数来定义用于删除相等元素的策略（例如，我们希望删除对特定键具有相同值的元素）。 如果未提供，将使用默认值，并且仅删除完全相等的元素。

 const array: ClassName[] = [];
...
 CmUtilsService.uniqueBy(array, optionalFunction)

deserialize

将 json 转换为特定类（它也可用于将类转换为另一个类）。

 const json = {};
...
 CmUtilsService.deserializer(json, ClassName)

它返回反序列化的对象。

property decorator configuration

如果 json 中的属性与 ClassName 中的属性相同（对于名称和类型）装饰器配置是默认配置：

 class ClassName {
   @CmUtilsProperty(String) key1: string;
 }

如果 json 中的属性具有不同的类型或名称或两者，装饰器配置将是：

 class ClassName {
   @CmUtilsProperty(String, undefined, {propertyType: Number, propertyKey: 'key1different'}) key1: string;
 }

propertyType 定义类型，propertyKey 定义 json 对象中属性的名称。 \ 如果 propertyType 不是原始类型（请参阅如何使用 部分中的表格），或者有必要这样做转换值的一些操作，可以定义自定义转换器。 \

 class ClassName {
   @CmUtilsProperty(String, undefined, {propertyType: Number, converter: new NumberToStringConverter()}) key1: string;
 }

其中 converter 必须以这种方式定义：

class NumberToStringConverter implements CustomConverter<String> {
  serialize(data: String): any {
  }

  deserialize(data: any): String {
    return data.toString().replace('.', ',');
  }

}

每个 converter 必须实现 CustomConverter 接口并且必须有两个方法：

• serialize (see serialize section)
• deserialize

deserialize 方法< /strong> 获取属性的 json 值并返回转换后的值。

注意：转换器也可以在数组和对象类型属性上定义。 \ 在这种情况下，相同的转换器应用于没有自己的转换器的数组/对象的每个元素/属性。

serialize

将特定类转换为 json。

 class ClassName {
  ...   
 }
...
 CmUtilsService.serializer(ClassName)

它返回序列化的 json。

property decorator configuration

如果 ClassName 中的属性与 json 中的属性相同（名称和类型），则装饰器配置为默认配置：

 class ClassName {
   @CmUtilsProperty(String) key1: string;
 }

如果 ClassName 中的属性具有不同的类型或名称或两者，装饰器配置将是：

 class ClassName {
   @CmUtilsProperty(String, undefined, {propertyType: Number, propertyKey: 'key1different'}) key1: string;
 }

propertyType 定义类型，propertyKey 定义 json 对象中属性的名称。 \ 如果 propertyType 不是原始类型（请参阅如何使用 部分中的表格），或者有必要这样做转换值的一些操作，可以定义自定义转换器。 \

 class ClassName {
   @CmUtilsProperty(String, undefined, {propertyType: Number, converter: new NumberToStringConverter()}) key1: string;
 }

其中 converter 必须以这种方式定义：

class NumberToStringConverter implements CustomConverter<Number> {
  serialize(data: String): Number {
    return Number(data.replace(',', '.'));
  }

  deserialize(data: Number): String {
    return undefined;
  }

}

每个 converter 必须实现 CustomConverter 接口并且必须有两个方法：

• serialize
• deserialize (see deserialize section)

serialize 方法< /strong> 获取属性的 ClassName 值并返回转换后的值。

注意：转换器也可以在数组和对象类型属性上定义。 \ 在这种情况下，相同的转换器应用于没有自己的转换器的数组/对象的每个元素/属性。

deepFind

给定一个对象，返回特定路径处的属性值。

 const obj = new ClassName();
...
 CmUtilsService.deepFind(obj, 'path.to.key')

注意：路径必须从对象的根开始，每一层必须用点分隔。 \ 对于数组，键是元素的索引。

deepUpdate

给定一个对象，更新特定路径处的属性值。

 const obj = new ClassName();
...
 CmUtilsService.deepUpdate(obj, 'path.to.key', newValue)

注意：路径必须从对象的根开始，每一层必须用点分隔。 \ 对于数组，键是元素的索引。

deepRemove

给定一个对象，删除特定路径处的属性。

 const obj = new ClassName();
...
 CmUtilsService.deepRemove(obj, 'path.to.key')

注意：路径必须从对象的根开始，每一层必须用点分隔。 \ 对于数组，键是元素的索引。

Pipes

该库还提供以下管道：

• isUndefined: check if element is undefined
• isNull: check if element is null
• isNil: check if element is null or undefined
• isEmpty: check if element is empty
• isNilty: check if element is null or undefined or empty

Authors

• Andrea Cimini

License

该项目已获得 Apache License 2.0 许可 - 有关详细信息，请参阅 LICENSE.md 文件。