XuqmGroup-Web/docs-site/docs/rn/common.md

# Common 基础能力

`@xuqm/rn-common` 是所有 RN 扩展包共享的基础依赖，也可以不接入平台配置、不开启登录而
独立使用。

## 网络请求

Common-only 工程可以设置自己的业务地址：

```ts
import {
  apiRequest,
  configureHttp,
  setGlobalApiErrorHandler,
} from '@xuqm/rn-common'

configureHttp({
  baseUrl: 'https://api.example.com',
})

setGlobalApiErrorHandler((report) => {
  // report 只包含经过脱敏的请求诊断信息
  console.warn(report)
})

const profile = await apiRequest<{ name: string }>('/profile', {
  timeoutMs: 15_000,
})
```

安装扩展包并完成自动配置后，扩展模块共享平台地址和当前会话。页面不要重复创建平台
Axios 实例，也不要逐层传递用户 ID 或 Token。

React 页面需要请求状态和运行时响应校验时，可以使用 `useRequest`、`useApi` 和
`usePageApi`。这些 Hooks 接收 URL、请求方法、参数和可选的 Zod Schema，具体类型由
TypeScript 自动提示。

## 文件与下载

```ts
import {
  downloadFileToPath,
  fileExists,
  openLocalFile,
  resolveAvailableFilePath,
} from '@xuqm/rn-common'

const target = await resolveAvailableFilePath('/downloads', 'report.pdf', 'rename')
const task = downloadFileToPath('https://example.com/report.pdf', target, {
  onProgress(progress) {
    console.log(progress.percent)
  },
})

await task.result
if (await fileExists(target)) await openLocalFile(target)
```

常用能力还包括：

- `ensureDirectory`
- `readFileAsBase64`
- `writeBase64File`
- `deleteFile`
- `registerAndroidDownloadedFile`
- `fileNameFromUrl`
- `parseContentDispositionFileName`
- `sanitizeFileName`
- `inferMimeType`

下载任务支持取消，页面卸载时可以调用 `task.cancel()`。

## 日期与过期状态

```ts
import {
  expirationStatus,
  formatDateTime,
  millisecondsUntil,
  toTimestamp,
} from '@xuqm/rn-common'

const status = expirationStatus(endTime)
if (status === 'expired') {
  // 已过期
}

const remaining = millisecondsUntil(endTime)
const display = formatDateTime(endTime)
const timestamp = toTimestamp(endTime)
```

协议要求固定数字格式时使用 `formatNumericDateTime`，不要依赖设备 Locale 的标点顺序。

## 版本判断

```ts
import {
  compareVersions,
  isVersionUpgrade,
  satisfiesVersion,
} from '@xuqm/rn-common'

compareVersions('1.2.0', '1.10.0')
isVersionUpgrade('1.0.0', '1.1.0')
satisfiesVersion('1.2.3', '>=1.0.0 <2.0.0')
```

## 设备信息

```ts
import { getDeviceId, getDeviceInfo, detectPushVendor } from '@xuqm/rn-common'

const deviceId = await getDeviceId()
const device = await getDeviceInfo()
const vendor = detectPushVendor(device.brand)
```

## 公共提示

```ts
import { showAlert, showConfirm, showToast } from '@xuqm/rn-common'

showToast('保存成功')
await showAlert({ title: '提示', message: '操作已完成' })
showConfirm({
  title: '确认删除',
  message: '删除后无法恢复',
  onConfirm() {
    // 执行删除
  },
})
```

宿主可在应用入口统一调用 `configureToast` 对接自己的提示组件，业务页面不应复制多套
Alert/Toast 样式。

## 错误处理

```ts
import { XuqmError } from '@xuqm/rn-common'

try {
  await someOperation()
} catch (error) {
  if (error instanceof XuqmError) {
    switch (error.code) {
      case 'XUQM_NOT_READY':
      case 'XUQM_SERVICE_DISABLED':
        // 非阻断提示或跳过功能
        break
    }
  }
}
```

不要根据英文错误文案判断业务分支，统一使用结构化错误码。