@cloudcome/utils-browser 0.0.0 → 1.1.1

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ☁️淡然
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,8 +1,122 @@
 {
-    "name": "@cloudcome/utils-browser",
-    "version": "0.0.0",
-    "publishConfig": {
-        "access": "public",
-        "registry": "https://registry.npmjs.org/"
+  "name": "@cloudcome/utils-browser",
+  "version": "1.1.1",
+  "description": "cloudcome utils for browser",
+  "engines": {
+    "node": ">=22"
+  },
+  "engineStrict": true,
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json",
+    "./base64": {
+      "types": "./dist/base64.d.ts",
+      "import": "./dist/base64.mjs",
+      "require": "./dist/base64.cjs"
+    },
+    "./cache": {
+      "types": "./dist/cache.d.ts",
+      "import": "./dist/cache.mjs",
+      "require": "./dist/cache.cjs"
+    },
+    "./canvas": {
+      "types": "./dist/canvas.d.ts",
+      "import": "./dist/canvas.mjs",
+      "require": "./dist/canvas.cjs"
+    },
+    "./clipboard": {
+      "types": "./dist/clipboard.d.ts",
+      "import": "./dist/clipboard.mjs",
+      "require": "./dist/clipboard.cjs"
+    },
+    "./cookie": {
+      "types": "./dist/cookie.d.ts",
+      "import": "./dist/cookie.mjs",
+      "require": "./dist/cookie.cjs"
+    },
+    "./dom": {
+      "types": "./dist/dom.d.ts",
+      "import": "./dist/dom.mjs",
+      "require": "./dist/dom.cjs"
+    },
+    "./download": {
+      "types": "./dist/download.d.ts",
+      "import": "./dist/download.mjs",
+      "require": "./dist/download.cjs"
+    },
+    "./image": {
+      "types": "./dist/image.d.ts",
+      "import": "./dist/image.mjs",
+      "require": "./dist/image.cjs"
+    },
+    "./timer": {
+      "types": "./dist/timer.d.ts",
+      "import": "./dist/timer.mjs",
+      "require": "./dist/timer.cjs"
+    },
+    "./video": {
+      "types": "./dist/video.d.ts",
+      "import": "./dist/video.mjs",
+      "require": "./dist/video.cjs"
     }
-}
+  },
+  "typesVersions": {
+    "*": {
+      "base64": [
+        "./dist/base64.d.ts"
+      ],
+      "cache": [
+        "./dist/cache.d.ts"
+      ],
+      "canvas": [
+        "./dist/canvas.d.ts"
+      ],
+      "clipboard": [
+        "./dist/clipboard.d.ts"
+      ],
+      "cookie": [
+        "./dist/cookie.d.ts"
+      ],
+      "dom": [
+        "./dist/dom.d.ts"
+      ],
+      "download": [
+        "./dist/download.d.ts"
+      ],
+      "image": [
+        "./dist/image.d.ts"
+      ],
+      "timer": [
+        "./dist/timer.d.ts"
+      ],
+      "video": [
+        "./dist/video.d.ts"
+      ]
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@cloudcome/utils-core": "1.1.1"
+  },
+  "repository": "https://github.com/cloudcome/utils",
+  "keywords": [
+    "utils",
+    "cloudcome",
+    "utils-core",
+    "utils-vue",
+    "utils-react",
+    "utils-uni",
+    "utils-node",
+    "utils-browser"
+  ],
+  "homepage": "https://github.com/cloudcome/utils",
+  "license": "MIT",
+  "author": "云淡然 <hi@ydr.me> (https://ydr.me/)"
+}

package/src/base64.ts

@@ -0,0 +1,25 @@
+// @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/cache.ts

