@hzab/utils 0.0.1 → 1.0.0-beta

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hzab/utils",
-  "version": "0.0.1",
+  "version": "1.0.0-beta",
   "description": "utils",
   "main": "src",
   "scripts": {

package/src/base64Str.ts

@@ -0,0 +1,49 @@
+/**
+ * 是否是 base64 字符串
+ * @param {*} str
+ * @returns
+ */
+export const isBase64Str = function (str) {
+  if (typeof str !== "string") {
+    return false;
+  }
+  return /^data:\w+\/\w+;base64/i.test(str);
+};
+
+/**
+ * 从 base64 字符串获取文件类型
+ * @param base64Str
+ * @returns
+ */
+export function getFileTypeFromBase64(base64Str) {
+  if (!isBase64Str(base64Str)) {
+    return base64Str;
+  }
+  // 移除Base64前缀（如果存在）
+  const base64Data = base64Str.replace(/^data:.*;base64,/, "");
+
+  // 键值对调换：Base64前缀作为键，文件类型信息作为值
+  const prefixMap = {
+    JVBERi0: { type: "pdf", mimeType: "application/pdf" },
+    R0lGODdh: { type: "gif", mimeType: "image/gif" },
+    R0lGODlh: { type: "gif", mimeType: "image/gif" },
+    iVBORw0KGgo: { type: "png", mimeType: "image/png" },
+    "/9j/": { type: "jpeg", mimeType: "image/jpeg" },
+    SUQzB: { type: "mp4", mimeType: "video/mp4" },
+    AAAAGGZ0eXBpc29tAA: { type: "mpeg", mimeType: "audio/mpeg" },
+    UklGR: { type: "webp", mimeType: "image/webp" },
+    PD94bWwgdmVyc2lvbj0: { type: "xml", mimeType: "text/xml" },
+    PHN2ZyB4bWxucz0: { type: "svg", mimeType: "image/svg+xml" },
+    dGV4dCB4bWxucz0: { type: "txt", mimeType: "text/plain" },
+  };
+
+  // 使用Object.keys遍历所有前缀，一次循环完成检测
+  for (const prefix of Object.keys(prefixMap)) {
+    if (base64Data.startsWith(prefix)) {
+      return prefixMap[prefix];
+    }
+  }
+
+  // 未匹配到已知类型
+  return { type: "unknown", mimeType: "application/octet-stream" };
+}

package/src/blob.ts

@@ -0,0 +1,42 @@
+/**
+ * 通过 Blob 的文件签名判断文件类型
+ * @param {Blob} blob - 待检测的 Blob 对象
+ * @returns {Promise<string>} - 匹配的 MIME 类型或 'unknown'
+ */
+export async function getFileTypeFromBlob(blob: Blob): Promise<string> {
+  // 预设文件签名表（键：十六进制前缀，值：MIME类型）
+  const fileSignatures = {
+    "89504E47": "image/png",
+    FFD8FF: "image/jpeg",
+    "47494638": "image/gif",
+    "25504446": "application/pdf",
+    "504B0304": "application/zip", // ZIP 或 DOCX/XLSX 等基于 ZIP 的格式
+    "3C3F786D6C": "text/xml", // XML
+    "7B22": "application/json", // JSON（开头可能为 { 或 {"）
+    "25215053": "application/postscript", // PS
+    "494433": "audio/mpeg", // MP3
+    "0000001866747970": "video/mp4", // MP4（部分情况）
+  };
+
+  // 读取 Blob 的前 8 字节（足够覆盖大部分签名）
+  const buffer = await blob.slice(0, 8).arrayBuffer();
+  const uint8Array = new Uint8Array(buffer);
+
+  // 转换为十六进制字符串（大写）
+  let hex = "";
+  for (let i = 0; i < uint8Array.length; i++) {
+    const byte = uint8Array[i].toString(16).padStart(2, "0");
+    hex += byte.toUpperCase();
+  }
+
+  // 对比签名表（优先匹配长前缀）
+  const signatures = Object.keys(fileSignatures).sort((a, b) => b.length - a.length);
+  for (const signature of signatures) {
+    if (hex.startsWith(signature)) {
+      return fileSignatures[signature];
+    }
+  }
+
+  // 未匹配到已知类型
+  return "unknown";
+}

package/src/empty-val.ts

@@ -0,0 +1,40 @@
+export interface ICheckEmptyOpt {
+  /** 【废弃】空值占位符 */
+  emptyStr?: string;
+  /** 空值占位符 */
+  emptySymbol?: string;
+  checkEmptyArr?: boolean;
+}
+export interface IHandleEmptyValOpt extends ICheckEmptyOpt {}
+
+/**
+ * 空数据判断
+ * @param {*} val
+ * @param {*} opt
+ * @returns
+ */
+export function checkEmpty(val, opt: ICheckEmptyOpt = {}) {
+  const { checkEmptyArr = true } = opt || {};
+  if (val === "" || val === null || val === undefined) {
+    return true;
+  }
+  if (checkEmptyArr && Array.isArray(val) && Array.length === 0) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * 处理空数据显示占位符
+ * @param val
+ * @param opt
+ * @returns
+ */
+export const handleEmptyVal = (val, opt: IHandleEmptyValOpt = {}) => {
+  const { emptyStr = "--" } = opt || {};
+  const emptySymbol = opt?.emptySymbol ?? emptyStr;
+  if (checkEmpty(val, opt)) {
+    return emptySymbol;
+  }
+  return val;
+};

package/src/file/fileName.ts

@@ -1,3 +1,4 @@
+import dayjs from "dayjs";
 import { nanoidNumALetters } from "../nanoid";
 
 /**
@@ -62,6 +63,7 @@ export const mergeFileName = function (fileName, str = "") {
   }
   const name = fileName?.match(/([^\/]+?)\.[^\/]+$/)?.[1] || "";
   const suffix = fileName?.match(/[^\/]+?\.([^\/]+)$/)?.[1] || "";
+
   return `${name}${str ?? ""}.${suffix}`;
 };
 
@@ -71,5 +73,5 @@ export const mergeFileName = function (fileName, str = "") {
  * @returns
  */
 export const getUFileName = function (fileName) {
-  return mergeFileName(getFileName(fileName) || "rc-upload", "-" + `~kid-${nanoidNumALetters()}~` + `${Date.now()}`);
+  return mergeFileName(getFileName(fileName) || "up", "-" + `~kid-${nanoidNumALetters()}~`);
 };

package/src/string.ts

@@ -1,12 +1,3 @@
-/**
- * 是否是 base64 字符串
- * @param {*} str
- * @returns
- */
-export const isBase64Str = function (str) {
-  return /^data:\w+\/\w+;base64/i.test(str);
-};
-
 /**
  * 字符串中划线转为小驼峰
  * @param s
@@ -17,3 +8,24 @@ export const convertToCamelCase = function (s) {
     return letter.toUpperCase();
   });
 };
+
+/**
+ * 对象字符串转为对象
+ * @param objStr
+ */
+export const objStrToObj = function (objStr) {
+  let _objStr = objStr;
+  if (typeof _objStr === "object") {
+    return _objStr;
+  }
+  // 对象字符串 转为 对象
+  if (typeof _objStr === "string") {
+    _objStr = _objStr.trim();
+    if (/^\[.*\]$|^\{.*\}$/.test(_objStr)) {
+      try {
+        _objStr = JSON.parse(_objStr);
+      } catch (error) {}
+    }
+  }
+  return _objStr;
+};

package/src/upload/OfflineUpload.ts

@@ -1,3 +1,5 @@
+import dayjs from "dayjs";
+
 import { axios } from "@hzab/data-model";
 
 import { formatDirStr, mergeDirStr, getFileNameByFileObj } from "./uploadUtils";
@@ -102,7 +104,7 @@ export function getSignature(opt: IGetSignatureOpt = {}) {
     window._$offlineSignatureRes &&
     window._$offlineSignatureRes.data &&
     serverUrl + JSON.stringify(params) === window._$offlineSignatureRes.serverUrlParams &&
-    Date.now() - window._$offlineSignatureRes.__saveTime < window._$offlineSignatureRes.expireTimeMilles - 10000
+    dayjs().valueOf() - window._$offlineSignatureRes.__saveTime < window._$offlineSignatureRes.expireTimeMilles - 10000
   ) {
     return Promise.resolve(window._$offlineSignatureRes.data);
   }
@@ -128,7 +130,7 @@ export function getSignature(opt: IGetSignatureOpt = {}) {
           data: res?.data?.data,
         };
         if (window._$offlineSignatureRes) {
-          window._$offlineSignatureRes.__saveTime = Date.now();
+          window._$offlineSignatureRes.__saveTime = dayjs().valueOf();
           window._$offlineSignatureRes.serverUrlParams = serverUrl + JSON.stringify(params);
         }
         return window._$offlineSignatureRes.data;

package/src/upload/fileDataNormalization.ts

@@ -0,0 +1,281 @@
+/**
+ * 文件数据格式归一化
+ */
+import dayjs from "dayjs";
+
+import { nanoidNumALetters } from "../nanoid";
+import { objStrToObj } from "../string";
+import { isBase64Str, getFileTypeFromBase64 } from "../base64Str";
+import { getFileURL } from "../file/file";
+import { getFileType } from "../file/fileType";
+import { getUFileName, getFileName, getFullFileName, getFileExt } from "../file/fileName";
+import { getFileNameObj, mergePreviewConfig } from "./uploadUtils";
+
+/**
+ * 文件数据格式
+ */
+export interface IFile {
+  /** 唯一 id */
+  uid?: string;
+  /** 唯一 id */
+  id: string;
+  /** 文件地址 */
+  url: string;
+  /** 存储的文件地址 */
+  storeUrl: string;
+  /** 存储的文件名称 */
+  name?: string;
+  /** 存储的文件名称 */
+  filename?: string;
+  /** 上传的文件名称 */
+  originalFilename: string;
+  /** 基础路径 */
+  basePath?: string;
+  /** 存储路径 */
+  path?: string;
+  /** 文件后缀 */
+  ext?: string;
+  /** 文件类型 */
+  contentType: string;
+  /** 上传平台 */
+  platform: string;
+  /** 文件预览地址 */
+  previewUrl?: string;
+  /** 文件缩略图地址 */
+  thumbnailUrl?: string;
+  /** 文件类型 */
+  type: string;
+  /** 文件大小 */
+  size: number;
+  /** 原始 file 文件 */
+  originFileObj?: File;
+  /** 文件上传时间 */
+  createTime?: string;
+  /** 最后更新时间戳 */
+  lastModified?: number;
+}
+
+/**
+ * 数据处理配置项
+ */
+export interface INormalizationOpt {
+  /** 列表数据模式：数组 | 字符串 */
+  listMode: "array" | "jsonStr" | "splitStr";
+  /** 字符串列表数据模式下的分隔符 */
+  split: string;
+  /** 子项数据模式： 格式化对象 | file 文件格式 | url 地址 | JSON 序列化字符串 */
+  itemMode: "object" | "file" | "url" | "jsonStr";
+  /** 预览配置参数 */
+  previewConfig?: Object;
+  /** 设置预览 URL 的回调 */
+  getPreviewUrl?: (file, opt) => string;
+  /** 缩略图配置参数 */
+  thumbnailUrlConf?: Object;
+  /** 设置缩略图 URL 的回调 */
+  getThumbnailUrl?: (file, opt) => string;
+}
+
+/** 内部文件格式 */
+const fileTpl: IFile = {
+  uid: "",
+  id: "",
+  url: "",
+  storeUrl: "",
+  name: "",
+  filename: "",
+  originalFilename: "",
+  basePath: "",
+  path: "",
+  ext: "",
+  type: "",
+  contentType: "",
+  previewUrl: undefined,
+  size: undefined,
+  platform: undefined,
+  lastModified: undefined,
+  createTime: undefined,
+  originFileObj: undefined,
+};
+
+/**
+ * 文件数据格式归一化
+ */
+export const normalizationFileObj = (data: IFile, opt: INormalizationOpt) => {
+  if (!data) {
+    console.warn("Upload handleInputData 请传入正确的数据");
+    return data;
+  }
+  let file = {
+    ...fileTpl,
+  };
+  // 对象字符串 转为 对象
+  const _data = objStrToObj(data);
+  if (isBase64Str(_data)) {
+    // base64 格式
+    file.id = nanoidNumALetters();
+    file.uid = file.id;
+    file.url = _data;
+    file.storeUrl = _data;
+    file.name = file.id;
+    file.filename = file.name;
+    file.originalFilename = file.name;
+    // 根据 base64 数据获取文件类型
+    const typeObj = getFileTypeFromBase64(_data);
+    file.type = typeObj.mimeType;
+    file.ext = typeObj.type;
+  } else if (typeof _data === "string") {
+    // url 格式
+    const obj = getFileNameObj(_data);
+    file.id = obj?.id;
+    file.uid = file.id;
+    file.url = _data;
+    file.storeUrl = _data;
+    file.name = getFullFileName(file.url);
+    file.filename = file.name;
+    file.originalFilename = getFullFileName(file.url);
+    file.type = getFileType(file.url);
+    file.ext = getFileExt(file.url);
+  } else if (typeof _data === "object") {
+    const sourceData = _data.originFileObj || _data;
+    file.id = _data.id || _data.uid;
+    file.url = sourceData.url || sourceData.ossUrl;
+    file.storeUrl = file.url;
+    file.originalFilename = _data.originalFilename || getFullFileName(file.url) || _data.name;
+    file.name = _data.filename || _data.name || getFullFileName(file.url);
+    file.filename = file.name;
+    file.originFileObj = data instanceof File ? data : undefined;
+    file.lastModified = _data.lastModified;
+    file.basePath = _data.basePath;
+    file.path = _data.path;
+    file.ext = getFileExt(file.url);
+    file.type = _data.contentType || _data.type;
+    file.contentType = file.type;
+    file.size = _data.size;
+    file.platform = _data.platform;
+    file.createTime = _data.createTime;
+  }
+
+  if (!file.id) {
+    file.id =
+      file.uid ||
+      `${
+        getFileName(file.url || file.name || file.filename) || "rc-upload"
+      }-${dayjs().valueOf()}-${nanoidNumALetters()}`;
+  }
+  if (!file.name) {
+    file.name = file.id;
+  }
+  if (!file.filename) {
+    file.filename = file.name;
+  }
+  if (!file.storeUrl) {
+    file.storeUrl = file.url;
+  }
+
+  // 预览地址
+  if (!file.previewUrl) {
+    const { getPreviewUrl, previewConfig } = opt || {};
+    file.previewUrl = getPreviewUrl ? getPreviewUrl(file, opt) : mergePreviewConfig(file, previewConfig);
+  }
+  // 缩略图地址
+  if (!file.thumbnailUrl) {
+    const { getThumbnailUrl, thumbnailUrlConf } = opt || {};
+    file.thumbnailUrl = getThumbnailUrl ? getThumbnailUrl(file, opt) : mergePreviewConfig(file, thumbnailUrlConf);
+  }
+
+  return file;
+};
+
+/**
+ * 解析传入的文件列表数据
+ */
+export const parseFileList = (fileList, opt: INormalizationOpt) => {
+  if (!fileList) {
+    return [];
+  }
+
+  let _fileList = fileList;
+  const { listMode, split } = opt || {};
+
+  // splitStr jsonStr 模式下处理字符串
+  const isStr = typeof _fileList === "string";
+  if (isStr && listMode === "splitStr") {
+    // @ts-ignore
+    _fileList = _fileList?.split(split ?? ", ");
+  }
+
+  if (isStr && listMode === "jsonStr") {
+    _fileList = objStrToObj(_fileList);
+  }
+
+  const isArr = Array.isArray(_fileList);
+  // 统一成数组格式
+  if (_fileList !== null && _fileList !== undefined && !isArr) {
+    _fileList = [_fileList];
+  }
+
+  if (isArr) {
+    const arrRes = [];
+    _fileList.forEach((it) => {
+      const itRes = normalizationFileObj(it, opt);
+      itRes && arrRes.push(itRes);
+    });
+    return arrRes;
+  }
+  return _fileList;
+};
+
+/**
+ * 出参子项归一化
+ * 根据配置，将 对象 处理成所需格式
+ */
+export const formatFile = function (file, opt: INormalizationOpt) {
+  const { itemMode = "object" } = opt || {};
+  if (itemMode === "file") {
+    return file?.originFileObj || file;
+  }
+  if (itemMode === "object") {
+    return normalizationFileObj(file, opt);
+  }
+  if (itemMode === "jsonStr" && typeof file !== "string") {
+    const { originFileObj, ...jFile } = normalizationFileObj(file, opt);
+    return JSON.stringify({ ...jFile });
+  }
+  if (itemMode === "url") {
+    return typeof file === "string" ? file : file.originFileObj?.url || file?.url;
+  }
+  return file;
+};
+
+/**
+ * 出参 fileList 归一化
+ * 根据配置，将 对象 处理成所需格式
+ */
+export const formatFileList = function (fileList, opt: INormalizationOpt) {
+  if (!fileList) {
+    return undefined;
+  }
+
+  const { listMode, split } = opt || {};
+
+  let _fileList = fileList;
+  if (_fileList && !Array.isArray(_fileList)) {
+    _fileList = [fileList];
+  }
+
+  // 数组
+  if (listMode === "array") {
+    return _fileList?.map((it) => formatFile(it, opt));
+  }
+  // 序列化后的字符串
+  if (listMode === "jsonStr") {
+    return JSON.stringify(_fileList?.map((it) => formatFile(it, opt)));
+  }
+  // join 后的字符串
+  if (listMode === "splitStr") {
+    return _fileList
+      ?.map((it) => formatFile(it, opt))
+      .filter((it) => it)
+      .join(split ?? ", ");
+  }
+};

package/src/upload/ossUpload.ts

@@ -1,3 +1,5 @@
+import dayjs from "dayjs";
+
 import { axios } from "@hzab/data-model";
 import { formatDirStr, mergeDirStr, getFileNameByFileObj } from "./uploadUtils";
 
@@ -65,7 +67,7 @@ export function getSignature(opt: IGetSignatureOpt = {}) {
   if (
     window._$ossSignatureRes &&
     serverUrl === window._$ossSignatureRes.serverUrl &&
-    Date.now() - window._$ossSignatureRes.__saveTime < window._$ossSignatureRes.expireTimeMilles - 10000
+    dayjs().valueOf() - window._$ossSignatureRes.__saveTime < window._$ossSignatureRes.expireTimeMilles - 10000
   ) {
     return Promise.resolve(window._$ossSignatureRes);
   }
@@ -84,7 +86,7 @@ export function getSignature(opt: IGetSignatureOpt = {}) {
     .then((res) => {
       window._$ossSignatureRes = res?.data?.data ?? res?.data ?? res;
       if (window._$ossSignatureRes) {
-        window._$ossSignatureRes.__saveTime = Date.now();
+        window._$ossSignatureRes.__saveTime = dayjs().valueOf();
         window._$ossSignatureRes.serverUrl = serverUrl;
       }
       return window._$ossSignatureRes;

package/src/upload/uploadUtils.ts

@@ -1,7 +1,10 @@
+import dayjs from "dayjs";
+
 import { getArr } from "../array";
+import { isBase64Str } from "../base64Str";
 
+import { mergeFileName, getFileName } from "../file/fileName";
 import { nanoidNumALetters } from "../nanoid";
-import { mergeFileName, getFullFileName } from "../file/fileName";
 
 /**
  * 格式化 dir 字符串，必须为非 / 开头， /  结尾。如： test/
@@ -51,6 +54,30 @@ export function getPreviewUrl(uri, previewConfig) {
   return uri;
 }
 
+
+export const getFileNameExt = function (fileName,) {
+  const regex = /^(.*)\.([^.]+)$/;
+  const result = fileName.match(regex);
+  if (result) {
+    const [, mainPart, ext] = result;
+    return {
+      mainPart,
+      ext
+    }
+  }
+  return {
+    mainPart: fileName,
+    ext: ""
+  }
+};
+
+export const getFileTypeExt = function (type,) {
+  if (type.indexOf("/") >= 0) {
+    return type?.match(/[^\/]*\/([^\/]+)$/)?.[1]
+  };
+  return type;
+};
+
 /**
  * 根据 file 对象获取文件名称，文件名称包含：初始名称、类型
  * 数据存储格式 ~k[key]-[data]~ 如： ~ktime-1743649562530~
@@ -58,22 +85,31 @@ export function getPreviewUrl(uri, previewConfig) {
  * @param file
  */
 export const getFileNameByFileObj = (file, opt: any) => {
-  const { useHashName = true } = opt || {};
-  const _fileName = file.name || getFullFileName(file.url);
-  if (_fileName.indexOf("~kid-") >= 0 || !useHashName) {
+
+  const {
+    useHashName = true,
+    params: { fileName = "" } = {}  // 给 params 加默认空对象
+  } = opt || {};
+
+  const { mainPart,
+    ext } = getFileNameExt(file.name || "");
+
+  const type = ext || getFileTypeExt(file.type || file.contentType);
+
+  const _fileName = fileName || mainPart || getFileName(file.url) || "oss";
+
+  if (_fileName.indexOf("~kid-") >= 0) {
     return _fileName;
   }
-  // id、时间、文件类型
-  const id = file.id || file.uid || nanoidNumALetters();
-  return mergeFileName(
-    _fileName,
-    "-" +
-      setFileNameObj({
-        id,
-        time: file.createTime ?? Date.now(),
-        type: (file.type || file.contentType)?.replace("/", "_"),
-      }),
-  );
+
+  const objStr = setFileNameObj({
+    t: file.createTime || dayjs().valueOf(),
+    ext: file.ext || (file.type || file.contentType)?.replace("/", "_"),
+  });
+  const hashStr = useHashName ? `${nanoidNumALetters()}-` : "";
+  const nm = mergeFileName(_fileName + "." + type, `~kid-${hashStr}${objStr}`);
+
+  return nm
 };
 
 /**
@@ -116,3 +152,40 @@ export const getValByKey = function (url, key) {
   const reg = new RegExp(`~k${key?.replace(/~/g, "_")}-\([^~]*\)~`);
   return url.match(reg)?.[1];
 };
+
+/**
+ * 预览 url 添加前缀
+ * @param {*} uri
+ * @param {*} conf
+ * @returns
+ */
+export function mergePreviewConfig(uri, conf) {
+  let _uri = uri;
+  let basePath = "";
+  if (typeof _uri === "object") {
+    basePath = _uri.basePath;
+    _uri = _uri.previewUrl || _uri.url;
+  }
+  if (typeof _uri !== "string") {
+    return _uri;
+  }
+  _uri = _uri?.trim();
+  // base64 直接返回
+  if (isBase64Str(_uri)) {
+    return _uri;
+  }
+  const isUriPattern = /http[s]?:\/\/[^\s]+/.test(_uri);
+  const query = conf?.query?.trim() ? "?" + conf?.query?.trim() : "";
+
+  if (isUriPattern) {
+    // 源地址为 http 地址，直接拼接 query 参数
+    return `${_uri}${query}`;
+  }
+
+  if (conf) {
+    // 拼接前缀
+    return `${conf?.url?.trim()?.replace(/\/$/, "")}/${_uri?.trim()?.replace(/^\//, "")}${query}`?.trim();
+  }
+
+  return _uri;
+}