npm package: @microbt/environment
Description: microbt app library for environment
Latest version: 1.2.12

# @microbt/environment 使用文档

## 安装和使用

### 安装

```bash
pnpm add @microbt/environment
```

### 使用

```typescript
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）

**示例**:

```typescript
const env = environment();
console.log(env); // 输出: 'prod'
```

### `isAWSDomain()`

判断当前域名是否为 AWS 环境。

**返回值**: `boolean` - 如果是 AWS 环境返回 `true`，否则返回 `false`

**示例**:

```typescript
const isAWS = isAWSDomain();
console.log(isAWS); // 输出: true 或 false
```

### `region()`

获取当前区域代码。

**返回值**: `string` - 区域代码（如 'cn', 'us' 等）

**示例**:

```typescript
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 值

**示例**:

```typescript
// 中国区开发环境
// 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'

// Eu-Cinmoore 测试环境
// location.host: 'iot-test.eu-cinmoore.com'
baseUrl({ name: 'iot-api' }); // => '//iot-api-test.eu-cinmoore.com'
baseUrl({ name: 'iot-api', path: '/saas' }); // => '//iot-api-test.eu-cinmoore.com/saas'

// Eu-Cinmoore 生产环境
// location.host: 'iot.eu-cinmoore.com'
baseUrl({ name: 'iot-api' }); // => '//iot-api.eu-cinmoore.com'
```

## 混合应用相关函数

### `bridgeCall(method: string, params: Record<string, string>, callback: (resp: string) => void)`

调用原生桥接方法。

**参数**:

- `method`: `string` - 要调用的方法名
- `params`: `Record<string, string>` - 方法参数
- `callback`: `(resp: string) => void` - 回调函数

**示例**:

```typescript
bridgeCall('getUserInfo', { userId: '123' }, (resp) => {
console.log(resp);
```

### `bridgeBootstrap()`

初始化桥接环境。

**示例**:

```typescript
bridgeBootstrap();
```

### `inSuperAcme()`

判断当前是否在 SuperAcme 应用中。

**返回值**: `boolean` - 如果在 SuperAcme 应用中返回 `true`，否则返回 `false`

**示例**:

```typescript
const isInApp = inSuperAcme();
console.log(isInApp); // 输出: true 或 false
```

### `superAcmeVersion()`

获取 SuperAcme 应用的版本信息。

**返回值**: 返回一个包含版本信息的对象：

- 如果在 SuperAcme 应用中且能够解析版本号：

  ```json
  {
    version: string; // 完整版本号，如 "1.2.3"
    major: number; // 主版本号
    minor: number; // 次版本号
    patch: number; // 修订号
  }
  ```

- 如果不在 SuperAcme 应用中或无法解析版本号：

  ```json
  {
    version: 'unknown';
  }
  ```

**示例**:

```typescript
const versionInfo = superAcmeVersion();
console.log(versionInfo);
// 在 SuperAcme 应用中可能输出：{ version: "1.2.3", major: 1, minor: 2, patch: 3 }
// 在非 SuperAcme 应用中输出：{ version: "unknown" }
```

### `getStatusBarHeight()`

> 2.6.0 新增

获取 SuperAcme 应用的状态栏高度信息。

**返回值**: 返回一个包含状态栏高度信息的对象：

```json
{
  top: number;    // 顶部状态栏高度，单位为像素
  bottom: number; // 底部状态栏高度，单位为像素
}
```

如果不在 SuperAcme 应用中或无法解析高度信息，将返回默认值：

```json
{
  "top": 0,
  "bottom": 0
}
```

**示例** :

```typescript
const statusBarHeight = getStatusBarHeight();
console.log(statusBarHeight);
// 可能输出：{ top: 20, bottom: 0 }
// 在非 SuperAcme 应用中输出：{ top: 0, bottom: 0 }
```

## 平台相关函数

### `iOSWebview`

判断当前是否为 iOS Webview 环境。

**类型**: `boolean`

**示例**:

```typescript
if (iOSWebview) {
  console.log('当前为 iOS Webview 环境');
}
```

### `androidWebView`

判断当前是否为 Android Webview 环境。

**类型**: `boolean`

**示例**:

```typescript
if (androidWebView) {
  console.log('当前为 Android Webview 环境');
}
```

## 本地化相关函数

### `getLocale(defaultLocal = 'zh-CN')`

获取当前语言环境。

**参数**:

- `defaultLocal`: `string` - 默认语言环境，默认为 'zh-CN'

**返回值**: `string` - 当前语言环境

**示例**:

```typescript
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`。

**示例**:

```typescript
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 值。

**示例**:

```typescript
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)`**: 添加用户行为数据。

### 参考链接

- [阿里云 ARMS 文档 - API 参考](https://help.aliyun.com/zh/arms/browser-monitoring/developer-reference/api-reference)

## 日志管理

### Logger

提供统一的日志管理功能，支持不同级别的日志输出和配置。

#### 配置选项

```typescript
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[])`: 输出错误级别日志

#### 示例

```typescript
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' 级别的日志。