@@ -0,0 +1,115 @@
+import { AbstractCache, type TCacheOptions, type TCached } from '@cloudcome/utils-core/cache';
+import type { MaybePromise } from '@cloudcome/utils-core/types';
+
+/**
+ * 使用浏览器存储（localStorage 或 sessionStorage）实现的缓存类
+ * @template T - 缓存数据的类型
+ */
+export class StorageCache<T> extends AbstractCache<T> {
+  /**
+   * 创建一个新的 StorageCache 实例
+   * @param storage - 使用的存储实现（localStorage 或 sessionStorage）
+   * @param namespace - 可选，用于为缓存键添加前缀的命名空间
+   */
+  constructor(
+    readonly storage: Storage,
+    readonly namespace = '',
+  ) {
+    super();
+  }
+
+  /**
+   * 通过ID获取缓存数据
+   * @param id - 要获取的缓存键
+   * @returns 如果找到且未过期则返回缓存数据，否则返回null
+   */
+  get(id: string): TCached<T> | null {
+    const { storage, namespace } = this;
+    const fullId = namespace ? `${namespace}:${id}` : id;
+
+    try {
+      const cachedString = storage.getItem(fullId);
+      if (!cachedString) return null;
+
+      const cached = JSON.parse(cachedString);
+
+      if (cached.createdAt + cached.maxAge < Date.now()) {
+        this.del(id);
+        return null;
+      }
+
+      return cached;
+    } catch (e) {
+      return null;
+    }
+  }
+
+  /**
+   * 将数据存储到缓存中
+   * @param id - 存储数据使用的缓存键
+   * @param data - 要缓存的数据
+   * @param options - 可选的缓存配置
+   * @returns 成功返回true，存储失败返回false
+   */
+  set(id: string, data: T, options?: TCacheOptions) {
+    const { storage, namespace } = this;
+    const fullId = namespace ? `${namespace}:${id}` : id;
+
+    try {
+      storage.setItem(
+        fullId,
+        JSON.stringify({
+          id,
+          data,
+          createdAt: Date.now(),
+          maxAge: options?.maxAge || 0,
+        }),
+      );
+    } catch (cause) {
+      //
+    }
+  }
+
+  /**
+   * 通过ID删除缓存数据
+   * @param id - 要删除的缓存键
+   */
+  del(id: string) {
+    const { storage, namespace } = this;
+    const fullId = namespace ? `${namespace}:${id}` : id;
+
+    try {
+      storage.removeItem(fullId);
+    } catch (cause) {
+      //
+    }
+  }
+
+  clear() {
+    try {
+      this.storage.clear();
+    } catch (err) {
+      //
+    }
+  }
+}
+
+/**
+ * 创建一个使用 localStorage 的缓存实例
+ * @template T - 缓存数据的类型
+ * @param namespace - 可选，用于为缓存键添加前缀的命名空间
+ * @returns 使用 localStorage 的新 StorageCache 实例
+ */
+export function createLocalCache<T>(namespace?: string): AbstractCache<T> {
+  return new StorageCache<T>(localStorage, namespace);
+}
+
+/**
+ * 创建一个使用 sessionStorage 的缓存实例
+ * @template T - 缓存数据的类型
+ * @param namespace - 可选，用于为缓存键添加前缀的命名空间
+ * @returns 使用 sessionStorage 的新 StorageCache 实例
+ */
+export function createSessionCache<T>(namespace?: string): AbstractCache<T> {
+  return new StorageCache<T>(sessionStorage, namespace);
+}

package/src/canvas.ts

@@ -0,0 +1,147 @@
+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/clipboard.ts

@@ -0,0 +1,29 @@
+/**
+ * 将文本复制到剪贴板
+ * 该方法使用传统的 execCommand 方法实现文本复制
+ *
+ * @param text - 要复制到剪贴板的文本内容
+ * @returns void
+ *
+ * @example
+ * // 基本用法
+ * await copyText('Hello World');
+ *
+ * @example
+ * // 处理复制结果
+ * copyText('Hello World')
+ *   .then(() => console.log('复制成功'))
+ *   .catch(() => console.error('复制失败'));
+ */
+export function copyText(text: string) {
+  const textArea = document.createElement('textarea');
+  textArea.value = text;
+  textArea.style.position = 'fixed';
+  textArea.style.left = '-9999px';
+  textArea.style.top = '-9999px';
+  document.body.appendChild(textArea);
+  textArea.focus();
+  textArea.select();
+  document.execCommand('copy');
+  document.body.removeChild(textArea);
+}

package/src/cookie.ts

@@ -0,0 +1,118 @@
+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

@@ -0,0 +1,48 @@
+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

@@ -0,0 +1,22 @@
+/**
+ * 下载 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);
+}