@hzab/utils 1.1.2 → 1.1.4

package/src/upload/uploadUtils.ts

@@ -6,21 +6,69 @@ import { isBase64Str } from "../base64Str";
 import { mergeFileName, getFileName, getFileNameExt } from "../file/fileName";
 import { getFileTypeExt } from "../file/fileType";
 import { nanoidNumALetters } from "../nanoid";
+import { addQuery, searchToObj } from "../url";
+
+/** 预览配置（旧版 getPreviewUrl） */
+export interface IPreviewConfig {
+  /** 预览域名或路径前缀 */
+  url?: string;
+  /** 额外 query（不含 ?） */
+  query?: string;
+}
+
+/** getFileNameByFileObj 入参文件对象 */
+export interface IFileNameSource {
+  name?: string;
+  type?: string;
+  url?: string;
+  createTime?: string | number;
+}
+
+/** getFileNameByFileObj 配置项 */
+export interface IGetFileNameByFileObjOpt {
+  /** 是否开启 Hash 命名 */
+  useHashName?: boolean;
+  params?: {
+    /** 指定文件名 */
+    fileName?: string;
+    [key: string]: any;
+  };
+}
+
+/** 含 previewUrl / url 的文件类对象 */
+export interface IPreviewFileLike {
+  previewUrl?: string;
+  url?: string;
+  [key: string]: any;
+}
+
+/** mergePreviewConfig 配置项 */
+export interface IMergePreviewConfig {
+  /** 预览域名或路径前缀（有值才拼接） */
+  url?: string;
+  /** url 别名 */
+  baseUrl?: string;
+  /** query 对象，优先推荐 */
+  query?: Record<string, any>;
+  /** `?` 后的原始字符串（不含 ?），会先解析再与 query 合并；同名键以 query 为准 */
+  search?: string;
+}
 
 /**
  * 格式化 dir 字符串，必须为非 / 开头， /  结尾。如： test/
- * @param {*} dir
+ * @param dir
  * @returns
  */
