@hzab/utils 1.1.1 → 1.1.3

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;
 }