@d-matrix/utils 1.25.0 → 1.27.0

package/dist/algorithm/binary.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 二分查找target 在arr中的索引
+ * @param arr
+ * @param target
+ * @param forward true 向前取值，false
+ * @param backward true 向后取值，false
+ */
+export declare const binarySearchIndex: <T>(arr: T[], target: T, forward?: boolean, backward?: boolean) => number;

package/dist/algorithm/binary.js

@@ -0,0 +1,38 @@
+// 二分
+/**
+ * 二分查找target 在arr中的索引
+ * @param arr
+ * @param target
+ * @param forward true 向前取值，false
+ * @param backward true 向后取值，false
+ */
+export const binarySearchIndex = (arr, target, forward = false, backward = false) => {
+    let low = 0;
+    let high = arr.length - 1;
+    let result = -1; // 如果找不到，返回-1
+    while (low <= high) {
+        const mid = Math.floor((low + high) / 2);
+        if (arr[mid] === target) {
+            return mid; // 找到目标值，返回索引
+        }
+        else if (arr[mid] < target) {
+            low = mid + 1;
+        }
+        else {
+            high = mid - 1;
+        }
+        if (forward) {
+            // 向前取值
+            if (arr[mid] < target) {
+                result = mid;
+            }
+        }
+        else if (backward) {
+            // 向后取值
+            if (arr[mid] > target) {
+                result = mid;
+            }
+        }
+    }
+    return result;
+};

package/dist/algorithm/index.d.ts

@@ -1 +1,2 @@
 export * as tree from './tree';
+export * as binary from './binary';

package/dist/algorithm/index.js

@@ -1 +1,2 @@
 export * as tree from './tree';
+export * as binary from './binary';

package/dist/algorithm/tree.d.ts

