@base-web-kits/base-tools-ts 0.9.4 → 0.9.6

package/src/ts/url/oss/index.d.ts

@@ -0,0 +1,120 @@
+// 兼容oss后期添加的参数
+type OtherOption = Record<string, string | number | boolean | undefined>;
+
+export type OSSGravity = 'nw' | 'north' | 'ne' | 'west' | 'center' | 'east' | 'sw' | 'south' | 'se';
+
+export type OSSFormat = 'png' | 'jpg' | 'jpeg' | 'webp' | 'bmp' | 'gif' | 'tiff' | 'heic' | 'avif';
+
+export type OSSResizeOption = {
+  p?: number;
+  w?: number;
+  h?: number;
+  m?: 'lfit' | 'mfit' | 'fill' | 'pad' | 'fixed';
+  l?: number;
+  s?: number;
+  limit?: 1 | 0;
+  color?: string;
+} & OtherOption;
+
+export type OSSCropOption = {
+  w?: number;
+  h?: number;
+  x?: number;
+  y?: number;
+  g?: OSSGravity;
+  p?: number;
+} & OtherOption;
+
+export type OSSIndexCropOption = {
+  x?: number;
+  y?: number;
+  i?: number;
+} & OtherOption;
+
+export type OSSQualityOption = {
+  q?: number;
+  Q?: number;
+} & OtherOption;
+
+export type OSSWatermarkOption = {
+  type?: string;
+  text?: string;
+  size?: number;
+  color?: string;
+  shadow?: number;
+  t?: number;
+  g?: OSSGravity;
+  x?: number;
+  y?: number;
+  voffset?: number;
+  fill?: 0 | 1;
+  padx?: number;
+  pady?: number;
+  image?: string;
+  P?: number;
+} & OtherOption;
+
+export type OSSBlurOption = {
+  r: number;
+  s: number;
+  g?: 'face' | 'faces';
+  p?: number;
+} & OtherOption;
+
+export type OSSRoundedCornersOption = {
+  r: number;
+} & OtherOption;
+
+export type OSSCircleOption = {
+  r: number;
+} & OtherOption;
+
+export type OSSImgOption = {
+  resize?: OSSResizeOption;
+  watermark?: OSSWatermarkOption;
+  flip?: 0 | 1 | 2;
+  crop?: OSSCropOption;
+  quality?: OSSQualityOption;
+  format?: OSSFormat;
+  info?: boolean;
+  'auto-orient'?: 0 | 1;
+  circle?: OSSCircleOption;
+  indexcrop?: OSSIndexCropOption;
+  'rounded-corners'?: OSSRoundedCornersOption;
+  blur?: OSSBlurOption;
+  rotate?: number;
+  interlace?: 0 | 1;
+  'average-hue'?: boolean;
+  bright?: number;
+  sharpen?: number;
+  contrast?: number;
+} & {
+  [action: string]: number | string | boolean | Record<string, unknown> | undefined;
+};
+
+export type OSSVideoOption = {
+  convert?: Record<string, unknown>;
+  animation?: Record<string, unknown>;
+  sprite?: Record<string, unknown>;
+  snapshots?: Record<string, unknown>;
+  concat?: Record<string, unknown>;
+  info?: boolean;
+} & {
+  [action: string]: number | string | boolean | Record<string, unknown> | undefined;
+};
+
+export type OSSAudioOption = {
+  convert?: Record<string, unknown>;
+  concat?: Record<string, unknown>;
+  info?: boolean;
+} & {
+  [action: string]: number | string | boolean | Record<string, unknown> | undefined;
+};
+
+export type OSSHlsOption = {
+  m3u8?: boolean | Record<string, unknown>;
+} & {
+  [action: string]: number | string | boolean | Record<string, unknown> | undefined;
+};
+
+export type OSSOption = OSSImgOption | OSSVideoOption | OSSAudioOption | OSSHlsOption;

package/src/ts/url/oss/index.ts

