@pnt-team/pnt-component-frontend 0.0.92 → 0.0.96

package/README.md

@@ -66,7 +66,8 @@ import {
 | `src`        | `string \| undefined`                |  ✅  | -                                                                    | 图片 URL；为空则展示 defaultImg 或内置 uploadImg        |
 | `alt`        | `string`                             |  ❌  | `''`                                                                 | alt 文本，纯预览模式建议传入以提升可访问性              |
 | `defaultImg` | `string`                             |  ❌  | 内置 uploadImg                                                       | 默认图片（仅上传预览模式生效）                          |
-| `style`      | `React.CSSProperties`                |  ❌  | -                                                                    | 自定义样式（一般用于控制宽高）                          |
+| `size`       | `'small' \| 'medium' \| 'large'`     |  ❌  | `'large'`                                                            | 快捷正方形尺寸：small=36px、medium=60px、large=136px    |
+| `style`      | `React.CSSProperties`                |  ❌  | -                                                                    | 自定义样式；width/height 优先级高于 size                |
 | `loading`    | `boolean`                            |  ❌  | `false`                                                              | 上传中状态（仅上传预览模式生效）                        |
 | `onRemove`   | `(e: any) => void`                   |  ❌  | -                                                                    | 删除回调（传入即启用上传预览模式）                      |
 | `container`  | `HTMLElement \| (() => HTMLElement)` |  ❌  | -                                                                    | attach 容器（弹窗场景需要，透传给 tdesign ImageViewer） |
@@ -88,14 +89,14 @@ import {
   loading={uploading}
   defaultImg="/path/to/default.png"
   onRemove={handleRemove}
-  style={{ width: 136, height: 136 }}
+  size="large"
 />
 
 // 纯预览模式
 <PntImage
   src={url}
   alt="avatar"
-  style={{ width: 60, height: 60 }}
+  size="medium"
   container={dialogContainer}
 />
 
@@ -103,7 +104,7 @@ import {
 <PntImage
   src={url}
   alt="avatar"
-  style={{ width: 60, height: 60 }}
+  size="medium"
   texts={{ loading: 'Loading', loadFailed: 'Failed' }}
 />
 ```
@@ -207,6 +208,27 @@ import { PntSecureBox } from '@pnt-team/pnt-component-frontend';
 />;
 ```
 
+**非展示场景（查看 → 复制 / 批量解锁拼装）请用 `useHighSecurity`：**
+
+```tsx
+import { useHighSecurity } from '@pnt-team/pnt-component-frontend';
+
+const { securityData, isUnlocked, requestSecurityData, clearSecurityData } =
+  useHighSecurity({ gameId, env });
+
+// 第一次点击解锁、第二次点击复制；切换业务时 clearSecurityData()
+const res = await requestSecurityData({
+  gameId,
+  env,
+  param: [{ key: 'SDK_KEY', value: cipher }],
+});
+if (res.length) navigator.clipboard.writeText(securityData.SDK_KEY);
+```
+
+- 模块级缓存按 `gameId + env + key` 复合键隔离，同页多实例共享，同一 key 同页只请求一次；在途并发自动去重
+- 解锁失败返回 `[]` 且不抛错；`env` 必填
+- 另有 `isSecurityData(value)` 导出，用于判断 `_high_security_:` 密文
+
 ---
 
 ### L3 布局组件

package/lib/cjs/api/cos.d.ts

@@ -0,0 +1,103 @@
+import type { AxiosInstance } from 'axios';
+/**
+ * 归一化后的 COS 临时凭证
+ * @description 各后端接口字段命名不统一（snake/camel），组件库内部统一为 camelCase
+ */
+export interface NormalizedCosCredential {
+    /** COS 存储桶 */
+    bucket: string;
+    /** COS 地域 */
+    region: string;
+    /** 临时密钥 ID */
+    secretId: string;
+    /** 临时密钥 Key */
+    secretKey: string;
+    /** 临时会话令牌 */
+    sessionToken: string;
+    /** 凭证生效时间（秒） */
+    startTime: number;
+    /** 凭证过期时间（秒） */
+    expiredTime: number;
+    /**
+     * 业务路径映射
+     * @description 后端按业务类型返回的可写路径 map；消费方按 pathKey 选取
+     */
+    path?: Record<string, string>;
+    /**
+     * 受控目录前缀（SDK 定制场景返回）
+     * @description 前端在该前缀下自行拼接文件名；可与 pathKey 继续拼接子目录
+     */
+    filePath?: string;
+    /**
+     * CDN 访问域名（不含尾斜杠）
+     * @description SDK 定制场景返回 cdn_url；通用场景无此字段时组件按 COS Location 拼接
+     */
+    cosHost?: string;
+}
+/**
+ * 通用 COS 凭证响应（snake_case，pnt-tools / account-business）
+ */
+interface SnakeCosCredential {
+    bucket: string;
+    region: string;
+    secret_id: string;
+    secret_key: string;
+    token: string;
+    start_time: number;
+    expired_time: number;
+    path?: Record<string, string>;
+}
+/**
+ * 内置业务场景
+ * @description 决定走哪个后端凭证接口
+ * - default: 通用上传（GET /v2/business/operation/get-cos-temp-token）
+ * - default_download: 通用下载/上传（POST /v2/business/operation/get-download-cos-temp-token，snake_case）
+ * - sdk_customize: SDK 定制服务（POST /internal/sdk_customize/upload_token，含 cdn_url/file_path）
+ * - ai_translate: AI 翻译服务（POST /business/aiTranslate/import/cosToken，camelCase）
+ */
+export type CosScene = 'default' | 'default_download' | 'sdk_customize' | 'ai_translate' | (string & Record<never, never>);
+/**
+ * 凭证获取参数
+ */
+export interface GetCosCredentialParams {
+    /** 业务场景 */
+    scene: CosScene;
+    /** 业务类型路径 key（透传到后端 path map 选取；sdk_customize 场景作为受控目录下的子目录） */
+    pathKey?: string;
+    /**
+     * 业务上下文参数（gameId/env/updType 等，按 scene 不同传递）
+     * @description default/default_download 场景下 gameId 会自动映射到请求头 x-service-type，
+     * 其余字段透传到 query/body；ai_translate 场景整体透传到 body
+     */
+    context?: Record<string, string | number>;
+    /** 文件大小（字节），后端用于校验配额 */
+    contentLength?: number;
+    /** 已上传文件 URL/Key（下载场景使用） */
+    fileUrl?: string;
+    /**
+     * 网关 audience
+     * @default '/player-network'
+     * @description 账号管理等子系统需覆盖为对应 audience（如 '/laas-pnt'）；
+     * 消费方注入的 http 实例若已统一追加 audience，URL 上存在该参数时拦截器不会重复追加
+     */
+    audience?: string;
+}
+/**
+ * 自定义原始响应归一化函数
+ * @description 后端返回字段不符合内置 scene 约定时使用；入参为后端响应的原始 data
+ */
+export type NormalizeCredential = (raw: unknown) => NormalizedCosCredential;
+/**
+ * snake_case 凭证归一化（导出供 getCredential 自定义逃生舱复用）
+ * @description 消费方自行请求凭证（如项目 http 实例为非标准签名）时，
+ * 可在 getCredential 内调用本函数把后端 data 转为组件库统一结构
+ */
+export declare const normalizeSnakeCredential: (raw: SnakeCosCredential) => NormalizedCosCredential;
+/**
+ * 获取 COS 临时凭证（按 scene 路由到不同后端接口，内部归一化字段命名）
+ * @param http 由 PntProvider 注入的 axios 实例
+ * @param params 凭证获取参数
+ * @param customNormalize 可选的原始响应自定义归一化
+ */
+export declare const fetchCosCredential: (http: AxiosInstance, params: GetCosCredentialParams, customNormalize?: NormalizeCredential) => Promise<NormalizedCosCredential>;
+export {};

package/lib/cjs/api/cos.js

@@ -0,0 +1,137 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/api/cos.ts
+var cos_exports = {};
+__export(cos_exports, {
+  fetchCosCredential: () => fetchCosCredential,
+  normalizeSnakeCredential: () => normalizeSnakeCredential
+});
+module.exports = __toCommonJS(cos_exports);
+var normalizeSnake = (raw) => ({
+  bucket: raw.bucket,
+  region: raw.region,
+  secretId: raw.secret_id,
+  secretKey: raw.secret_key,
+  sessionToken: raw.token,
+  startTime: raw.start_time,
+  expiredTime: raw.expired_time,
+  path: raw.path
+});
+var normalizeSnakeCredential = (raw) => normalizeSnake(raw);
+var normalizeAiTranslate = (raw) => {
+  var _a, _b;
+  return {
+    bucket: raw.bucket || "",
+    region: raw.region || "",
+    secretId: raw.secretId || "",
+    secretKey: raw.secretKey || "",
+    sessionToken: raw.token || "",
+    startTime: (_a = raw.startTime) != null ? _a : 0,
+    expiredTime: (_b = raw.expiredTime) != null ? _b : 0,
+    // aiTranslate path 类型为 Record<string, unknown>，这里收窄为 string
+    path: raw.path ? Object.fromEntries(
+      Object.entries(raw.path).filter(
+        (v) => typeof v[1] === "string"
+      )
+    ) : void 0
+  };
+};
+var normalizeSdkCustomize = (raw) => ({
+  bucket: raw.bucket,
+  region: raw.region,
+  secretId: raw.secret_id,
+  secretKey: raw.secret_key,
+  sessionToken: raw.token,
+  startTime: raw.start_time,
+  expiredTime: raw.expired_time,
+  filePath: raw.file_path,
+  cosHost: raw.cdn_url
+});
+var DEFAULT_AUDIENCE = "/player-network";
+var resolveCredential = (res, normalize, customNormalize) => {
+  var _a, _b;
+  const success = res.code === 0 || res.ret === 0;
+  if (!success || res.data === null || typeof res.data === "undefined") {
+    throw new Error(
+      `[PntCosUploader] 获取 COS 凭证失败: code=${(_a = res.code) != null ? _a : "null"} ret=${(_b = res.ret) != null ? _b : "null"} ${res.msg || ""}`
+    );
+  }
+  return customNormalize ? customNormalize(res.data) : normalize(res.data);
+};
+var fetchCosCredential = async (http, params, customNormalize) => {
+  const {
+    scene,
+    context = {},
+    contentLength,
+    fileUrl,
+    audience = DEFAULT_AUDIENCE
+  } = params;
+  switch (scene) {
+    case "default": {
+      const { gameId, ...restContext } = context;
+      const res = await http.get(`/v2/business/operation/get-cos-temp-token?audience=${audience}`, {
+        params: {
+          content_length: contentLength,
+          ...restContext
+        },
+        headers: gameId !== void 0 ? { "x-service-type": String(gameId) } : void 0
+      });
+      return resolveCredential(res, normalizeSnake, customNormalize);
+    }
+    case "default_download": {
+      const { gameId, ...restContext } = context;
+      const res = await http.post(
+        `/v2/business/operation/get-download-cos-temp-token?audience=${audience}`,
+        {
+          file_url: fileUrl,
+          content_length: contentLength,
+          ...restContext
+        },
+        {
+          headers: gameId !== void 0 ? { "x-service-type": String(gameId) } : void 0
+        }
+      );
+      return resolveCredential(res, normalizeSnake, customNormalize);
+    }
+    case "sdk_customize": {
+      const res = await http.post("/internal/sdk_customize/upload_token", {
+        content_length: contentLength,
+        ...context
+      });
+      return resolveCredential(res, normalizeSdkCustomize, customNormalize);
+    }
+    case "ai_translate": {
+      const res = await http.post("/business/aiTranslate/import/cosToken", {
+        contentLength,
+        ...context
+      });
+      return resolveCredential(res, normalizeAiTranslate, customNormalize);
+    }
+    default: {
+      throw new Error(
+        `[PntCosUploader] 未支持的 scene: ${scene}；请通过 getCredential 自定义`
+      );
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fetchCosCredential,
+  normalizeSnakeCredential
+});

package/lib/cjs/components/PntCosUploader/index.d.ts

@@ -0,0 +1,135 @@
+import { type CosScene, type GetCosCredentialParams, type NormalizeCredential, type NormalizedCosCredential } from "../../api/cos";
+import { usePntConfig } from "../../config";
+import type { AxiosInstance } from 'axios';
+/**
+ * 文件名生成策略
+ * @description 内置三种策略；如需自定义可传函数
+ * - uuid: UUID v4 + 原扩展名（默认，最简单）
+ * - md5: 文件内容 MD5 + 原扩展名（与 pnt-tools CosApi 原策略一致）
+ * - timestamp: 时间戳(36进制)+自增计数器 + 原扩展名（与 SDK 定制场景原策略一致）
+ */
+export type FileNameStrategy = 'uuid' | 'md5' | 'timestamp' | ((file: File) => string | Promise<string>);
+/**
+ * COS 上传配置
+ */
+export interface PntCosUploadOptions {
+    /**
+     * 业务场景，决定走哪个凭证接口
+     * @description 内置 4 个 scene，消费方可传 string 自定义并配合 getCredential 使用
+     */
+    scene: CosScene;
+    /**
+     * 业务类型路径 key
+     * @description 通用场景透传给后端 path map 选取对应业务路径；
+     * sdk_customize 场景作为受控目录（filePath）下的子目录继续拼接
+     */
+    pathKey?: string;
+    /**
+     * 业务上下文参数（gameId/env/updType 等）
+     * @description 按 scene 不同传递给后端；default/default_download 下 gameId 自动映射到 x-service-type 请求头
+     */
+    context?: Record<string, string | number>;
+    /**
+     * 网关 audience
+     * @default '/player-network'
+     * @description 账号管理等子系统需覆盖为对应 audience（如 '/laas-pnt'）
+     */
+    audience?: string;
+    /**
+     * 文件名生成策略
+     * @default 'uuid'
+     */
+    fileNameStrategy?: FileNameStrategy;
+    /**
+     * 是否走 CDN 域名拼接
+     * @description true 且凭证返回 cosHost 时用 cosHost + cosKey；否则用 COS putObject 返回的 Location
+     * @default true
+     */
+    useCdn?: boolean;
+    /**
+     * 自定义凭证获取函数（覆盖内置 scene 路由）
+     * @description 后端接口非内置 scene 时使用；返回归一化后的凭证
+     */
+    getCredential?: (http: ReturnType<typeof usePntConfig>['http'], params: GetCosCredentialParams) => Promise<NormalizedCosCredential>;
+    /**
+     * 自定义凭证响应归一化
+     * @description 后端字段不标准时使用；入参为内置 scene 接口返回的原始 data，需返回归一化凭证
+     */
+    normalizeCredential?: NormalizeCredential;
+}
+/**
+ * COS 上传结果
+ */
+export interface PntCosUploadResult {
+    /** 上传后的可访问 URL */
+    fileUrl: string;
+    /** COS 对象 Key */
+    cosKey: string;
+    /** 原始文件名 */
+    fileName: string;
+}
+/**
+ * 单次请求覆盖参数
+ * @description 上传/下载入口的 gameId/task_id/pathKey 常来自表单或表格行数据，
+ * 可通过该参数在单次调用覆盖 hook 初始化时的配置
+ */
+export interface PntCosRequestOverrides {
+    /** 覆盖业务上下文（与初始化 context 浅合并，如行级 gameId/task_id） */
+    context?: Record<string, string | number>;
+    /** 覆盖网关 audience */
+    audience?: string;
+    /** 覆盖凭证场景 */
+    scene?: CosScene;
+    /** 覆盖业务路径 key */
+    pathKey?: string;
+}
+/**
+ * COS 上传器实例
+ */
+export interface PntCosUploader {
+    /**
+     * 上传文件到 COS
+     * @param file 原始文件
+     * @param onProgress 上传进度回调（0~100）
+     * @param overrides 单次调用覆盖配置（表单/行级 gameId 等）
+     */
+    upload: (file: File, onProgress?: (percent: number) => void, overrides?: PntCosRequestOverrides) => Promise<PntCosUploadResult>;
+    /**
+     * 获取文件预签名下载 URL（临时）
+     * @param cosKey COS 对象 Key，或完整 URL（自动剥离域名）
+     * @param overrides 单次调用覆盖配置（行级 gameId/task_id 等）
+     */
+    getDownloadUrl: (cosKey: string, overrides?: PntCosRequestOverrides) => Promise<string>;
+}
+export type { CosScene, GetCosCredentialParams, NormalizeCredential, NormalizedCosCredential, };
+export { normalizeSnakeCredential } from "../../api/cos";
+/**
+ * 创建 COS 直传器实例（不依赖 React）
+ * @description 与 usePntCosUploader 共用同一套核心逻辑，适用于 class 兼容层、
+ * 工具函数、非 React 入口等场景；React 组件请优先使用 usePntCosUploader
+ *
+ * @param http 消费方 axios 实例（约定响应拦截器已解包 response.data）
+ * @param options 上传配置（固定值），或返回配置的 getter（需要动态配置时使用）
+ *
+ * @example
+ * ```ts
+ * const uploader = createPntCosUploader(http, { scene: 'default', pathKey: 'marketing_icon' });
+ * const { fileUrl } = await uploader.upload(file);
+ * ```
+ */
+export declare const createPntCosUploader: (http: AxiosInstance, options: PntCosUploadOptions | (() => PntCosUploadOptions)) => PntCosUploader;
+/**
+ * COS 直传 Service Hook
+ * @description 内置凭证获取 + COS SDK 初始化 + 文件名策略 + URL 拼接，
+ * 收敛各项目重复的 4 份自实现；http 实例由 PntProvider 注入
+ *
+ * @param options 上传配置
+ *
+ * @example
+ * ```ts
+ * const uploader = usePntCosUploader({ scene: 'default', pathKey: 'marketing_icon' });
+ * const { fileUrl, cosKey } = await uploader.upload(file, (p) => setProgress(p));
+ * ```
+ */
+export declare const usePntCosUploader: (options: PntCosUploadOptions) => PntCosUploader;
+export default usePntCosUploader;

package/lib/cjs/components/PntCosUploader/index.js

@@ -0,0 +1,209 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/components/PntCosUploader/index.ts
+var PntCosUploader_exports = {};
+__export(PntCosUploader_exports, {
+  createPntCosUploader: () => createPntCosUploader,
+  default: () => PntCosUploader_default,
+  normalizeSnakeCredential: () => import_cos2.normalizeSnakeCredential,
+  usePntCosUploader: () => usePntCosUploader
+});
+module.exports = __toCommonJS(PntCosUploader_exports);
+var import_cos = require("../../api/cos");
+var import_config = require("../../config");
+var import_cos_js_sdk_v5 = __toESM(require("cos-js-sdk-v5"));
+var import_crypto_js = __toESM(require("crypto-js"));
+var import_react = require("react");
+var import_uuid = require("uuid");
+var import_cos2 = require("../../api/cos");
+var trimSlash = (seg, leading = true) => seg.replace(/\/$/, "").replace(leading ? /^\// : "", "");
+var getFileExt = (filename) => {
+  const idx = filename.lastIndexOf(".");
+  return idx > -1 ? filename.slice(idx) : "";
+};
+var _timestampCounter = 0;
+var generateTimestampName = () => `${Date.now().toString(36)}${(_timestampCounter++).toString(36)}`;
+var computeFileMd5 = async (file) => {
+  const buffer = await file.arrayBuffer();
+  return import_crypto_js.default.MD5(import_crypto_js.default.lib.WordArray.create(buffer)).toString();
+};
+var generateFileName = async (file, strategy) => {
+  if (typeof strategy === "function") {
+    return strategy(file);
+  }
+  const ext = getFileExt(file.name);
+  switch (strategy) {
+    case "md5": {
+      const md5 = await computeFileMd5(file);
+      return `${md5}${ext}`;
+    }
+    case "timestamp":
+      return `${generateTimestampName()}${ext}`;
+    case "uuid":
+    default:
+      return `${(0, import_uuid.v4)()}${ext}`;
+  }
+};
+var resolveBasePath = (cred, pathKey) => {
+  if (cred.filePath) {
+    const prefix = cred.filePath.replace(/\/$/, "");
+    return pathKey ? `${prefix}/${trimSlash(pathKey)}` : prefix;
+  }
+  if (pathKey && cred.path) {
+    return cred.path[pathKey] || "";
+  }
+  return "";
+};
+var stripHost = (key) => key.replace(/^https?:\/\/[^/]+/, "");
+var createCosClient = (cred) => new import_cos_js_sdk_v5.default({
+  getAuthorization: (_, callback) => {
+    callback({
+      TmpSecretId: cred.secretId,
+      TmpSecretKey: cred.secretKey,
+      SecurityToken: cred.sessionToken,
+      StartTime: cred.startTime,
+      ExpiredTime: cred.expiredTime
+    });
+  },
+  Protocol: "https:",
+  FileParallelLimit: 3,
+  ChunkParallelLimit: 3,
+  ChunkSize: 1024 * 1024,
+  ProgressInterval: 1
+});
+var createPntCosUploader = (http, options) => {
+  const getOptions = () => typeof options === "function" ? options() : options;
+  const upload = async (file, onProgress, overrides) => {
+    var _a, _b, _c;
+    const opts = getOptions();
+    const {
+      scene,
+      pathKey,
+      context,
+      audience,
+      fileNameStrategy = "uuid",
+      useCdn = true,
+      getCredential,
+      normalizeCredential
+    } = opts;
+    const mergedContext = { ...context, ...overrides == null ? void 0 : overrides.context };
+    const mergedScene = (_a = overrides == null ? void 0 : overrides.scene) != null ? _a : scene;
+    const mergedAudience = (_b = overrides == null ? void 0 : overrides.audience) != null ? _b : audience;
+    const mergedPathKey = (_c = overrides == null ? void 0 : overrides.pathKey) != null ? _c : pathKey;
+    const credParams = {
+      scene: mergedScene,
+      pathKey: mergedPathKey,
+      context: mergedContext,
+      audience: mergedAudience,
+      contentLength: file.size
+    };
+    const cred = getCredential ? await getCredential(http, credParams) : await (0, import_cos.fetchCosCredential)(http, credParams, normalizeCredential);
+    const basePath = resolveBasePath(cred, mergedPathKey);
+    const fileName = await generateFileName(file, fileNameStrategy);
+    const cosKey = basePath ? `${basePath.replace(/\/$/, "")}/${fileName}` : fileName;
+    const cos = createCosClient(cred);
+    return new Promise((resolve, reject) => {
+      cos.putObject(
+        {
+          Bucket: cred.bucket,
+          Region: cred.region,
+          Key: cosKey,
+          Body: file,
+          onProgress: onProgress ? (progressData) => {
+            onProgress(Math.round(progressData.percent * 100));
+          } : void 0
+        },
+        (err, data) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          const fileUrl = useCdn && cred.cosHost ? `${cred.cosHost.replace(/\/$/, "")}/${cosKey}` : `https://${data.Location}`;
+          resolve({
+            fileUrl,
+            cosKey,
+            fileName: file.name
+          });
+        }
+      );
+    });
+  };
+  const getDownloadUrl = async (cosKey, overrides) => {
+    var _a, _b, _c;
+    const opts = getOptions();
+    const { scene, pathKey, context, audience, getCredential } = opts;
+    const mergedContext = { ...context, ...overrides == null ? void 0 : overrides.context };
+    const mergedScene = (_a = overrides == null ? void 0 : overrides.scene) != null ? _a : scene;
+    const mergedAudience = (_b = overrides == null ? void 0 : overrides.audience) != null ? _b : audience;
+    const mergedPathKey = (_c = overrides == null ? void 0 : overrides.pathKey) != null ? _c : pathKey;
+    const credParams = {
+      scene: getCredential ? mergedScene : mergedScene === "sdk_customize" ? mergedScene : "default_download",
+      pathKey: mergedPathKey,
+      context: mergedContext,
+      audience: mergedAudience,
+      fileUrl: cosKey
+    };
+    const cred = getCredential ? await getCredential(http, credParams) : await (0, import_cos.fetchCosCredential)(http, credParams);
+    const cos = createCosClient(cred);
+    return new Promise((resolve, reject) => {
+      cos.getObjectUrl(
+        {
+          Bucket: cred.bucket,
+          Region: cred.region,
+          Key: stripHost(cosKey),
+          Sign: true
+        },
+        (err, data) => {
+          if (err) {
+            reject(err);
+            return;
+          }
+          resolve(data.Url);
+        }
+      );
+    });
+  };
+  return { upload, getDownloadUrl };
+};
+var usePntCosUploader = (options) => {
+  const { http } = (0, import_config.usePntConfig)();
+  const optionsRef = (0, import_react.useRef)(options);
+  optionsRef.current = options;
+  return (0, import_react.useMemo)(
+    () => createPntCosUploader(http, () => optionsRef.current),
+    [http]
+  );
+};
+var PntCosUploader_default = usePntCosUploader;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createPntCosUploader,
+  normalizeSnakeCredential,
+  usePntCosUploader
+});

package/lib/cjs/components/PntImage/index.d.ts

@@ -28,9 +28,15 @@ export interface PntImageProps {
      * @description src 为空时展示的占位图；不传则使用内置的 uploadImg
      */
     defaultImg?: string;
+    /**
+     * 快捷尺寸（正方形）
+     * @description 预设尺寸：`small`=36px、`medium`=60px、`large`=136px；默认 `large`
+     * 若 `style` 中显式指定了 width/height，则以 style 为准；非正方形场景请使用 `style`
+     */
+    size?: 'small' | 'medium' | 'large';
     /**
      * 自定义样式
-     * @description 一般用于控制图片宽高
+     * @description 一般用于控制图片宽高；其中 width/height 优先级高于 size
      */
     style?: React.CSSProperties;
     /**
@@ -69,14 +75,14 @@ export interface PntImageProps {
  *   loading={loading}
  *   defaultImg={defaultImg}
  *   onRemove={handleRemove}
- *   style={{ width: 136, height: 136 }}
+ *   size="large"
  * />
  *
  * // 纯预览模式
  * <PntImage
  *   src={url}
  *   alt="avatar"
- *   style={{ width: 60, height: 60 }}
+ *   size="medium"
  *   container={container}
  * />
  * ```