feat: 注释补齐

packages/common-widgets/utils/index.ts

@@ -13,10 +13,30 @@ export * from './locale';
 export * from './date';
 export * from './validator';
 
+/**
+ * 给值带上 px 的单位，有单位的值直接返回
+ * @desc {en} Add the unit of px to the number, and return it directly if there is a unit.
+ * @param {number | string} value 需要设置的值
+ * @param {number | string} value {en} The value that needs to be set
+ * @return {string} 返回带有单位的值
+ * @return {string} {en} Returns a value with units
+ */
 export function handleUnit(value: number | string) {
     return typeof value === 'number' || !isNaN(Number(value)) ? `${value}px` : value;
 }
 
+/**
+ * 基于给定的过滤函数返回一个过滤后的数组
+ * @desc {en} Returns a filtered array based on the given filter function
+ * @param {T[]} data 数据数组
+ * @param {T[]} data {en} data array
+ * @param {Function} filterFn 过滤函数
+ * @param {Function} filterFn {en} filter function
+ * @param {Object} options 可选对象
+ * @param {Object} options {en} Optional object
+ * @return {string} 过滤后的数组
+ * @return {string} filtered array
+ */
 export function arrayTreeFilter<T>(
     data: T[],
     filterFn: (item: T, level: number) => boolean,
@@ -46,6 +66,20 @@ export function arrayTreeFilter<T>(
     return result;
 }
 
+/**
+ * 使用了缓出（ease-out）的方式时返回在给定时间内根据缓动函数计算得到的新值
+ * @desc {en} When the ease-out method is used, the new value calculated according to the easing function is returned within a given time.
+ * @param {number} elapsed 持续时间
+ * @param {number} elapsed {en} duration
+ * @param {number} initialValue 初始值
+ * @param {number} initialValue {en} initial value
+ * @param {number} amountOfChange 变动系数
+ * @param {number} amountOfChange {en} coefficient of variation
+ * @param {number} duration 持续时间
+ * @param {number} duration {en} duration
+ * @return {number} 返回在给定时间内根据缓动函数计算得到的新值
+ * @return {number} {en} Returns the new value calculated from the easing function within the given time
+ */
 export function easeOutCubic(
     elapsed: number,
     initialValue: number,
@@ -57,8 +91,10 @@ export function easeOutCubic(
 }
 
 /**
- * 历史逻辑问题，轻喷 _(:з」∠)_
- * @desc {en} Please ignore this weird function _(:з」∠)_
+ * 在下一个事件循环周期执行给定的函数
+ * @desc {en} Execute the given function on the next event loop cycle
+ * @param {Function} func 执行的函数
+ * @param {Function} func {en} function executed
  */
 export function nextTick(func: () => void) {
     setTimeout(func, 20);
@@ -69,6 +105,12 @@ export function nextTick(func: () => void) {
  * @desc {en} To simulate the sliding damping effect, use the function x = X/(aX+b), where x is the element displacement, X is the sliding distance, and a and b are custom parameters obtained by setting the corresponding relationship between the two targets
  * 例如目标X=500时x=100, X=200时x=60，可得a,b
  * @desc {en} For example, when the target X=500, x=100, when X=200, x=60, you can get a,b
+ * @param {number} x 元素位移
+ * @param {number} x {en} element displacement
+ * @param {[number, number] | number} damping 阻尼参数
+ * @param {[number, number] | number} damping {en} Damping parameters
+ * @return {number} 返回需要滑动的距离
+ * @return {number} {en} Return the distance required to slide
  */
 export function fingerDisToLabelDis(x: number, damping?: [number, number] | number) {
     const dampArr = typeof damping === 'number' ? [damping] : damping;

packages/common-widgets/utils/is.ts

@@ -1,39 +1,125 @@
 const opt = Object.prototype.toString;
 
+/**
+ * 判断一个对象是否为数组类型
+ * @desc {en} Whether it is an array
+ * @param {any} obj 入参
+ * @param {any} obj {en} Entering
+ * @return {boolean} 返回是否为数组类型
+ * @return {boolean} {en} Returns whether it is an array type
+ */
 export function isArray(obj: any): obj is any[] {
     return opt.call(obj) === '[object Array]';
 }
 
+/**
+ * 判断一个对象是否为对象类型
+ * @desc {en} Whether it is an object
+ * @param {any} obj 入参
+ * @param {any} obj {en} Entering
+ * @return {boolean} 返回是否为对象类型
+ * @return {boolean} {en} Returns whether it is an object type
+ */
 export function isObject(obj: any): obj is { [key: string]: any } {
     return opt.call(obj) === '[object Object]';
 }
 
+/**
+ * 判断一个对象是否为字符串类型
+ * @desc {en} Whether it is an string
+ * @param {any} obj 入参
+ * @param {any} obj {en} Entering
+ * @return {boolean} 返回是否为字符串类型
+ * @return {boolean} {en} Returns whether it is an string type
+ */
 export function isString(obj: any): obj is string {
     return opt.call(obj) === '[object String]';
 }
 
+/**
+ * 检查一个值是否在给定的有效值列表中
+ * @desc {en} Checks whether a value is in the given list of valid values
+ * @param {T} value 检查的值
+ * @param {T} value {en} value to check
+ * @param {T[]} validList 有效值列表
+ * @param {T[]} validList {en} List of valid values
+ * @return {boolean} 返回要检查的值是否在有效值列表中
+ * @return {boolean} {en} Returns whether the value to be checked is in the list of valid values
+ */
 export function isOneOf<T>(value: T, validList: T[]) {
     return validList.indexOf(value) !== -1;
 }
 
+/**
+ * 检查一个值是否为空值
+ * @desc {en} Check if a value is null
+ * @param {any} obj 入参
+ * @param {any} obj {en} Entering
+ * @return {boolean} 返回该值是否为空值
+ * @return {boolean} {en} Returns whether the value is null
+ */
 export function isEmptyValue(obj: any): boolean {
     return obj === undefined || obj === null || obj === '';
 }
 
+/**
+ * 检查一个值是否为函数类型
+ * @desc {en} Check if a value is function
+ * @param {unknown} obj 入参
+ * @param {unknown} obj {en} Entering
+ * @return {boolean} 返回该值是否为函数
+ * @return {boolean} {en} Returns whether the value is function
+ */
 export function isFunction(obj: unknown): boolean {
     return Object.prototype.toString.call(obj).toLowerCase() === '[object function]';
 }
 
+/**
+ * 检查一个值是否为 null
+ * @desc {en} Check if a value is null
+ * @param {unknown} obj 入参
+ * @param {unknown} obj {en} Entering
+ * @return {boolean} 返回该值是否为 null
+ * @return {boolean} {en} Returns whether the value is null
+ */
 export function isNull(obj: unknown): boolean {
     return Object.prototype.toString.call(obj).toLowerCase() === '[object null]';
 }
+
+/**
+ * 检查一个值是否为 undefined
+ * @desc {en} Check if a value is undefined
+ * @param {unknown} obj 入参
+ * @param {unknown} obj {en} Entering
+ * @return {boolean} 返回该值是否为 undefined
+ * @return {boolean} {en} Returns whether the value is undefined
+ */
 export function isUndefined(obj: unknown): boolean {
     return Object.prototype.toString.call(obj).toLowerCase() === '[object undefined]';
 }
+
+/**
+ * 检查一个值是否为空数组
+ * @desc {en} Check if a value is an empty array
+ * @param {Array<unknown>} obj 入参
+ * @param {Array<unknown>} obj {en} Entering
+ * @return {boolean} 返回该值是否为空数组
+ * @return {boolean} {en} Returns whether the value is an empty array
+ */
 export function isEmptyArray(obj: Array<unknown>): boolean {
     return isArray(obj) && !obj?.length;
 }
 
+/**
+ * 深比较两个对象是否相等
+ * @desc {en} Check if a value is an empty array
+ * @param {any} obj 要比较的第一个对象
+ * @param {any} obj {en} the first object to compare
+ * @param {any} obj 要比较的第二个对象
+ * @param {any} obj {en} the second object to be compared
+ * @return {boolean} 返回两个对象是否相等
+ * @return {boolean} {en} Returns whether two objects are equal
+ */
 export function isDeepEqual(obj: any, sub: any): boolean {
     if (typeof obj !== 'object' || typeof sub !== 'object' || obj === null || sub === null) {
         return obj === sub;