@@ -0,0 +1,168 @@
+import type {
+  OSSOption,
+  OSSAudioOption,
+  OSSHlsOption,
+  OSSImgOption,
+  OSSVideoOption,
+  OSSWatermarkOption,
+} from './index.d';
+
+export * from './index.d';
+
+/**
+ * oss图片处理
+ * 参考官方文档: https://help.aliyun.com/zh/oss/user-guide/img-parameters/?spm=a2c4g.11186623.help-menu-31815.d_0_11_2_1.572824a1a1W5Pf&scm=20140722.H_144582._.OR_help-T_cn~zh-V_1
+ * @param src 原始图片URL
+ * @param option 图片处理选项
+ * @returns 处理后的图片URL（格式: `{src}?x-oss-process=image/xx`）
+ * @example
+ * 缩放: getOSSImg('xx.jpg', { resize: { w: 100, h: 100 } })
+ * 水印: getOSSImg('xx.jpg', { watermark: { text: '水印' } });
+ * 翻转: getOSSImg('xx.jpg', { flip: 1 });
+ * 裁剪: getOSSImg('xx.jpg', { crop: { w: 100, h: 100 } });
+ * 质量: getOSSImg('xx.jpg', { quality: { q: 80 } });
+ * 格式转换: getOSSImg('xx.jpg', { format: 'jpg' });
+ * 获取信息: getOSSImg('xx.jpg', { info: true });
+ * 自适应方向: getOSSImg('xx.jpg', { 'auto-orient': 1 });
+ * 内切圆: getOSSImg('xx.jpg', { circle: { r: 100 } });
+ * 索引切割: getOSSImg('xx.jpg', { indexcrop: { x: 100 } });
+ * 圆角: getOSSImg('xx.jpg', { 'rounded-corners': { r: 10 } });
+ * 模糊: getOSSImg('xx.jpg', { blur: { r: 10, s: 10 } });
+ * 旋转: getOSSImg('xx.jpg', { rotate: 90 });
+ * 渐进显示: getOSSImg('xx.jpg', { interlace: 1 });
+ * 主色调: getOSSImg('xx.jpg', { 'average-hue': true });
+ * 亮度: getOSSImg('xx.jpg', { bright: 10 });
+ * 锐化: getOSSImg('xx.jpg', { sharpen: 100 });
+ * 对比度: getOSSImg('xx.jpg', { contrast: 100 });
+ */
+export function getOSSImg(src: string, option: OSSImgOption) {
+  return buildOSSUrl(src, 'image', option);
+}
+
+/**
+ * oss视频处理
+ * 参考官方文档: https://help.aliyun.com/zh/oss/user-guide/audio-and-video-processing/
+ * @param src 原始视频URL
+ * @param option 视频处理选项
+ * @returns 处理后的URL（格式: `{src}?x-oss-process=video/xx`）
+ * @example
+ * 视频转码: getOSSVideo('xx.mp4', { convert: { format: 'mp4' } })
+ * 转为动图: getOSSVideo('xx.mp4', { animation: { format: 'gif' } })
+ * 雪碧图: getOSSVideo('xx.mp4', { sprite: { format: 'png' } })
+ * 多帧截取: getOSSVideo('xx.mp4', { snapshots: { count: 3 } })
+ * 视频拼接: getOSSVideo('xx.mp4', { concat: { list: 'a.mp4,b.mp4' } })
+ * 信息查询: getOSSVideo('xx.mp4', { info: true })
+ * 组合操作: getOSSVideo('xx.mp4', { convert: { format: 'mp4' }, snapshots: { count: 3 } })
+ */
+export function getOSSVideo(src: string, option: OSSVideoOption) {
+  return buildOSSUrl(src, 'video', option);
+}
+
+/**
+ * oss音频处理
+ * 参考官方文档: https://help.aliyun.com/zh/oss/user-guide/audio-and-video-processing/
+ * @param src 原始音频URL
+ * @param option 音频处理选项
+ * @returns 处理后的URL（格式: `{src}?x-oss-process=audio/xx`）
+ * @example
+ * 音频转码: getOSSAudio('xx.mp3', { 'convert': { format: 'mp3' } })
+ * 音频拼接: getOSSAudio('xx.mp3', { 'concat': { list: 'a.mp3,b.mp3' } })
+ * 信息查询: getOSSAudio('xx.mp3', { 'info': true })
+ */
+export function getOSSAudio(src: string, option: OSSAudioOption) {
+  return buildOSSUrl(src, 'audio', option);
+}
+
+/**
+ * oss直播处理（边转边播 HLS）
+ * 参考官方文档: https://help.aliyun.com/zh/oss/user-guide/audio-and-video-processing/
+ * @param src 原始视频URL
+ * @param option HLS 选项（或布尔）
+ * @returns 处理后的URL（格式: `{src}?x-oss-process=hls/xx`）
+ * @example
+ * 生成播放列表: getOSSHls('xx.mp4', { 'm3u8': true })
+ * 配置参数: getOSSHls('xx.mp4', { 'm3u8': { playlist: 1, segtime: 6 } })
+ */
+export function getOSSHls(src: string, option: OSSHlsOption) {
+  return buildOSSUrl(src, 'hls', option);
+}
+
+/**
+ * 构造oss处理地址
+ * @param src 原始地址
+ * @param type oss处理类型,如`image`, `audio`, `video`, `hls`
+ * @param option oss处理选项
+ * @returns 处理后的URL（格式: `{src}?x-oss-process={type}/{segs.join('/')}`）
+ */
+export function buildOSSUrl(src: string, type: string, option: OSSOption) {
+  if (!src || !option) return src;
+  if (src.startsWith('blob:')) return src;
+  if (src.includes('.svg')) return src;
+
+  const segs: string[] = [];
+
+  // 遍历选项,构造处理参数
+  for (const [k, v] of Object.entries(option)) {
+    const seg = k === 'watermark' ? getWatermark(v as OSSWatermarkOption) : getOSSSegs(k, v);
+    if (seg) segs.push(seg);
+  }
+
+  if (!segs.length) return src;
+
+  // 拼接处理参数(先移除查询参数,避免重复拼接)
+  const base = src.split('?')[0];
+  return `${base}?x-oss-process=${type}/${segs.join('/')}`;
+}
+
+/**
+ * 构造图片处理参数
+ * @param type 图片处理类型,如`resize`, `flip`, `format`, `info`
+ * @param option 图片处理选项
+ * @returns `object`返回格式为`resize,w_100,h_100`
+ * @returns `number`返回格式为`flip,1`
+ * @returns `string`返回格式为`format,jpg`
+ * @returns `true`返回格式为`info`, `false`返回空字符串
+ */
+function getOSSSegs(type: string, option?: Record<string, unknown> | number | string | boolean) {
+  if (!option && option !== 0) return '';
+
+  if (option === true) return type;
+
+  if (typeof option === 'number' || typeof option === 'string') return `${type},${option}`;
+
+  const segs = Object.entries(option)
+    .map(([k, v]) => `${k}_${v}`)
+    .join(',');
+
+  return segs ? `${type},${segs}` : '';
+}
+
+/**
+ * 图片水印 (文本和图片已Base64编码)
+ * @returns 格式: `watermark,text_xxx`
+ */
+function getWatermark(w?: OSSWatermarkOption) {
+  if (!w) return '';
+  if (w.image) w.image = toBase64Url(w.image);
+  if (w.text) w.text = toBase64Url(w.text);
+  if (w.type) w.type = toBase64Url(w.type);
+  return getOSSSegs('watermark', w);
+}
+
+/**
+ * Base64编码
+ */
+function toBase64Url(s: string) {
+  let b64 = '';
+  if (typeof Buffer !== 'undefined') {
+    const buf = Buffer.from(s, 'utf-8');
+    b64 = buf.toString('base64');
+  } else {
+    try {
+      b64 = btoa(unescape(encodeURIComponent(s)));
+    } catch {
+      b64 = '';
+    }
+  }
+  return b64.replace(/=+$/g, '').replace(/\+/g, '-').replace(/\//g, '_');
+}

package/src/ts/url/param/index.ts

@@ -0,0 +1,119 @@
+/**
+ * 获取url的查询参数值
+ * - 采用纯JS解析，因为小程序不支持URLSearchParams
+ * @param key 参数名
+ * @param url 完整 URL 或仅查询串（如 "a=1&b=2"）
+ * @returns 解码后的参数值 (若不存在|"null"|"undefined"，则返回 null)
+ * @example
+ * const q = getUrlParam('q', 'https://a.com/?q=%E6%B5%8B%E8%AF%95'); // "测试"
+ * const a = getUrlParam('a', 'a=1'); // "1"
+ * const list = getUrlParam('list', 'list=[1,2]'); // "[1,2]"
+ * const list = getUrlParam('list', 'list=null'); // null
+ * const list = getUrlParam('list', 'list=undefined'); // null
+ */
+export function getUrlParam(key: string, url: string) {
+  const raw = url.includes('?') ? url.slice(url.indexOf('?') + 1) : url.includes('=') ? url : '';
+  const qs = raw.split('#')[0];
+  if (!qs) return null;
+  const pairs = qs.split('&').filter(Boolean);
+  const decode = (s: string) => {
+    try {
+      return decodeURIComponent(s.replace(/\+/g, ' '));
+    } catch {
+      return s;
+    }
+  };
+  for (const pair of pairs) {
+    const i = pair.indexOf('=');
+    const k = i >= 0 ? pair.slice(0, i) : pair;
+    if (decode(k) === key) {
+      const v = i >= 0 ? decode(pair.slice(i + 1)) : '';
+      return v !== 'null' && v !== 'undefined' ? v : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * 获取url的查询参数值,并转为number类型
+ * @param key 参数名
+ * @param url 完整 URL 或仅查询串（如 "a=1&b=2"）
+ * @returns 解码后的参数值 (若不存在|"非数字字符串"，则返回 null)
+ * @example
+ * const a = getUrlNumber('a', 'https://a.com/?a=1'); // 1
+ * const a = getUrlNumber('a', 'a=1'); // 1
+ * const a = getUrlNumber('a', 'a=1.2'); // 1.2
+ * const a = getUrlNumber('a', 'a=abc'); // null
+ */
+export function getUrlNumber(key: string, url: string) {
+  const str = getUrlParam(key, url);
+  if (!str) return null;
+
+  const num = Number(str);
+  return isNaN(num) ? null : num;
+}
+
+/**
+ * 获取url的所有查询参数值
+ * - 采用纯JS解析，因为小程序不支持URLSearchParams
+ * @param url 完整 URL 或仅查询串（如 "a=1&b=2"）
+ * @returns 解码后的键值对象（无参数返回空对象; "null"|"undefined"的参数会被忽略）
+ * @example
+ * const params = getUrlParamAll('a=1&b=2'); // { a: "1", b: "2" }
+ * const params = getUrlParamAll('https://a.com/?a=1&b=2'); // { a: "1", b: "2" }
+ * const params = getUrlParamAll('a=1&b=null'); // { a: "1" }
+ * const params = getUrlParamAll('a=1&b=undefined'); // { a: "1" }
+ */
+export function getUrlParamAll(url: string) {
+  const raw = url.includes('?') ? url.slice(url.indexOf('?') + 1) : url.includes('=') ? url : '';
+  const qs = raw.split('#')[0];
+  const result: Record<string, string> = {};
+  if (!qs) return result;
+  const decode = (s: string) => {
+    try {
+      return decodeURIComponent(s.replace(/\+/g, ' '));
+    } catch {
+      return s;
+    }
+  };
+  for (const seg of qs.split('&')) {
+    if (!seg) continue;
+    const i = seg.indexOf('=');
+    const k = i >= 0 ? seg.slice(0, i) : seg;
+    const v = i >= 0 ? seg.slice(i + 1) : '';
+    const dv = decode(v);
+    if (dv !== 'null' && dv !== 'undefined') {
+      result[decode(k)] = dv;
+    }
+  }
+  return result;
+}
+
+/**
+ * 将对象参数拼接到 URL
+ * - 采用纯JS拼接，因为小程序不支持URLSearchParams
+ * @param url 基础地址
+ * @param param 将要追加的参数对象；`null/undefined` 值会被忽略，Object 会使用 `JSON.stringify`
+ * @returns 拼接后的完整 URL（保留原有哈希片段）
+ * @example
+ * const url = appendUrlParam('https://a.com', { q: '测试', list: [1, 2], a: null, b: undefined }); // 'https://a.com/?q=%E6%B5%8B%E8%AF%95&list=[1,2]'
+ */
+export function appendUrlParam(url: string, param: Record<string, unknown>) {
+  if (!param || typeof param !== 'object') return url;
+
+  const hashIndex = url.indexOf('#');
+  const baseWithoutHash = hashIndex >= 0 ? url.slice(0, hashIndex) : url;
+  const hash = hashIndex >= 0 ? url.slice(hashIndex) : '';
+
+  const [base, existingQs] = baseWithoutHash.split('?');
+  const parts: string[] = [];
+  if (existingQs) parts.push(existingQs);
+  for (const key in param) {
+    const rawVal = param[key];
+    if (rawVal === null || rawVal === undefined) continue;
+    const val = typeof rawVal === 'object' ? JSON.stringify(rawVal) : String(rawVal);
+    parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(val)}`);
+  }
+  const qs = parts.filter(Boolean).join('&');
+  return base + (qs ? `?${qs}` : '') + hash;
+}

package/src/ts/url/qn/index.d.ts

@@ -0,0 +1,103 @@
+type QnOtherOption = Record<string, string | number | boolean | undefined>;
+
+export type QnImageView2Option = {
+  mode?: 0 | 1 | 2 | 3 | 4 | 5;
+  w?: number;
+  h?: number;
+  l?: number;
+  limit?: 0 | 1;
+  q?: number;
+  format?: string;
+} & QnOtherOption;
+
+export type QnMogr2Option = {
+  thumbnail?: string;
+  crop?: string;
+  rotate?: number;
+  'auto-orient'?: boolean;
+  format?: string;
+  interlace?: 0 | 1;
+  background?: string;
+  q?: number;
+  blur?: string | { r: number; s: number };
+  colors?: number;
+} & QnOtherOption;
+
+export type QnWatermarkOption = {
+  type?: 'image' | 'text' | number;
+  image?: string;
+  text?: string;
+  font?: string;
+  fontsize?: number;
+  fill?: string;
+  gravity?: string;
+  dx?: number;
+  dy?: number;
+  dissolve?: number;
+} & QnOtherOption;
+
+export type QnImgOption = {
+  imageView2?: QnImageView2Option;
+  imageMogr2?: QnMogr2Option;
+  watermark?: QnWatermarkOption;
+  imageslim?: boolean;
+  imageInfo?: boolean;
+} & {
+  thumbnail?: string;
+  crop?: string;
+  rotate?: number;
+  'auto-orient'?: boolean;
+  format?: string;
+  interlace?: 0 | 1;
+  background?: string;
+  q?: number;
+  blur?: string | { r: number; s: number };
+  colors?: number;
+  [action: string]: number | string | boolean | Record<string, unknown> | undefined;
+};
+
+export type QnAvthumbOption = {
+  format?: string;
+  s?: string;
+  vcodec?: 'libx264' | 'libx265' | 'copy' | string;
+  vb?: string; // e.g. '1.25m', '128k', support '!'
+  r?: number; // frame rate
+  acodec?: 'libmp3lame' | 'libfdk_aac' | 'copy' | string;
+  ab?: string; // e.g. '128k', support '!'
+  ar?: number; // sampling rate
+} & QnOtherOption;
+
+export type QnVframeOption = {
+  format?: 'jpg' | 'png';
+  offset?: number; // seconds, support decimals
+  w?: number;
+  h?: number;
+} & QnOtherOption;
+
+export type QnVideoOption = {
+  avthumb?: QnAvthumbOption;
+  vframe?: QnVframeOption;
+} & {
+  [action: string]: number | string | boolean | Record<string, unknown> | undefined;
+};
+
+export type QnAudioOption = {
+  avthumb?: QnAvthumbOption;
+} & {
+  [action: string]: number | string | boolean | Record<string, unknown> | undefined;
+};
+
+export type QnHlsOption = {
+  level?: number; // e.g. 3 for 720p preset
+  format?: 'm3u8';
+  segtime?: number; // 2-10 seconds
+  t?: string; // duration like '1.500s'
+  vcodec?: 'libx264' | 'libx265' | 'copy' | string;
+  vb?: string; // bitrate e.g. '1.25m', '128k', support '!'
+  r?: number; // frame rate [1,60]
+  s?: string; // resolution '1280x720'
+  acodec?: 'libmp3lame' | 'libfdk_aac' | 'copy' | string;
+  ab?: string; // audio bitrate
+  ar?: number; // audio sampling rate
+  output?: string; // m3u8 filename (url-safe base64)
+} & QnOtherOption;