@microbt/environment v1.2.7
@microbt/environment 使用文档
安装和使用
安装
pnpm add @microbt/environment
使用
import { environment, baseUrl, getLocale } from '@microbt/environment';
const env = environment();
const url = baseUrl();
const locale = getLocale();
环境相关函数
environment()
获取当前运行的环境。
返回值: string
- 环境名称(local, dev, test, pre, gray, prod, unknown)
示例:
const env = environment();
console.log(env); // 输出: 'prod'
isAWSDomain()
判断当前域名是否为 AWS 环境。
返回值: boolean
- 如果是 AWS 环境返回 true
,否则返回 false
示例:
const isAWS = isAWSDomain();
console.log(isAWS); // 输出: true 或 false
region()
获取当前区域代码。
返回值: string
- 区域代码(如 'cn', 'us' 等)
示例:
const regionCode = region();
console.log(regionCode); // 输出: 'cn'
网关相关函数
baseUrl(params: { name: string; path?: string })
根据当前域名生成对应的 API URL。
参数:
params.name
:string
- 必填,API 服务名称(如 'api'、'iot-api')params.path
:string
- 可选,API 路径(如 '/saas')
返回值: string
- 生成的 URL。如果生成失败则返回传入的 path 值
示例:
// 中国区开发环境
// location.host: 'mall-cn-dev.superacme.com'
baseUrl({ name: 'api' }); // => '//api-cn-dev.superacme.com'
baseUrl({ name: 'iot-api', path: '/saas' }); // => '//iot-api-cn-dev.superacme.com/saas'
// 美区 AWS 生产环境
// location.host: 'mall-us-aws.superacme.com'
baseUrl({ name: 'api' }); // => '//api-us-aws.superacme.com'
混合应用相关函数
bridgeCall(method: string, params: Record<string, string>, callback: (resp: string) => void)
调用原生桥接方法。
参数:
method
:string
- 要调用的方法名params
:Record<string, string>
- 方法参数callback
:(resp: string) => void
- 回调函数
示例:
bridgeCall('getUserInfo', { userId: '123' }, (resp) => {
console.log(resp);
bridgeBootstrap()
初始化桥接环境。
示例:
bridgeBootstrap();
inSuperAcme()
判断当前是否在 SuperAcme 应用中。
返回值: boolean
- 如果在 SuperAcme 应用中返回 true
,否则返回 false
示例:
const isInApp = inSuperAcme();
console.log(isInApp); // 输出: true 或 false
superAcmeVersion()
获取 SuperAcme 应用的版本信息。
返回值: 返回一个包含版本信息的对象:
如果在 SuperAcme 应用中且能够解析版本号:
{ version: string; // 完整版本号,如 "1.2.3" major: number; // 主版本号 minor: number; // 次版本号 patch: number; // 修订号 }
如果不在 SuperAcme 应用中或无法解析版本号:
{ version: 'unknown'; }
示例:
const versionInfo = superAcmeVersion();
console.log(versionInfo);
// 在 SuperAcme 应用中可能输出:{ version: "1.2.3", major: 1, minor: 2, patch: 3 }
// 在非 SuperAcme 应用中输出:{ version: "unknown" }
getStatusBarHeight()
获取 SuperAcme 应用的状态栏高度信息。
返回值: 返回一个包含状态栏高度信息的对象:
{
top: number; // 顶部状态栏高度,单位为像素
bottom: number; // 底部状态栏高度,单位为像素
}
如果不在 SuperAcme 应用中或无法解析高度信息,将返回默认值:
{
"top": 0,
"bottom": 0
}
示例 :
const statusBarHeight = getStatusBarHeight();
console.log(statusBarHeight);
// 可能输出:{ top: 20, bottom: 0 }
// 在非 SuperAcme 应用中输出:{ top: 0, bottom: 0 }
平台相关函数
iOSWebview
判断当前是否为 iOS Webview 环境。
类型: boolean
示例:
if (iOSWebview) {
console.log('当前为 iOS Webview 环境');
}
androidWebView
判断当前是否为 Android Webview 环境。
类型: boolean
示例:
if (androidWebView) {
console.log('当前为 Android Webview 环境');
}
本地化相关函数
getLocale(defaultLocal = 'zh-CN')
获取当前语言环境。
参数:
defaultLocal
:string
- 默认语言环境,默认为 'zh-CN'
返回值: string
- 当前语言环境
示例:
const locale = getLocale();
console.log(locale); // 输出: 'zh-CN' 或 'en-US'
Cookie 相关函数
getCookie(name: string)
获取指定名称的 Cookie 值。
参数:
name
:string
- 要获取的 Cookie 名称
返回值: string | null
- 返回指定名称的 Cookie 值,如果不存在或解析失败则返回 null
功能描述:
- 使用正则表达式匹配指定名称的 Cookie 值。
- 如果匹配成功,返回解码后的 Cookie 值。
- 如果匹配失败或解码过程中发生错误,返回
null
。
示例:
const userToken = getCookie('token');
if (userToken) {
console.log(`User token: ${userToken}`);
} else {
console.log('Token not found or invalid');
}
注意事项:
- 函数会对 Cookie 值进行解码,如果解码失败会捕获错误并返回
null
。 - 确保传入的
name
参数是合法的 Cookie 名称。
getRUID()
获取当前域名下的 RUID
值。
返回值: string | null
- 返回当前域名下的 RUID
值,如果不存在或解析失败则返回 null
功能描述:
- 基于当前域名(
location.hostname
)动态生成RUID
的 Cookie 名称。 - 调用
getCookie
函数获取对应的 Cookie 值。
示例:
const ruid = getRUID();
if (ruid) {
console.log(`RUID: ${ruid}`);
} else {
console.log('RUID not found or invalid');
}
注意事项:
- 确保
RUID
的 Cookie 名称格式为RUID_<当前域名>
。 - 函数依赖
getCookie
,因此会继承其解码逻辑和错误处理机制。
ARMS 模块
arms
模块封装了阿里云 ARMS(应用实时监控服务)的前端监控功能,提供了一系列 API 用于上报性能数据、错误信息、用户行为等。
可用 API
以下是 arms
模块中提供的 API 列表:
api(params)
: 上报 API 请求数据。error(e, pos)
: 上报错误信息。sum(key, value)
: 上报累加指标。avg(key, value)
: 上报平均值指标。reportBehavior()
: 上报用户行为数据。performance(params)
: 上报性能数据。setConfig(params)
: 设置 ARMS 配置。setPage(page, sendPv)
: 设置当前页面信息,并可选择是否发送页面访问数据(PV)。setCommonInfo(params)
: 设置通用信息。addBehavior(data, page)
: 添加用户行为数据。
参考链接
日志管理
Logger
提供统一的日志管理功能,支持不同级别的日志输出和配置。
配置选项
interface LoggerConfig {
level: 'debug' | 'info' | 'warn' | 'error' | 'none';
prefix?: string;
}
level
: 日志级别,默认在生产环境为 'info',开发环境为 'debug'prefix
: 日志前缀,默认为 '@microbt/shared'
可用方法
Logger.configure(config: Partial<LoggerConfig>)
: 配置日志选项Logger.debug(...args: any[])
: 输出调试级别日志Logger.info(...args: any[])
: 输出信息级别日志Logger.warn(...args: any[])
: 输出警告级别日志Logger.error(...args: any[])
: 输出错误级别日志
示例
import { Logger } from '@microbt/environment';
// 配置日志级别和前缀
Logger.configure({
level: process.env.NODE_ENV === 'production' ? 'error' : 'debug',
prefix: '自定义前缀',
});
// 使用不同级别的日志
Logger.debug('调试信息');
Logger.info('普通信息');
Logger.warn('警告信息');
Logger.error('错误信息');
日志级别说明
日志级别从低到高依次为:
debug
: 调试信息,仅在开发环境下显示info
: 普通信息warn
: 警告信息error
: 错误信息none
: 禁用所有日志输出较高级别的日志会包含所有较低级别的日志输出。例如,设置 level 为 'warn' 时,将输出 'warn' 和 'error' 级别的日志。