@@ -31,3 +31,4 @@ export declare const findParent: <T extends Record<string, any>>(tree: T | undef
  * @returns 节点路径
  */
 export declare function findPath<T extends Record<string, any>>(tree: T[], func: (node: T) => boolean, childrenKey?: string): T[] | null;
+export declare function flatten<T extends Record<string, any>>(tree: T[], childrenKey?: string): Record<string, any>[];

package/dist/algorithm/tree.js

@@ -1,3 +1,14 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 /**
  * 计算指定层级的节点数量
  * @param root tree data 对象
@@ -95,3 +106,19 @@ export function findPath(tree, func, childrenKey = 'children') {
     }
     return null;
 }
+export function flatten(tree, childrenKey = 'children') {
+    const result = [];
+    function traverse(node) {
+        // 将当前节点添加到结果数组
+        const _a = node, _b = childrenKey, __ = _a[_b], nodePropsOmitChildren = __rest(_a, [typeof _b === "symbol" ? _b : _b + ""]);
+        result.push(nodePropsOmitChildren);
+        const children = node[childrenKey];
+        // 如果节点有子节点，则递归处理每个子节点
+        if (children && Array.isArray(children) && children.length > 0) {
+            children.forEach((child) => traverse(child));
+        }
+    }
+    // 遍历树的每个根节点
+    tree.forEach((root) => traverse(root));
+    return result;
+}

package/dist/array.d.ts

@@ -2,3 +2,4 @@ export declare function moveMutable<T>(array: T[], fromIndex: number, toIndex: n
 export declare function moveImmutable<T>(array: T[], fromIndex: number, toIndex: number): T[];
 export declare function moveToStart<T>(array: T[], predicate: (item: T) => boolean): T[];
 export declare const moveMulti: <T extends unknown>(arr: T[], indexes: number[], start: number) => T[];
+export declare const getArrayOrUndefined: <T>(array?: T[] | null | undefined) => T[] | undefined;

package/dist/array.js

@@ -31,3 +31,7 @@ export const moveMulti = (arr, indexes, start) => {
     cloned.splice(start, 0, ...els);
     return cloned.filter((v) => v !== removeSymbol);
 };
+export const getArrayOrUndefined = (array) => {
+    if (Array.isArray(array) && array.length > 0)
+        return array;
+};

package/dist/color.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 将十六进制颜色转换为 RGBA 颜色
+ * @param hex 十六进制颜色
+ * @param alpha 透明度，默认值为 1
+ * @returns RGBA 颜色
+ */
+export declare function hexToRGBA(hex: string, alpha?: number | string): string;

package/dist/color.js

@@ -0,0 +1,41 @@
+/**
+ * 将十六进制颜色转换为 RGBA 颜色
+ * @param hex 十六进制颜色
+ * @param alpha 透明度，默认值为 1
+ * @returns RGBA 颜色
+ */
+export function hexToRGBA(hex, alpha = 1) {
+    // 移除井号并转为小写
+    const processedHex = hex.replace(/^#/, '').toLowerCase();
+    // 验证十六进制字符合法性
+    if (!/^[0-9a-f]+$/.test(processedHex)) {
+        throw new Error('Invalid hex character(s)');
+    }
+    // 验证长度合法性
+    if (![3, 6].includes(processedHex.length)) {
+        throw new Error('Hex must be 3 or 6 characters long');
+    }
+    // 扩展三位缩写为六位
+    const fullHex = processedHex.length === 3
+        ? processedHex
+            .split('')
+            .map((c) => c + c)
+            .join('')
+        : processedHex;
+    // 解析颜色通道
+    const parseChannel = (start, end) => parseInt(fullHex.substring(start, end), 16);
+    const r = parseChannel(0, 2);
+    const g = parseChannel(2, 4);
+    const b = parseChannel(4, 6);
+    // 处理透明度
+    const numericAlpha = Number(alpha);
+    if (isNaN(numericAlpha)) {
+        throw new Error('Alpha must be a valid number');
+    }
+    if (numericAlpha < 0 || numericAlpha > 1) {
+        throw new Error('Alpha must be between 0 and 1');
+    }
+    // 标准化输出格式
+    const formattedAlpha = numericAlpha % 1 === 0 ? numericAlpha.toFixed(0) : numericAlpha.toFixed(2).replace(/0+$/, '').replace(/\.$/, '');
+    return `rgba(${r}, ${g}, ${b}, ${formattedAlpha})`;
+}

package/dist/file.js

@@ -109,6 +109,8 @@ export function download(source, fileName = '', target) {
             link.target = target;
         }
         else {
+            // https://stackoverflow.com/questions/33909763/download-attribute-with-a-file-name-not-working
+            // download 只在同源 URL 或 blob:、data: 协议起作用, 如果下载不同源的oss文件，download属性无效
             link.download = fileName;
         }
         link.href = source;

package/dist/index.d.ts

@@ -13,3 +13,4 @@ export * as object from './object';
 export * as echarts from './echarts';
 export * as array from './array';
 export * as number from './number';
+export * as color from './color';

package/dist/index.js

@@ -13,3 +13,4 @@ export * as object from './object';
 export * as echarts from './echarts';
 export * as array from './array';
 export * as number from './number';
+export * as color from './color';

package/dist/react/index.d.ts

@@ -9,3 +9,4 @@ export * from './types';
 export * from './useForwardRef';
 export * from './useIsomorphicLayoutEffect';
 export * from './useMediaQuery';
+export * from './useIsFirstRender';

package/dist/react/index.js

@@ -9,3 +9,4 @@ export * from './types';
 export * from './useForwardRef';
 export * from './useIsomorphicLayoutEffect';
 export * from './useMediaQuery';
+export * from './useIsFirstRender';

package/dist/react/useIsFirstRender.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 使用 useIsFirstRender 区分第一次和后续渲染
+ * useIsFirstRender 对于确定当前渲染是否是组件的第一个渲染很有用。当你想在初始渲染时有条件地执行某些逻辑或渲染特定组件时，这个钩子特别有价值，提供了一种有效的方法来区分第一次和后续渲染。
+ * @returns boolean true 表示第一次渲染，false 表示其他渲染
+ */
+export declare function useIsFirstRender(): boolean;

package/dist/react/useIsFirstRender.js

@@ -0,0 +1,14 @@
+import { useRef } from 'react';
+/**
+ * 使用 useIsFirstRender 区分第一次和后续渲染
+ * useIsFirstRender 对于确定当前渲染是否是组件的第一个渲染很有用。当你想在初始渲染时有条件地执行某些逻辑或渲染特定组件时，这个钩子特别有价值，提供了一种有效的方法来区分第一次和后续渲染。
+ * @returns boolean true 表示第一次渲染，false 表示其他渲染
+ */
+export function useIsFirstRender() {
+    const renderRef = useRef(true);
+    if (renderRef.current === true) {
+        renderRef.current = false;
+        return true;
+    }
+    return renderRef.current;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@d-matrix/utils",
   "sideEffects": false,
-  "version": "1.25.0",
+  "version": "1.27.0",
   "description": "A dozen of utils for Front-End Development",
   "main": "dist/index.js",
   "scripts": {

package/readme.md

@@ -22,6 +22,7 @@ A dozen of utils for Front-End Development
 - [array](#array)
 - [number](#number)
 - [echarts](#echarts)
+- [color](#color)
 
 ### clipboard
 
@@ -198,6 +199,10 @@ export default function Component() {
 }
 ```
 
+- `useIsFirstRender(): boolean`
+
+对于确定当前渲染是否是组件的第一个渲染很有用。当你想在初始渲染时有条件地执行某些逻辑或渲染特定组件时，这个 hook 特别有价值，提供了一种有效的方法来区分第一次和后续渲染。
+
 ### dom
 
 - `scrollToTop(element: Element | null | undefined): void`
@@ -424,6 +429,10 @@ const actual = tree.findPath([root], (node) => node.id === 33);
 expect(actual).to.be.deep.equal([root, root.children[1], root.children[1].children[2]]);
 ```
 
+- `tree.flatten(tree, T[], childrenKey = 'children')`
+
+扁平化树结构, 返回的每个节点没有`children`属性
+
 ### file
 
 - `toImage(file: BlobPart | FileURL, options?: BlobPropertyBag): Promise<HTMLImageElement>`
@@ -615,6 +624,10 @@ const newList = array.moveToStart(list, (item) => item.id === 4);
 
 移动多个元素到数组中指定的位置,用法,见[测试用例](tests/algorithm.cy.ts)
 
+- `getArrayOrUndefined<T>(array?: T[] | undefined | null): T[] | undefined`
+
+如果`array`是数组且不为空,返回该数组，否则返回`undefined`,见[测试用例](tests/array.cy.ts)
+
 ## number
 
 - `randomInt(min: number, max: number): number`
@@ -637,6 +650,12 @@ deep merge Echarts配置，用法见[测试用例](./tests//echarts/echarts.cy.t
 
 计算echarts YAxis的max和min属性，以达到根据实际数据动态调整，使折线图的波动明显。且第一个点始终在Y轴中间位置，[效果图](https://raw.githubusercontent.com/mrdulin/pic-bucket-01/master/Dingtalk_20240724140535.jpg)
 
+## color
+
+- `hexToRGBA(hex: string, alpha: number | string = 1): string`
+
+将十六进制颜色转换为 RGBA 颜色, 见[测试用例](./tests/color.cy.ts)
+
 ## 测试
 
 运行全部组件测试