@bi-nova/utils

跨平台通用工具包，为 SDK 各模块提供环境检测、剪贴板、Toast、日志、参数校验等基础能力。

支持环境：Taro、uni-app、微信小程序、支付宝小程序、H5（浏览器）。

安装

::: code-group

pnpm add @bi-nova/utils

npm install @bi-nova/utils

:::

::: tip 该包通常作为内部依赖被 @bi-nova/services 等包引用，业务端一般不需要直接安装。 :::

API

环境检测

detectEnv()

检测当前运行环境，返回环境类型字符串。

import { detectEnv } from '@bi-nova/utils'

const env = detectEnv()
// 'taro' | 'uni' | 'wechat' | 'alipay' | 'web' | 'unknown'

检测优先级： taro > uni > wechat > alipay > web > unknown

::: warning Taro 和 uni-app 环境中也存在 wx / my 全局变量，因此必须优先检测框架环境。 :::

isWechatMiniProgram()

判断是否在微信小程序环境中运行（包含 Taro / uni-app 编译到微信的情况）。

import { isWechatMiniProgram } from '@bi-nova/utils'

if (isWechatMiniProgram()) {
  // 微信小程序特有逻辑
}

检测依据：wx.getSystemInfoSync 存在、__wxConfig / getApp 全局变量、navigator.userAgent 中包含 miniprogram 或 micromessenger。

剪贴板

setClipboardData(data)

将文本复制到剪贴板，自动适配各平台 API。

| 参数 | 类型 | 说明 | |------|------|------| | data | string | 要复制的文本内容 |

返回值： Promise<void>

import { setClipboardData } from '@bi-nova/utils'

await setClipboardData('要复制的文本')

各环境底层实现：

| 环境 | 调用方式 | |------|----------| | Taro | Taro.setClipboardData() | | uni-app | uni.setClipboardData() | | 微信小程序 | wx.setClipboardData() | | 支付宝小程序 | my.setClipboardData() | | H5 | navigator.clipboard.writeText() |

Toast

showToast(title, duration?)

显示提示信息，自动适配各平台 API。

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | title | string | - | 提示文本 | | duration | number | 2000 | 显示时长（毫秒） |

返回值： void

import { showToast } from '@bi-nova/utils'

showToast('操作成功')
showToast('加载中', 3000)

H5 环境下降级为 console.log 输出。

平台信息

getPlatform()

获取系统平台类型。

返回值： Promise<'ios' | 'android' | 'unknown'>

import { getPlatform } from '@bi-nova/utils'

const platform = await getPlatform() // 'ios' | 'android' | 'unknown'

getSystemInfo()

获取完整系统信息，各平台返回其原生 getSystemInfoSync() 的结果。

返回值： any

H5 环境返回 { platform, userAgent }。

日志

Logger 类

可控开关的日志工具，所有输出以 [AdPlugin] 为前缀。

import { Logger, logger } from '@bi-nova/utils'

// 使用全局单例
logger.setEnable(true)
logger.info('初始化完成')
logger.warn('参数缺失')
logger.error('请求失败', error)
logger.debug('调试信息', data)

// 或创建独立实例
const myLogger = new Logger(true)

| 方法 | 说明 | |------|------| | setEnable(enable: boolean) | 开启/关闭日志输出 | | info(...args) | 输出 info 级别日志 | | warn(...args) | 输出 warn 级别日志 | | error(...args) | 输出 error 级别日志 | | debug(...args) | 输出 debug 级别日志 |

响应构建

ErrorCode

通用错误码常量，可跨业务复用。

| 值 | 常量 | 说明 | |:--:|------|------| | 0 | SUCCESS | 成功 | | 1000 | UNKNOWN_ERROR | 未知错误 | | 1001 | NETWORK_ERROR | 网络请求失败 | | 1002 | PARSE_ERROR | 数据解析失败 | | 1003 | INVALID_PARAM | 缺少必需参数 |

buildResult(code, message, data?)

构建标准返回结构。

import { buildResult, ErrorCode } from '@bi-nova/utils'

buildResult(ErrorCode.SUCCESS, '操作成功', { id: 1 })
// { code: 0, message: '操作成功', data: { id: 1 } }

buildResult(ErrorCode.NETWORK_ERROR, '请求失败')
// { code: 1001, message: '请求失败', data: null }

isSuccess(result) / isFailure(result)

判断结果是否成功/失败。

import { isSuccess, isFailure } from '@bi-nova/utils'

if (isSuccess(result)) {
  // result.code === 0
}

参数校验

所有校验函数返回 ValidationResult：

interface ValidationResult {
  valid: boolean
  message?: string  // 校验失败时的错误描述
}

| 函数 | 说明 | |------|------| | validateAdUnitId(id) | 校验广告位 ID（非空字符串，长度 5-50） | | validateAdStyle(style) | 校验广告样式（可选，width/height 须为正数） | | validateCallback(cb, name?) | 校验回调函数类型 | | validateRequired(value, fieldName) | 校验必填字段（通用） | | validateRequiredFields(params, fields) | 批量校验必填字段 |

import { validateRequired, validateRequiredFields } from '@bi-nova/utils'

// 单个字段校验
const result1 = validateRequired('', 'equipmentValue')
// { valid: false, message: 'equipmentValue不能为空' }

const result2 = validateRequired('  ', 'name')
// { valid: false, message: 'name不能为空' }  // 自动处理空格

// 批量校验
const result3 = validateRequiredFields(params, ['idMd5Value', 'rtaStrategy'])
// { valid: false, message: 'rtaStrategy不能为空' }  // 指出缺失字段

类型导出

import type {
  EnvType,            // 'taro' | 'uni' | 'wechat' | 'alipay' | 'web' | 'unknown'
  ValidationResult,   // { valid: boolean; message?: string }
  BuildResultReturn,  // { code: number; message: string; data: T | null }
  ErrorCodeValue,     // ErrorCode 枚举值的联合类型
} from '@bi-nova/utils'