@boteteam/utils

工具包，提供文件处理、Cookie、URL 参数、存储、字符串、树/模板、模块格式化、脚本执行、文件 URL、安全、环境检测、媒体查询、HTTP、时间、水印、会话/变量解析、单位换算等能力。

安装

yarn add @boteteam/utils

或

npm install @boteteam/utils

导出的工具方法说明

文件与 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。 |

导出的类型

• fileToBase64Type：fileToBase64 的函数类型
• asyncLocalStorageType / asyncSessionStorageType：异步存储的 setItem/getItem/removeItem 接口
• scriptExecutionType：脚本执行函数类型
• pageSizeType：watchMatchMedia 返回的尺寸类型联合
• WatermarkStyles / WatermarkLayout / WatermarkConfig / WatermarkRow / ContextVariable：水印与上下文变量相关类型
• SessionInfo：会话用户信息 { userId?, userName?, realName? }

LICENSE

MIT