-export const formatDirStr = function (dir) {
+export const formatDirStr = function (dir?: string | null): string | undefined {
   return dir?.replace(/^\/(.*)\/*$/, "$1").replace(/(.?=*)\/*$/, "$1/");
 };
 
 /**
  * 合并 dir 字符串
- * @param {*} dir
+ * @param dir1
+ * @param dir2
  */
-export const mergeDirStr = function (dir1, dir2) {
+export const mergeDirStr = function (dir1?: string | null, dir2?: string | null): string {
   return `${formatDirStr(dir1 || "")}${formatDirStr(dir2 || "")}`;
 };
 
@@ -30,8 +78,8 @@ export const mergeDirStr = function (dir1, dir2) {
  * @param maxCount
  * @returns
  */
-export function handleMaxCount(fileList, maxCount) {
-  let list = getArr(fileList);
+export function handleMaxCount<T>(fileList: T | T[] | null | undefined, maxCount?: number): T[] {
+  let list = getArr(fileList) as T[];
   if (maxCount > 0 && list.length > maxCount) {
     list = list.slice(0, maxCount);
   }
@@ -40,11 +88,11 @@ export function handleMaxCount(fileList, maxCount) {
 
 /**
  * 获取预览 url
- * @param {*} uri
- * @param {*} previewConfig
+ * @param uri
+ * @param previewConfig
  * @returns
  */
-export function getPreviewUrl(uri, previewConfig) {
+export function getPreviewUrl(uri: string, previewConfig?: IPreviewConfig): string {
   const isUriPattern = /http[s]?:\/\/[^\s]+/.test(uri);
   const query = previewConfig?.query ? "?" + previewConfig?.query : "";
 
@@ -60,8 +108,9 @@ export function getPreviewUrl(uri, previewConfig) {
  * 数据存储格式 ~k[key]-[data]~ 如： ~ktime-1743649562530~
  * key、data 中的 ~ 转为 _
  * @param file
+ * @param opt
  */
-export const getFileNameByFileObj = (file, opt: any) => {
+export const getFileNameByFileObj = (file: IFileNameSource, opt?: IGetFileNameByFileObjOpt): string => {
   const {
     useHashName = true,
     params: { fileName = "" } = {}, // 给 params 加默认空对象
@@ -75,8 +124,6 @@ export const getFileNameByFileObj = (file, opt: any) => {
   const _fileName = mainPart || _fullFileName || getFileName(file.url) || "file";
   const _ext = ext || getFileTypeExt(file.type);
 
-
-
   const hashStr = useHashName ? nanoidNumALetters() : "";
   const nm = mergeFileName(_fileName + "." + _ext, (_fileName.indexOf("~kid-") < 0 ? `~kid-${hashStr}-${file.createTime || dayjs().valueOf()}-${ext}` : ""));
 
@@ -84,13 +131,13 @@ export const getFileNameByFileObj = (file, opt: any) => {
 };
 
 /**
- * 解析
+ * 解析文件名中的 ~k[key]-[data]~ 键值对
  * @param url
  * @returns
  */
-export const getFileNameObj = function (url): any {
+export const getFileNameObj = function (url: string): Record<string, string> {
   const list = url.match(/~k([^-~]+)-([^~]*)~/g);
-  const res = {};
+  const res: Record<string, string> = {};
   list?.forEach((it) => {
     const arr = it?.match(/~k([^-~]+)-([^~]*)~/);
     if (arr?.length >= 3) {
@@ -101,11 +148,11 @@ export const getFileNameObj = function (url): any {
 };
 
 /**
- * 解析
- * @param url
+ * 将对象序列化为 ~k[key]-[data]~ 字符串
+ * @param obj
  * @returns
  */
-export function setFileNameObj(obj) {
+export function setFileNameObj(obj: Record<string, any>): string {
   return Object.keys(obj)
     .map((key) => {
       return `~k${key?.replace(/~/g, "_")}-${obj[key]?.toString()?.replace(/~/g, "_")}~`;
@@ -119,44 +166,67 @@ export function setFileNameObj(obj) {
  * @param key
  * @returns
  */
-export const getValByKey = function (url, key) {
+export const getValByKey = function (url: string, key: string): string | undefined {
   const reg = new RegExp(`~k${key?.replace(/~/g, "_")}-\([^~]*\)~`);
   return url.match(reg)?.[1];
 };
 
 /**
- * 预览 url 添加前缀
- * @param {*} uri
- * @param {*} conf
+ * 是否为无需再拼前缀的绝对/特殊地址
+ * @param uri
+ */
+function isAbsoluteOrSpecialUrl(uri?: string | null): boolean {
+  if (!uri) {
+    return false;
+  }
+  if (isBase64Str(uri)) {
+    return true;
+  }
+  // http(s)://、协议相对 //、data:、blob:
+  if (/^(https?:)?\/\//i.test(uri) || /^(data|blob):/i.test(uri)) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * 预览 url 添加前缀（仅用于预览展示，不应用于表单提交值）
+ * @param uri 相对路径、完整 url，或含 previewUrl/url 的文件对象
+ * @param conf
+ *   - url / baseUrl: 预览域名或路径前缀（有值才拼接）
+ *   - query: query 对象，优先推荐
+ *   - search: `?` 后的原始字符串（不含 ?），会先解析再与 query 合并；同名键以 query 为准
  * @returns
  */
-export function mergePreviewConfig(uri, conf) {
-  let _uri = uri;
-  let basePath = "";
-  if (typeof _uri === "object") {
-    basePath = _uri.basePath;
-    _uri = _uri.previewUrl || _uri.url;
+export function mergePreviewConfig(
+  uri: string | IPreviewFileLike | null | undefined,
+  conf?: IMergePreviewConfig,
+): string | undefined {
+  let _uri: string | undefined = typeof uri === "string" ? uri : undefined;
+  if (typeof uri === "object" && uri) {
+    _uri = uri.previewUrl || uri.url;
   }
   if (typeof _uri !== "string") {
     return _uri;
   }
-  _uri = _uri?.trim();
-  // base64 直接返回
-  if (isBase64Str(_uri)) {
+  _uri = _uri.trim();
+  if (!_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();
+  const baseUrl = (conf?.url ?? conf?.baseUrl)?.trim?.() || "";
+  const searchStr = conf?.search?.trim() || "";
+  const searchParams = searchStr ? searchToObj(`?${searchStr}`) || {} : {};
+  const query = conf?.query && typeof conf.query === "object" ? conf.query : {};
+  const queryParams = { ...searchParams, ...query };
+  const hasQuery = Object.keys(queryParams).length > 0;
+
+  let result = _uri;
+  // 已是完整/特殊地址：不二次拼前缀，仅按需挂 query
+  if (!isAbsoluteOrSpecialUrl(_uri) && baseUrl) {
+    // 仅当配置了有效前缀时才拼接，避免 conf 为空对象时拼出 "undefined/xxx"
+    result = `${baseUrl.replace(/\/$/, "")}/${_uri.replace(/^\//, "")}`.trim();
   }
 
-  return _uri;
+  return hasQuery ? addQuery(result, queryParams) : result;
 }

package/src/url.ts

@@ -1,134 +1,145 @@
-/**
- * 替换 search 字符串
- * @param url
- * @param search
- * @returns
- */
-export function replaceSearch(url, search) {
-  if (!url || typeof url !== "string") {
-    console.warn("Warn handleUrlQuery: 请传入正确的 url 字符串");
-    return url;
-  }
-  let _url = fixUrlQuery(url);
-
-  const hashIdx = _url.indexOf("#");
-  const queryIdx = _url.indexOf("?");
-  let hash = "";
-  let resUrl = _url;
-  if (queryIdx >= 0) {
-    resUrl = _url.slice(0, queryIdx);
-  }
-  if (hashIdx >= 0) {
-    hash = _url.slice(hashIdx);
-  }
-
-  resUrl += search?.indexOf("?") >= 0 ? "" : "?";
-  resUrl += search;
-  resUrl += hash;
-
-  return resUrl;
-}
-
-/**
- * 把对象转为 query 参数
- * @param query
- */
-export function objToSearch(query, hasQuery) {
-  if (!query || typeof query !== "object") {
-    console.warn("Warn objToSearch: 请传入正确的对象");
-    return;
-  }
-  let search = hasQuery ? "?" : "";
-  Object.keys(query).forEach((key) => {
-    if (search && search != "?") {
-      search += "&";
-    }
-    search += key;
-    search += "=";
-    search += query[key];
-  });
-  return search;
-}
-
-/**
- * 修复 query，解决 query 在 hash 后面的情况
- * @param url
- * @returns
- * 源数据：/#/login?a=1&b=2
- * 结果：/?a=1&b=2#/login
- */
-export function fixUrlQuery(url) {
-  if (!url || typeof url !== "string") {
-    console.warn("Warn handleUrlQuery: 请传入正确的 url 字符串");
-    return url;
-  }
-  const hashIdx = url.indexOf("#");
-  const queryIdx = url.indexOf("?");
-
-  // 双 query 情况
-  if (queryIdx < hashIdx) {
-    let hash = url.slice(hashIdx);
-    const hashQueryIdx = hash.indexOf("?");
-    if (hashQueryIdx >= 0) {
-      const _url = url.slice(0, queryIdx);
-      const urlQuery = url.slice(queryIdx, hashIdx)?.replace(/\/$/, "");
-      const hashQuery = hash.slice(hashQueryIdx)?.replace("?", "")?.replace(/\/$/, "");
-      hash = hash.slice(0, hashQueryIdx);
-      return `${_url}${urlQuery}&${hashQuery}${hash}`;
-    }
-    return url;
-  }
-
-  // query 在 hash # 之后
-  if (queryIdx >= 0 && hashIdx >= 0 && queryIdx > hashIdx) {
-    const hash = url.slice(hashIdx, queryIdx);
-    const search = url.slice(queryIdx);
-    return `${url.slice(0, hashIdx)}${search}${hash}`;
-  }
-  return url;
-}
-
-/**
- * 获取 url 中的 query 值的对象
- * @param query
- */
-export function searchToObj(url) {
-  if (!url || typeof url !== "string") {
-    console.warn("Warn getSearchParams: 请传入正确的 url 字符串.");
-    return;
-  }
-  let _url = fixUrlQuery(url)
-    // 解决 query 在 /# 之前导致 query 参数多了 / 的问题
-    .replace("/#", "#");
-  const queryIdx = _url.indexOf("?");
-  const hashIdx = _url.indexOf("#");
-  if (queryIdx < 0) {
-    return;
-  }
-  // 去除 hash 相关数据及 query 的 "?"
-  if (hashIdx >= 0 && queryIdx >= 0) {
-    _url = _url.slice(queryIdx + 1, hashIdx);
-  } else if (queryIdx >= 0) {
-    _url = _url.slice(queryIdx + 1);
-  }
-  const res = {};
-  _url.split("&")?.forEach((it) => {
-    const arr = it.split("=");
-    res[arr[0]] = arr[1];
-  });
-  return res;
-}
-
-/**
- * 添加 url 中的 query 的参数
- * @param url
- * @param params
- * @returns
- */
-export function addQuery(url, params) {
-  const newObj = { ...searchToObj(url), ...params }
-  return replaceSearch(url, objToSearch(newObj, !!params))
-}
-
-
-
+/**
+ * 替换 search 字符串
+ * @param url
+ * @param search
+ * @returns
+ */
+export function replaceSearch(url: string, search: string) {
+  if (!url || typeof url !== "string") {
+    console.warn("Warn replaceSearch: 请传入正确的 url 字符串");
+    return url;
+  }
+  const _url = fixUrlQuery(url);
+
+  const hashIdx = _url.indexOf("#");
+  const queryIdx = _url.indexOf("?");
+  let hash = "";
+  let resUrl = _url;
+  // 无 query 时也要截掉 hash，否则后面再拼 hash 会重复
+  if (queryIdx >= 0) {
+    resUrl = _url.slice(0, queryIdx);
+  } else if (hashIdx >= 0) {
+    resUrl = _url.slice(0, hashIdx);
+  }
+  if (hashIdx >= 0) {
+    hash = _url.slice(hashIdx);
+  }
+
+  resUrl += search?.indexOf("?") >= 0 ? "" : "?";
+  resUrl += search;
+  resUrl += hash;
+
+  return resUrl;
+}
+
+/**
+ * 把对象转为 query 参数
+ * @param query
+ */
+export function objToSearch(query, hasQuery) {
+  if (!query || typeof query !== "object") {
+    console.warn("Warn objToSearch: 请传入正确的对象");
+    return;
+  }
+  let search = hasQuery ? "?" : "";
+  Object.keys(query).forEach((key) => {
+    if (search && search != "?") {
+      search += "&";
+    }
+    search += key;
+    search += "=";
+    search += query[key];
+  });
+  return search;
+}
+
+/**
+ * 修复 query，解决 query 在 hash 后面的情况
+ * @param url
+ * @returns
+ * 源数据：/#/login?a=1&b=2
+ * 结果：/?a=1&b=2#/login
+ */
+export function fixUrlQuery(url) {
+  if (!url || typeof url !== "string") {
+    console.warn("Warn handleUrlQuery: 请传入正确的 url 字符串");
+    return url;
+  }
+  const hashIdx = url.indexOf("#");
+  const queryIdx = url.indexOf("?");
+
+  // 双 query 情况
+  if (queryIdx < hashIdx) {
+    let hash = url.slice(hashIdx);
+    const hashQueryIdx = hash.indexOf("?");
+    if (hashQueryIdx >= 0) {
+      const _url = url.slice(0, queryIdx);
+      const urlQuery = url.slice(queryIdx, hashIdx)?.replace(/\/$/, "");
+      const hashQuery = hash.slice(hashQueryIdx)?.replace("?", "")?.replace(/\/$/, "");
+      hash = hash.slice(0, hashQueryIdx);
+      return `${_url}${urlQuery}&${hashQuery}${hash}`;
+    }
+    return url;
+  }
+
+  // query 在 hash # 之后
+  if (queryIdx >= 0 && hashIdx >= 0 && queryIdx > hashIdx) {
+    const hash = url.slice(hashIdx, queryIdx);
+    const search = url.slice(queryIdx);
+    return `${url.slice(0, hashIdx)}${search}${hash}`;
+  }
+  return url;
+}
+
+/**
+ * 获取 url 中的 query 值的对象
+ * @param query
+ */
+export function searchToObj(url) {
+  if (!url || typeof url !== "string") {
+    console.warn("Warn getSearchParams: 请传入正确的 url 字符串.");
+    return;
+  }
+  let _url = fixUrlQuery(url)
+    // 解决 query 在 /# 之前导致 query 参数多了 / 的问题
+    .replace("/#", "#");
+  const queryIdx = _url.indexOf("?");
+  const hashIdx = _url.indexOf("#");
+  if (queryIdx < 0) {
+    return;
+  }
+  // 去除 hash 相关数据及 query 的 "?"
+  if (hashIdx >= 0 && queryIdx >= 0) {
+    _url = _url.slice(queryIdx + 1, hashIdx);
+  } else if (queryIdx >= 0) {
+    _url = _url.slice(queryIdx + 1);
+  }
+  const res = {};
+  _url.split("&")?.forEach((it) => {
+    const arr = it.split("=");
+    res[arr[0]] = arr[1];
+  });
+  return res;
+}
+
+/**
+ * 添加 url 中的 query 的参数
+ * @param url
+ * @param params
+ * @returns url string
+ */
+export function addQuery(url, params) {
+  const newObj = { ...searchToObj(url), ...params };
+  return replaceSearch(url, objToSearch(newObj, !!params));
+}
+
+/**
+ * 添加 url 中的 query 参数，返回 search
+ * @param url
+ * @param params
+ * @returns search string
+ */
+export function addSearch(url: string, params: Record<string, unknown>) {
+  const newObj = { ...searchToObj(url), ...params };
+  return objToSearch(newObj, !!params);
+}