@boteteam/utils 0.0.34 → 0.0.35

package/README.md

@@ -1,22 +1,188 @@
-# pro-components
+# @boteteam/utils
 
-[![NPM version](https://img.shields.io/npm/v/pro-components.svg?style=flat)](https://npmjs.com/package/pro-components)
-[![NPM downloads](http://img.shields.io/npm/dm/pro-components.svg?style=flat)](https://npmjs.com/package/pro-components)
+工具包，提供文件处理、Cookie、URL 参数、存储、字符串、树/模板、模块格式化、脚本执行、文件 URL、安全、环境检测、媒体查询、HTTP、时间、水印、会话/变量解析、单位换算等能力。
 
-## Install
+## 安装
 
 ```bash
-$ yarn install
+yarn add @boteteam/utils
 ```
 
+或
+
 ```bash
-$ npm run dev
-$ npm run build
+npm install @boteteam/utils
 ```
 
-## Options
+## 导出的工具方法说明
+
+### 文件与 Base64
+
+| 方法 | 说明 |
+|------|------|
+| **fileToBase64** | 将 `File` 对象转为 Base64 数据 URL（Promise）。常用于图片上传前预览或提交。 |
+
+### Cookie
+
+| 方法 | 说明 |
+|------|------|
+| **CookieUtils** | Cookie 工具对象，兼容 Web 与 React Native。提供 `get(name)`、`set(name, value, expires?, path?, domain?, secure?)`、`unset(name, path?, domain?, secure?)`，以及异步版本 `getAsync`、`setAsync`、`unsetAsync`。内部通过 `getDocument()` 获取 document，在无 DOM 环境返回 null 不报错。 |
+
+### URL 与路径参数
+
+| 方法 | 说明 |
+|------|------|
+| **argsToString** | 将对象转为查询字符串，如 `{ a: 1, b: 2 }` → `"a=1&b=2"`。非对象或空对象返回空字符串。 |
+| **argsToObject** | 将查询字符串转为对象。支持 `?key=value` 或 `key=value` 形式；将 `"true"`/`"false"` 转为布尔值，`"undefined"`/`"null"` 转为空字符串。 |
+| **getSearchObj** | 从当前页面 URL（或传入的 `url`）解析 query，返回键值对对象。React Native 下无 location 时返回空对象。 |
+
+### 异步存储
+
+| 方法 | 说明 |
+|------|------|
+| **asyncLocalStorage** | 对 `localStorage` 的异步封装，提供 `setItem`、`getItem`、`removeItem`，均返回 Promise，便于在异步流程中统一使用。 |
+| **asyncSessionStorage** | 对 `sessionStorage` 的异步封装，接口同 `asyncLocalStorage`。 |
+
+### 字符串
+
+| 方法 | 说明 |
+|------|------|
+| **camelToSnake** | 驼峰转下划线，如 `fooBar` → `foo_bar`。 |
+| **underscoreToCamelCase** | 下划线转驼峰，如 `foo_bar` → `fooBar`。 |
+| **generateRandom18Int** | 生成 18 位随机整数（10^17 ～ 10^18-1），返回 Promise\<number\>。 |
+
+### 树与模板参数（treeUtils）
+
+| 方法 | 说明 |
+|------|------|
+| **getParamsArr** | 从字符串中解析 `${xxx.yyy.zzz}` 或 `${{xxx.yyy.zzz}}`，得到路径数组，如 `["xxx","yyy","zzz"]`。 |
+| **getDataArr** | 同 `getParamsArr`，但会过滤掉首段的 `root`、`pageParams`，用于从数据根节点取值的路径。 |
+| **replaceParamsValue** | 在字符串中替换 `${...}`、`${{...}}` 为参数对象中对应路径的值。支持 `isObject2String`：为 true 时对象会 `JSON.stringify`。 |
+| **replaceParamsValueForEvent** | 专用于事件参数：保留 `pageParams` 层级、对象会做 `JSON.stringify`、替换失败时返回原始字符串。 |
+| **getParamsContentByParamKeys** | 根据参数字符串（如 `"${a.b.c}"`）和 data 对象，按路径取值；支持 `${{}}` 转义内容。 |
+
+### 模块数据格式化
+
+| 方法 | 说明 |
+|------|------|
+| **formatModuleData** | 根据模块配置（moduleData）、父模块、页面数据、参数、循环项、静态资源等，递归格式化出可直接渲染的模块树（含各类组件 props、事件、样式等）。用于低代码/页面配置驱动渲染。 |
+
+### 格式模块辅助（formatModule/helpers）
+
+| 方法 | 说明 |
+|------|------|
+| **patternTransitionRegExp** | 将字符串转为 RegExp。支持 `/pattern/flags` 形式或普通字符串。异常时返回空字符串。 |
+| **stringPramarsValTransition** | 即 `replaceParamsValue`：在字符串中把 `${...}`、`${{...}}` 替换为参数对象中的值。 |
+| **stringScriptExecution** | 在 SES Compartment 中执行脚本字符串，传入 `root`（及 `window`）作为全局，返回执行结果。执行失败返回 undefined。 |
+| **createCompartmentExecution** | 创建 SES 的 `Compartment` 实例，可传入 `globals` 作为沙箱全局。 |
+| **checkDataSourceOfFn** | 判断字符串是否为“函数形式”数据源：去空格后不以 `$` 开头，且以 `(function()` 开头、以 `})()` 结尾。用于区分静态配置与可执行脚本。 |
+
+### 页面静态与接口映射
+
+| 方法 | 说明 |
+|------|------|
+| **loopPageStaticCodeMap** | 遍历页面配置树（items），收集所有 `compProps.attrs` 中的 `staticCode` 以及 `dataOptions.staticCode`，去重后返回静态编码列表。 |
+| **loopPageServiceApiMap** | 从页面配置第一个 `compType="page"` 的 `dataSources` 中收集 type 为 `api` 或 `custom` 的配置，返回 `{ apiId, reqParams, dataPath, name, type, ... }` 等字段的数组。 |
+
+### 路径取值
+
+| 方法 | 说明 |
+|------|------|
+| **getValueByPath** | 根据路径字符串（如 `res.data.list`、`user.name`）从对象中取值。路径以 `res` 开头时会从 `obj.res` 起算。路径无效或中间缺失返回 null。 |
+
+### 脚本执行
+
+| 方法 | 说明 |
+|------|------|
+| **scriptExecution** | 在 SES Compartment 中执行 `scriptCode`，传入 `options` 作为沙箱全局，返回执行结果。用于安全执行用户或配置中的脚本。 |
+
+### 文件与远程资源 URL
+
+| 方法 | 说明 |
+|------|------|
+| **getFileUrlById** | 根据文件 ID 生成下载 URL，支持 prefix、isSecurity（默认 true，会加签/加密）、params。会自动带上当前 URL 的 token。 |
+| **getFileUrlByFileInfoId** | 根据 fileInfoId 生成下载 URL，选项同 `getFileUrlById`，并支持 tenantId。 |
+| **getRemoteComponentUrlByCode** | 根据页面编码（pageCode）生成远程组件请求 URL。 |
+| **getRemoteComponentUrlById** | 根据 fileInfoId 生成远程组件请求 URL。 |
+
+### 安全
+
+| 方法 | 说明 |
+|------|------|
+| **isValidUrl** | 校验 URL 是否安全：仅允许 http/https，并检测 javascript:、data:、`<script`、onload 等危险模式，防止 XSS。 |
+| **sanitizeRedirectUrl** | 清理并校验重定向 URL；可传允许域名列表，未传则仅允许同源。不安全时返回 defaultUrl（默认 `/`）。 |
+| **safeRedirect** | 先经 `sanitizeRedirectUrl` 得到安全 URL，再设置 `window.location.href` 跳转。React Native 下仅打日志不跳转。 |
+| **sanitizeEventHandler** | 包装事件处理函数，非函数返回空函数；执行时 try-catch，避免异常抛出影响其他逻辑。 |
+
+### 环境检测
+
+| 方法 | 说明 |
+|------|------|
+| **isReactNative** | 判断是否为 React Native 环境（通过 `global.navigator.product === 'ReactNative'`）。 |
+| **isWeb** | 判断是否为 Web 环境（存在 window 与 document 且非 RN）。 |
+| **isNode** | 判断是否为 Node.js 环境。 |
+| **getEnvironment** | 返回当前环境：`'web'` \| `'react-native'` \| `'node'`。 |
+| **getWindow** | 安全获取 `window`，非 Web 返回 null。 |
+| **getDocument** | 安全获取 `document`，非 Web 返回 null。 |
+| **getLocation** | 安全获取 `window.location`，非 Web 返回 null。 |
+| **isMobile** | 根据 `navigator.userAgent` 判断是否为移动端设备。 |
+
+### 响应式与媒体查询
+
+| 方法 | 说明 |
+|------|------|
+| **watchMatchMedia** | 根据主题中的断点（mobile/mini/tablet/compact/middle/large）做一次 matchMedia 检测，返回当前页面尺寸类型：`'default'` \| `'mobile'` \| `'mini'` \| `'compact'` \| `'middle'` \| `'large'` \| `'tablet'`。 |
+
+### HTTP 与访问地址
+
+| 方法 | 说明 |
+|------|------|
+| **request** | HTTP 请求对象：`get`、`post`、`download`，以及 `getBaseUrl`、`setUrlPrefix`、`setTenantId`、`getManagerUrl`、`getBotUrl`、各类图标 URL 等。请求会自动带 token 与 Tenant-Id。 |
+| **tenantIdSessionKey** | 当前租户 ID 在 sessionStorage 中的 key 常量：`'botSelectedTenantID'`。 |
+| **getAccessUrl** | 根据环境变量或传入的 url 构造完整访问地址；若 url 为纯数字则视为端口号，与当前 hostname 拼接。 |
+
+### 时间格式化
+
+| 方法 | 说明 |
+|------|------|
+| **formatTime** | 格式化时间：当天显示 HH:mm，非当天显示 YYYY-MM-DD HH:mm。 |
+| **formatTimeCustom** | 自定义当天与非当天的格式，默认当天 `HH:mm`，非当天 `YYYY-MM-DD HH:mm`。 |
+| **isToday** | 判断给定时间是否为今天。 |
+| **getRelativeTime** | 返回相对时间文案：刚刚、N分钟前、N小时前、昨天、N天前，超过约一周则返回 YYYY-MM-DD。 |
+
+### 水印与 XML
+
+| 方法 | 说明 |
+|------|------|
+| **generateWatermarkBase64** | 根据水印配置（内容、样式、布局、行配置等）生成水印图片的 Base64 数据 URL，支持变量解析。 |
+| **generateWatermarkStyle** | 将水印样式配置转为 React CSSProperties（颜色、字号、透明度、旋转等）。 |
+| **escapeXml** | 对字符串做 XML 转义：`&` `<>` `"` `'` 转为对应实体。 |
+
+### 会话与变量解析
+
+| 方法 | 说明 |
+|------|------|
+| **getVariableRealValue** | 根据变量 key 取真实值。支持 `${system.now}`、`${system.today}`、`${system.ip}`、`${session.userId}`、`${session.userName}`、`${session.realName}`、`${contextParams.xxx}`。 |
+| **parseContentVariables** | 解析字符串中所有 `${system.xxx}`、`${session.xxx}`、`${contextParams.xxx}` 并替换为真实值。 |
+| **getUserInfoFromStorage** | 从 sessionStorage 或 localStorage 的 `userStores` 中读取 userInfo，返回 `{ userId, userName, realName }`。 |
+| **fetchClientIp** | 异步通过第三方 API 获取客户端 IP，并写入 storage 缓存。 |
+| **getClientIp** | 同步从缓存读取客户端 IP；无缓存时返回默认值并触发一次异步 fetch。 |
+
+### 其他
+
+| 方法 | 说明 |
+|------|------|
+| **aiGenerateFill** | 在 document.body 中插入一个隐藏的 SVG，用于定义 AI 生成图标的渐变（linearGradient），供其他 SVG 通过 id 引用。 |
+| **unitConversion** | 将数字（或可解析为数字的字符串）按 1024 换算为带单位的字符串，如 `1536` → `"1.5KB"`，支持 B/KB/MB/GB，整数会去掉 `.00`。 |
+
+## 导出的类型
 
-TODO
+- **fileToBase64Type**：`fileToBase64` 的函数类型  
+- **asyncLocalStorageType** / **asyncSessionStorageType**：异步存储的 setItem/getItem/removeItem 接口  
+- **scriptExecutionType**：脚本执行函数类型  
+- **pageSizeType**：`watchMatchMedia` 返回的尺寸类型联合  
+- **WatermarkStyles** / **WatermarkLayout** / **WatermarkConfig** / **WatermarkRow** / **ContextVariable**：水印与上下文变量相关类型  
+- **SessionInfo**：会话用户信息 `{ userId?, userName?, realName? }`  
 
 ## LICENSE
 

package/dist/cjs/aiGenerateFill.d.ts

@@ -0,0 +1,2 @@
+declare const aiGenearteFill: () => void;
+export default aiGenearteFill;

package/dist/cjs/aiGenerateFill.js

@@ -0,0 +1,44 @@
+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/aiGenerateFill.ts
+var aiGenerateFill_exports = {};
+__export(aiGenerateFill_exports, {
+  default: () => aiGenerateFill_default
+});
+module.exports = __toCommonJS(aiGenerateFill_exports);
+var aiGenearteFill = () => {
+  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  svg.style.position = "absolute";
+  svg.style.width = "0";
+  svg.style.height = "0";
+  svg.style.visibility = "hidden";
+  svg.style.overflow = "hidden";
+  svg.innerHTML = `
+    <defs>
+      <linearGradient id="icon-ai-generate_svg__a" x1="-6.64737" y1="3.91997" x2="17.3507" y2="13.7217" gradientUnits="userSpaceOnUse">
+        <stop stop-color="#409DFF" style="stop-color:#409DFF;stop-color:color(display-p3 0.2495 0.6157 1.0000);stop-opacity:1;"></stop>
+        <stop offset="0.5" stop-color="#5279FF" style="stop-color:#5279FF;stop-color:color(display-p3 0.3216 0.4745 1.0000);stop-opacity:1;"></stop>
+        <stop offset="1" stop-color="#C173FF" style="stop-color:#C173FF;stop-color:color(display-p3 0.7555 0.4512 1.0000);stop-opacity:1;"></stop>
+      </linearGradient>
+    </defs>
+  `;
+  document.body.appendChild(svg);
+};
+var aiGenerateFill_default = aiGenearteFill;
+//# sourceMappingURL=aiGenerateFill.js.map

package/dist/cjs/aiGenerateFill.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/aiGenerateFill.ts"],
+  "sourcesContent": ["const aiGenearteFill = () => {\n  // 使用 SVG 命名空间创建 SVG 元素，确保正确的 SVG 上下文\n  const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');\n  // 设置 SVG 为隐藏，作为渐变定义的容器（outlet）\n  svg.style.position = 'absolute';\n  svg.style.width = '0';\n  svg.style.height = '0';\n  svg.style.visibility = 'hidden';\n  svg.style.overflow = 'hidden';\n  \n  svg.innerHTML = `\n    <defs>\n      <linearGradient id=\"icon-ai-generate_svg__a\" x1=\"-6.64737\" y1=\"3.91997\" x2=\"17.3507\" y2=\"13.7217\" gradientUnits=\"userSpaceOnUse\">\n        <stop stop-color=\"#409DFF\" style=\"stop-color:#409DFF;stop-color:color(display-p3 0.2495 0.6157 1.0000);stop-opacity:1;\"></stop>\n        <stop offset=\"0.5\" stop-color=\"#5279FF\" style=\"stop-color:#5279FF;stop-color:color(display-p3 0.3216 0.4745 1.0000);stop-opacity:1;\"></stop>\n        <stop offset=\"1\" stop-color=\"#C173FF\" style=\"stop-color:#C173FF;stop-color:color(display-p3 0.7555 0.4512 1.0000);stop-opacity:1;\"></stop>\n      </linearGradient>\n    </defs>\n  `;\n  \n  // 将 SVG 元素添加到 body，作为渐变定义的出口（outlet）\n  // 这样其他 SVG 元素就可以通过 ID 引用其中的渐变\n  document.body.appendChild(svg);\n};\n\nexport default aiGenearteFill;\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAAM,iBAAiB,MAAM;AAE3B,QAAM,MAAM,SAAS,gBAAgB,8BAA8B,KAAK;AAExE,MAAI,MAAM,WAAW;AACrB,MAAI,MAAM,QAAQ;AAClB,MAAI,MAAM,SAAS;AACnB,MAAI,MAAM,aAAa;AACvB,MAAI,MAAM,WAAW;AAErB,MAAI,YAAY;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAYhB,WAAS,KAAK,YAAY,GAAG;AAC/B;AAEA,IAAO,yBAAQ;",
+  "names": []
+}

package/dist/cjs/copyToClipboard.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 使用 copy-to-clipboard 库的复制方法
+ * @param text 要复制的文本
+ * @returns Promise<boolean> 是否复制成功
+ */
+export declare const copyToClipboard: (text: string) => Promise<boolean>;

package/dist/cjs/copyToClipboard.js

@@ -0,0 +1,55 @@
+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/copyToClipboard.ts
+var copyToClipboard_exports = {};
+__export(copyToClipboard_exports, {
+  copyToClipboard: () => copyToClipboard
+});
+module.exports = __toCommonJS(copyToClipboard_exports);
+var import_copy_to_clipboard = __toESM(require("copy-to-clipboard"));
+var copyToClipboard = (text) => {
+  const str = typeof text === "string" ? text : String(text);
+  if (!str) {
+    return Promise.resolve(false);
+  }
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return Promise.resolve(false);
+  }
+  try {
+    const ok = (0, import_copy_to_clipboard.default)(str);
+    return Promise.resolve(ok);
+  } catch {
+    return Promise.resolve(false);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  copyToClipboard
+});
+//# sourceMappingURL=copyToClipboard.js.map

package/dist/cjs/copyToClipboard.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/copyToClipboard.ts"],
+  "sourcesContent": ["import copy from 'copy-to-clipboard';\n\n/**\n * 使用 copy-to-clipboard 库的复制方法\n * @param text 要复制的文本\n * @returns Promise<boolean> 是否复制成功\n */\nexport const copyToClipboard = (text: string): Promise<boolean> => {\n  const str = typeof text === 'string' ? text : String(text);\n  if (!str) {\n    return Promise.resolve(false);\n  }\n\n  if (typeof window === 'undefined' || typeof document === 'undefined') {\n    return Promise.resolve(false);\n  }\n\n  try {\n    const ok = copy(str);\n    return Promise.resolve(ok);\n  } catch {\n    return Promise.resolve(false);\n  }\n};\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,+BAAiB;AAOV,IAAM,kBAAkB,CAAC,SAAmC;AACjE,QAAM,MAAM,OAAO,SAAS,WAAW,OAAO,OAAO,IAAI;AACzD,MAAI,CAAC,KAAK;AACR,WAAO,QAAQ,QAAQ,KAAK;AAAA,EAC9B;AAEA,MAAI,OAAO,WAAW,eAAe,OAAO,aAAa,aAAa;AACpE,WAAO,QAAQ,QAAQ,KAAK;AAAA,EAC9B;AAEA,MAAI;AACF,UAAM,SAAK,yBAAAA,SAAK,GAAG;AACnB,WAAO,QAAQ,QAAQ,EAAE;AAAA,EAC3B,QAAE;AACA,WAAO,QAAQ,QAAQ,KAAK;AAAA,EAC9B;AACF;",
+  "names": ["copy"]
+}

package/dist/cjs/dealStorageData.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 会话信息类型
+ */
+export interface SessionInfo {
+    userId?: string;
+    userName?: string;
+    realName?: string;
+}
+/**
+ * 根据 key 获取变量的真实值
+ * @param key 变量 key，支持格式：${system.now}、${system.today}、${system.ip}、${session.userId}、${session.userName}、${session.realName}、${contextParams.xxx}
+ */
+export declare function getVariableRealValue(key: string): string;
+/**
+ * 从 storage 获取用户信息（优先从 sessionStorage，其次从 localStorage）
+ */
+export declare function getUserInfoFromStorage(): SessionInfo;
+export declare function getDriverInfoFromStorage(): {
+    [key: string]: any;
+} | null;
+/**
+ * 异步获取客户端 IP（通过第三方 API）
+ * @returns Promise<string> 返回客户端 IP 地址
+ */
+export declare function fetchClientIp(): Promise<string>;
+/**
+ * 获取客户端 IP（同步方法，从缓存读取）
+ * @returns string 返回客户端 IP 地址，如果缓存中没有则返回默认值 '127.0.0.1'
+ */
+export declare function getClientIp(): string;
+/**
+ * 解析 content 中的所有变量并替换为真实值
+ * @param content 原始内容，可能包含变量如 ${system.now}、${session.userId}、${contextParams.userName} 等
+ */
+export declare function parseContentVariables(content: string): string;