@cloudcome/utils-browser 1.1.1 → 1.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudcome/utils-browser",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "cloudcome utils for browser",
   "engines": {
     "node": ">=22"
@@ -102,10 +102,16 @@
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "dependencies": {
-    "@cloudcome/utils-core": "1.1.1"
+    "@cloudcome/utils-core": "~1.2.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloudcome/utils.git"
   },
-  "repository": "https://github.com/cloudcome/utils",
   "keywords": [
     "utils",
     "cloudcome",

package/CHANGELOG.md

@@ -1,27 +0,0 @@
-# Change Log
-
-All notable changes to this project will be documented in this file.
-See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
-
-## [1.1.1](https://github.com/cloudcome/utils/compare/@cloudcome/utils-browser@1.1.0...@cloudcome/utils-browser@1.1.1) (2025-08-30)
-
-**Note:** Version bump only for package @cloudcome/utils-browser
-
-# 1.1.0 (2025-08-27)
-
-### Bug Fixes
-
-* **utils-browser:** 修复 ios 拍照产生图片的尺寸问题 ([1e9b47d](https://github.com/cloudcome/utils/commit/1e9b47df68018cef80c050be48cdba206ec5e177))
-* **utils-browser:** 修复图片加载逻辑 ([16e5a41](https://github.com/cloudcome/utils/commit/16e5a4152f29619d8abf767e7f97889216ebe1ae))
-* **utils-browser:** 修正 cookie 过期时间格式 ([160c1c1](https://github.com/cloudcome/utils/commit/160c1c1107428f4c160b2e116454085a7fb3b83a))
-
-### Features
-
-* **utils-browser:** 优化 canvas 工具函数并添加新功能 ([fb89067](https://github.com/cloudcome/utils/commit/fb890674a0a97c0f09df480592236273ff3b5172))
-* **utils-browser:** 新增多个实用工具模块 ([6958f7a](https://github.com/cloudcome/utils/commit/6958f7a13e416b3330464ef9493957db605c4eb1))
-* **utils-browser:** 添加 canvas 相关工具函数 ([536f9d7](https://github.com/cloudcome/utils/commit/536f9d72b071402af3c1d38952d5a0ffdb1906a2))
-* **utils-browser:** 添加 Cookie 操作工具函数 ([cc7c014](https://github.com/cloudcome/utils/commit/cc7c01493141ecd4ef270192e87e51eac8ca2008))
-* **utils-browser:** 添加下载功能 ([7fd2441](https://github.com/cloudcome/utils/commit/7fd24411e357aa6cbfb9e0ca9961d4fcc3cde6e7))
-* **utils-browser:** 添加图片加载函数 ([f51210f](https://github.com/cloudcome/utils/commit/f51210f0af9c47a3033af19ce901a1b70f3882fc))
-* **utils-browser:** 添加视频加载功能 ([d4ef7a5](https://github.com/cloudcome/utils/commit/d4ef7a59a379156dbba8737d18582288ae306900))
-* **utils-browser:** 添加设置和获取元素样式功能 ([71e0b56](https://github.com/cloudcome/utils/commit/71e0b564b09b38020fd6aa9c85bc6b3e2e137d72))

package/src/base64.ts

@@ -1,25 +0,0 @@
-// @ref https://blog.csdn.net/m0_72642319/article/details/139743196
-
-/**
- * 【浏览器环境】将字符串编码为 Base64 格式
- * @param input 要编码的字符串
- * @returns 编码后的 Base64 字符串
- * @remarks
- * 在 Node.js 环境中使用 Buffer 实现，在浏览器环境中使用 TextEncoder 和 btoa 实现
- */
-export function encodeBase64(input: string) {
-  const encoder = new TextEncoder();
-  const unit8Array = encoder.encode(input);
-  return btoa(String.fromCharCode(...unit8Array));
-}
-
-/**
- * 【浏览器环境】 将 Base64 字符串解码为原始字符串
- * @param input 要解码的 Base64 字符串
- * @returns 解码后的原始字符串
- */
-export function decodeBase64(input: string) {
-  const decoder = new TextDecoder();
-  const unit8Array = Uint8Array.from(atob(input), (c) => c.charCodeAt(0));
-  return decoder.decode(unit8Array);
-}

package/src/canvas.ts

@@ -1,147 +0,0 @@
-import { objectDefaults } from '@cloudcome/utils-core/object';
-import { imageLoad } from './image';
-
-/**
- * 将 Canvas 转换为 Base64 编码的字符串
- * @param {HTMLCanvasElement} canvas - 需要转换的 Canvas 元素
- * @param {string} [type] - 图片格式，默认为 'image/png'
- * @param {number} [quality] - 图片质量，范围 0 到 1，仅适用于 'image/jpeg' 或 'image/webp'
- * @returns {string} Base64 编码的图片数据
- * @example
- * const base64 = canvasToBase64(canvas, 'image/jpeg', 0.8);
- */
-export function canvasToBase64(canvas: HTMLCanvasElement, type?: string, quality?: number) {
-  return canvas.toDataURL(type, quality);
-}
-
-/**
- * 将 Canvas 转换为 Blob 对象
- * @param {HTMLCanvasElement} canvas - 需要转换的 Canvas 元素
- * @param {string} [type] - 图片格式，默认为 'image/png'
- * @param {number} [quality] - 图片质量，范围 0 到 1，仅适用于 'image/jpeg' 或 'image/webp'
- * @returns {Promise<Blob>} 返回一个包含 Blob 对象的 Promise
- * @example
- * const blob = await canvasToBlob(canvas, 'image/jpeg', 0.8);
- */
-export async function canvasToBlob(canvas: HTMLCanvasElement, type?: string, quality?: number) {
-  return new Promise<Blob>((resolve, reject) => {
-    canvas.toBlob(
-      (blob) => {
-        if (blob) {
-          resolve(blob);
-        } else {
-          reject(new Error('canvas 导出二进制对象失败'));
-        }
-      },
-      type,
-      quality,
-    );
-  });
-}
-
-/**
- * Canvas 绘制图片的配置选项
- */
-export type CanvasDrawImageOptions = {
-  /**
-   * 源图片的左上角 x 坐标
-   * @type {number}
-   * @default 0
-   */
-  srcLeft?: number;
-  /**
-   * 源图片的左上角 y 坐标
-   * @type {number}
-   * @default 0
-   */
-  srcTop?: number;
-  /**
-   * 源图片的宽度
-   * @type {number}
-   * @default 图片的原始宽度
-   */
-  srcWidth?: number;
-  /**
-   * 源图片的高度
-   * @type {number}
-   * @default 图片的原始高度
-   */
-  srcHeight?: number;
-
-  /**
-   * 目标 Canvas 的左上角 x 坐标
-   * @type {number}
-   * @default 0
-   */
-  destLeft?: number;
-  /**
-   * 目标 Canvas 的左上角 y 坐标
-   * @type {number}
-   * @default 0
-   */
-  destTop?: number;
-  /**
-   * 目标 Canvas 的宽度
-   * @type {number}
-   * @default Canvas 的宽度
-   */
-  destWidth?: number;
-  /**
-   * 目标 Canvas 的高度
-   * @type {number}
-   * @default Canvas 的高度
-   */
-  destHeight?: number;
-};
-
-/**
- * 在 Canvas 上绘制图片
- * @param {HTMLCanvasElement} canvas - 目标 Canvas 元素
- * @param {string} url - 图片的 URL
- * @param {CanvasDrawImageOptions} [options] - 绘制图片的配置选项
- * @returns {Promise<void>} 返回一个 Promise，表示绘制完成
- * @example
- * await canvasDrawImage(canvas, 'https://example.com/image.png', {
- *   srcLeft: 10,
- *   srcTop: 10,
- *   srcWidth: 100,
- *   srcHeight: 100,
- *   destLeft: 0,
- *   destTop: 0,
- *   destWidth: 200,
- *   destHeight: 200
- * });
- */
-export async function canvasDrawImage(canvas: HTMLCanvasElement, url: string, options?: CanvasDrawImageOptions) {
-  const ctx = canvas.getContext('2d');
-  if (!ctx) throw new Error('canvas context is null');
-
-  const img = await imageLoad(url);
-  const defaults: CanvasDrawImageOptions = {
-    srcLeft: 0,
-    srcTop: 0,
-    srcWidth: img.width,
-    srcHeight: img.height,
-    destLeft: 0,
-    destTop: 0,
-    destWidth: canvas.width,
-    destHeight: canvas.height,
-  };
-  const { srcLeft, srcTop, srcWidth, srcHeight, destLeft, destTop, destWidth, destHeight } = objectDefaults(
-    options || {},
-    defaults,
-  ) as Required<CanvasDrawImageOptions>;
-  ctx.drawImage(
-    img,
-    // source
-    srcLeft,
-    srcTop,
-    srcWidth,
-    srcHeight,
-    // dest
-    destLeft,
-    destTop,
-    destWidth,
-    destHeight,
-  );
-}

package/src/cookie.ts

@@ -1,118 +0,0 @@
-import type { TDateValue } from '@cloudcome/utils-core/date';
-import { dateParse } from '@cloudcome/utils-core/date';
-
-/**
- * 获取指定名称的 Cookie 值。
- * @param {string} name - Cookie 的名称。
- * @returns {string} - 返回对应的 Cookie 值，如果不存在则返回空字符串。
- */
-export function cookieGet(name: string) {
-  const cookies = document.cookie.split(';');
-
-  for (let i = 0; i < cookies.length; i++) {
-    const cookie = cookies[i].trim();
-
-    if (cookie.startsWith(`${name}=`)) {
-      return decodeURIComponent(cookie.slice(name.length + 1));
-    }
-  }
-
-  return '';
-}
-
-/**
- * 设置 Cookie。
- * @param {string} name - Cookie 的名称。
- * @param {string} value - Cookie 的值。
- * @param {CookieOptions} [options] - 可选的 Cookie 配置项。
- */
-export type CookieOptions = {
-  /**
-   * Cookie 的过期时间，可以是日期字符串、时间戳或 `Date` 对象。
-   */
-  expires?: TDateValue;
-
-  /**
-   * Cookie 的路径，默认为当前路径。
-   */
-  path?: string;
-
-  /**
-   * Cookie 的域名，默认为当前域名。
-   */
-  domain?: string;
-
-  /**
-   * 是否启用安全传输（HTTPS）。
-   */
-  secure?: boolean;
-
-  /**
-   * SameSite 属性，可选值为 `'strict'`、`'lax'` 或 `'none'`。
-   */
-  sameSite?: 'strict' | 'lax' | 'none';
-
-  /**
-   * 是否启用 HttpOnly 标志，防止 JavaScript 访问。
-   */
-  httpOnly?: boolean;
-
-  /**
-   * Cookie 的最大存活时间（秒）。
-   */
-  maxAge?: number;
-};
-
-/**
- * 设置 Cookie。
- * @param {string} name - Cookie 的名称。
- * @param {string} value - Cookie 的值。
- * @param {CookieOptions} [options] - 可选的 Cookie 配置项。
- */
-export function cookieSet(name: string, value: string, options?: CookieOptions) {
-  const { expires, maxAge, path, domain, httpOnly, sameSite, secure } = options || {};
-  let cookie = `${name}=${encodeURIComponent(value)}`;
-
-  const expiresAt = expires ? dateParse(expires) : maxAge ? dateParse(Date.now() + maxAge) : null;
-  const metas: [string, string][] = [];
-
-  if (expiresAt) {
-    metas.push(['expires', expiresAt.toISOString()]);
-  }
-
-  if (path) {
-    metas.push(['path', path]);
-  }
-
-  if (domain) {
-    metas.push(['domain', domain]);
-  }
-
-  if (httpOnly) {
-    metas.push(['httpOnly', 'true']);
-  }
-
-  if (sameSite) {
-    metas.push(['sameSite', sameSite]);
-  }
-
-  if (secure) {
-    metas.push(['secure', 'true']);
-  }
-
-  for (const [key, value] of metas) {
-    cookie += `; ${key}=${value}`;
-  }
-
-  document.cookie = cookie;
-}
-
-/**
- * 删除指定名称的 Cookie。
- * @param {string} name - 要删除的 Cookie 名称。
- */
-export function cookieDel(name: string) {
-  cookieSet(name, '', {
-    expires: 0,
-  });
-}

package/src/dom.ts

@@ -1,48 +0,0 @@
-import { objectEach } from '@cloudcome/utils-core/object';
-
-/**
- * 表示 CSS 样式声明的类型，仅包含可用的字符串或数字类型的属性
- * @typedef {Object} TStyle
- * @property {string | number} [K] - CSS 样式属性，K 为 CSSStyleDeclaration 的键名，且值为字符串或数字类型
- */
-export type TStyle = {
-  [K in keyof CSSStyleDeclaration as K extends number
-    ? never
-    : CSSStyleDeclaration[K] extends string | number
-      ? K
-      : never]: CSSStyleDeclaration[K];
-};
-
-/**
- * 设置元素的样式
- * @param {HTMLElement} el - 需要设置样式的 HTML 元素
- * @param {string | Partial<TStyle> | Record<string, string>} style - 样式字符串或样式对象
- * @example
- * // 设置 body 元素的颜色为红色，并设置一个自定义变量
- * setStyle(document.body, { color: 'red', '--var': 'value' });
- * @example
- * // 使用字符串设置样式
- * setStyle(document.body, 'color: red; --var: value;');
- */
-export function setStyle(el: HTMLElement, style: string | Partial<TStyle> | Record<string, string>) {
-  if (typeof style === 'string') {
-    el.style.cssText = style;
-  } else {
-    objectEach(style, (value, key) => {
-      el.style.setProperty(key as string, value as string | null);
-    });
-  }
-}
-
-/**
- * 获取元素的指定样式值
- * @param {HTMLElement} el - 需要获取样式的 HTML 元素
- * @param {keyof TStyle} style - 需要获取的样式属性
- * @returns {string} 返回指定样式的值
- * @example
- * // 获取 body 元素的颜色
- * const color = getStyle(document.body, 'color');
- */
-export function getStyle(el: HTMLElement, style: keyof TStyle) {
-  return window.getComputedStyle(el).getPropertyValue(style);
-}

package/src/download.ts

@@ -1,22 +0,0 @@
-/**
- * 下载 URL
- * @param {string} url
- * @param {string} filename
- */
-export function downloadURL(url: string, filename?: string) {
-  const a = document.createElement('a');
-  a.href = url;
-  a.download = filename || '';
-  a.click();
-}
-
-/**
- * 下载 Blob 对象
- * @param blob Blob 对象
- * @param filename 文件名
- */
-export function downloadBlob(blob: Blob, filename?: string) {
-  const url = URL.createObjectURL(blob);
-  downloadURL(url, filename);
-  URL.revokeObjectURL(url);
-}

package/src/dts/global.d.ts

@@ -1,27 +0,0 @@
-/**
- * @file global.d.ts
- */
-
-/**
- * package.json name
- */
-declare const PKG_NAME: string;
-
-/**
- * package.json version
- */
-declare const PKG_VERSION: string;
-
-/**
- * package.json description
- */
-declare const PKG_DESCRIPTION: string;
-
-declare const IS_TEST: string;
-
-interface TEST_MOCK {
-  IS_BROWSER: boolean;
-  IS_NODE: boolean;
-}
-
-declare const TEST_MOCK: TEST_MOCK;

package/src/image.ts

@@ -1,45 +0,0 @@
-import { setStyle } from './dom';
-
-/**
- * 加载图片并返回一个包含 HTMLImageElement 的 Promise
- * @param {string} url - 图片的 URL 地址
- * @returns {Promise<HTMLImageElement>} 返回一个包含 HTMLImageElement 的 Promise
- * @example
- * const img = await imageLoad('https://example.com/image.png');
- * @throws {Error} 如果图片加载失败，抛出错误
- */
-export async function imageLoad(url: string) {
-  return new Promise<HTMLImageElement>((resolve, reject) => {
-    const image = new Image();
-    const onFinish = (isError?: boolean) => {
-      image.onload = image.onerror = null;
-      document.body.removeChild(image);
-      isError ? reject(new Error('图片加载失败')) : resolve(image);
-    };
-    image.onload = () => onFinish();
-    image.onerror = () => onFinish(true);
-    image.crossOrigin = 'anonymous';
-    image.src = url;
-
-    // ios 拍照产生的图片，如果没有插入的 DOM 中获取到的图片尺寸是相反的
-    setStyle(image, {
-      visibility: 'hidden',
-      position: 'absolute',
-      top: '-99999%',
-      left: '-99999%',
-      maxWidth: 'none',
-      maxHeight: 'none',
-      border: '0',
-      width: 'auto',
-      height: 'auto',
-      margin: '0',
-      padding: '0',
-      transform: '',
-    });
-    document.body.appendChild(image);
-
-    if (image.complete && image.width > 0) onFinish();
-  });
-}
-
-// 图片缩放函数

package/src/index.ts

@@ -1 +0,0 @@
-export const VERSION = PKG_VERSION;

package/src/timer.ts

@@ -1,56 +0,0 @@
-import { type TTimerHandler, type TTimerOptions, type TTimerState, makeInterval } from '@cloudcome/utils-core/timer';
-
-/**
- * 创建一个基于 `requestAnimationFrame` 的间隔定时器
- *
- * @param callback - 每次间隔执行的回调函数，接收定时器状态和可选的 `next` 函数
- * @param options - 配置选项
- * @returns {TTimerHandler} 返回包含控制方法的对象
- */
-export function frameInterval(
-  callback: (state: TTimerState, next?: () => void) => unknown,
-  options?: TTimerOptions,
-): TTimerHandler {
-  let rafId: number;
-  const { canStart, start, canStop, stop, canPause, pause, canResume, resume, execute } = makeInterval((call) => {
-    rafId = requestAnimationFrame(call);
-  }, callback);
-
-  return {
-    start() {
-      if (!canStart()) return;
-
-      if (options?.leading) {
-        start();
-      } else {
-        rafId = requestAnimationFrame(start);
-      }
-    },
-
-    stop() {
-      if (!canStop()) return;
-      if (options?.trailing) execute();
-
-      cancelAnimationFrame(rafId);
-      stop();
-    },
-
-    pause() {
-      if (!canPause()) return;
-      if (options?.trailing) execute();
-
-      cancelAnimationFrame(rafId);
-      pause();
-    },
-
-    resume(immediate?: boolean) {
-      if (!canResume()) return;
-
-      if (immediate || options?.leading) {
-        resume();
-      } else {
-        rafId = requestAnimationFrame(resume);
-      }
-    },
-  };
-}

package/src/video.ts

@@ -1,19 +0,0 @@
-/**
- * 加载视频并返回一个包含 HTMLVideoElement 的 Promise
- * @param {string} url - 视频的 URL 地址
- * @returns {Promise<HTMLVideoElement>} 返回一个包含 HTMLVideoElement 的 Promise
- * @example
- * const video = await videoLoad('https://example.com/video.mp4');
- * @throws {Error} 如果视频加载失败，抛出错误
- */
-export async function videoLoad(url: string) {
-  return new Promise<HTMLVideoElement>((resolve, reject) => {
-    const video = document.createElement('video');
-
-    video.src = url;
-    video.crossOrigin = 'anonymous';
-    video.currentTime = 1;
-    video.onloadedmetadata = () => resolve(video);
-    video.onerror = () => reject(new Error('视频加载失败'));
-  });
-}

package/test/base64.test.ts

@@ -1,47 +0,0 @@
-import { decodeBase64, encodeBase64 } from '@/base64';
-import { describe, expect, it } from 'vitest';
-
-describe('encodeBase64', () => {
-  it('应正确编码空字符串', () => {
-    expect(encodeBase64('')).toBe('');
-  });
-
-  it('应正确编码普通字符串', () => {
-    expect(encodeBase64('hello')).toBe('aGVsbG8=');
-  });
-
-  it('应正确编码特殊字符', () => {
-    expect(encodeBase64('!@#$%^&*()')).toBe('IUAjJCVeJiooKQ==');
-  });
-
-  it('应正确编码中文字符', () => {
-    expect(encodeBase64('你好')).toBe('5L2g5aW9');
-  });
-});
-
-describe('decodeBase64', () => {
-  it('应正确解码空字符串', () => {
-    expect(decodeBase64('')).toBe('');
-  });
-
-  it('应正确解码普通字符串', () => {
-    expect(decodeBase64('aGVsbG8=')).toBe('hello');
-  });
-
-  it('应正确解码特殊字符', () => {
-    expect(decodeBase64('IUAjJCVeJiooKQ==')).toBe('!@#$%^&*()');
-  });
-
-  it('应正确解码中文字符', () => {
-    expect(decodeBase64('5L2g5aW9')).toBe('你好');
-  });
-});
-
-describe('encode/decode 互操作', () => {
-  it('应能正确编码并解码回原始字符串', () => {
-    const original = 'Hello, 世界!';
-    const encoded = encodeBase64(original);
-    const decoded = decodeBase64(encoded);
-    expect(decoded).toBe(original);
-  });
-});