Common 基础能力

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

网络请求

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

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 自动提示。

文件与下载

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()。

日期与过期状态

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 的标点顺序。

版本判断

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')

设备信息

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

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

公共提示

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

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

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

错误处理

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
    }
  }
}

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

3.5 KiB 原始文件 Blame 文件历史