@h-ai/capacitor

Capacitor 原生桥接模块，为 hai Framework 移动应用提供原生安全 Token 存储、设备信息、推送通知、相机与状态栏等能力的统一封装。

支持的能力

• Token 存储：@aparajita/capacitor-secure-storage（原生必需）。Android 使用 KeyStore + 加密 SharedPreferences，iOS 使用 Keychain；Web 不回退。
• Preferences：@capacitor/preferences（必需）。通用偏好数据存储，适合非敏感配置，不用于认证 Token。
• 设备信息：@capacitor/device（可选）。平台、版本、型号检测。
• 应用版本：@capacitor/app（可选）。读取 appVersion / appBuild。
• 推送通知：@capacitor/push-notifications（可选）。注册 FCM/APNs Token、监听推送事件。
• 相机/相册：@capacitor/camera（可选）。拍照、选取相册图片。
• 状态栏：@capacitor/status-bar（可选）。沉浸式、背景色、样式配置。

快速开始

import { capacitor } from '@h-ai/capacitor'

// 应用启动时初始化（检测 Capacitor 环境）
const result = await capacitor.init()
if (!result.success) {
  // 非 Capacitor 环境（纯 Web）
}

与 api-client 配合的 Token 安全存储

import { apiClient } from '@h-ai/api-client'
import { createCapacitorTokenStorage } from '@h-ai/capacitor'

await apiClient.init({
  baseUrl: 'https://api.example.com/v1',
  auth: {
    storage: createCapacitorTokenStorage(),
    refreshPath: '/auth/refresh',
  },
})

createCapacitorTokenStorage() 仅在 Android/iOS 原生环境中持久化 token，并要求已安装 @aparajita/capacitor-secure-storage。纯 Web 环境下不会退化到 localStorage；get*() 返回 null，set*() / clear() 为 no-op。

设备信息与推送

import { capacitor } from '@h-ai/capacitor'

const info = await capacitor.device.getInfo()
if (info.success) {
  // info.data.platform — 'android' | 'ios' | 'web'
}

const reg = await capacitor.push.register()
if (reg.success) {
  // reg.data.token — FCM/APNs 推送 Token
}

状态栏

import { capacitor } from '@h-ai/capacitor'

await capacitor.statusBar.configure({
  style: 'dark',
  overlay: true,
  backgroundColor: '#ffffff',
})

相机

const photo = await capacitor.camera.takePhoto({
  source: 'camera',
  resultType: 'base64',
  quality: 80,
})

Preferences

await capacitor.preferences.set('my_key', 'value')
const result = await capacitor.preferences.get('my_key')
await capacitor.preferences.remove('my_key')

capacitor.preferences 适合保存语言、主题、草稿等普通偏好数据；认证 Token 请使用 createCapacitorTokenStorage()。

配置

本模块无配置文件。capacitor.init() 仅检测 Capacitor 运行环境是否可用。

Capacitor 应用必须使用 SPA 模式：

// src/routes/+layout.ts
export const prerender = true
export const ssr = false

错误处理

所有异步 API 返回 HaiResult<T>，不会直接 throw：

import { capacitor, HaiCapacitorError } from '@h-ai/capacitor'

const result = await capacitor.camera.takePhoto({ source: 'camera' })
if (!result.success) {
  if (result.error.code === HaiCapacitorError.CAMERA_FAILED.code) {
    // 相机权限被拒绝或插件未安装
  }
}

常用错误码：

| 错误码 | code | 说明 | | --------------------------------------------- | ------------------- | -------------------- | | HaiCapacitorError.INIT_FAILED | hai:capacitor:001 | 初始化失败 | | HaiCapacitorError.NOT_AVAILABLE | hai:capacitor:002 | 能力不可用 | | HaiCapacitorError.INIT_IN_PROGRESS | hai:capacitor:003 | 初始化进行中 | | HaiCapacitorError.NOT_INITIALIZED | hai:capacitor:010 | 未初始化 | | HaiCapacitorError.PREFERENCES_GET_FAILED | hai:capacitor:011 | Preferences 读取失败 | | HaiCapacitorError.PREFERENCES_SET_FAILED | hai:capacitor:012 | Preferences 写入失败 | | HaiCapacitorError.PREFERENCES_REMOVE_FAILED | hai:capacitor:013 | Preferences 删除失败 | | HaiCapacitorError.DEVICE_INFO_FAILED | hai:capacitor:020 | 设备信息获取失败 | | HaiCapacitorError.APP_VERSION_FAILED | hai:capacitor:021 | 应用版本获取失败 | | HaiCapacitorError.PUSH_REGISTER_FAILED | hai:capacitor:030 | 推送注册失败 | | HaiCapacitorError.PUSH_LISTEN_FAILED | hai:capacitor:031 | 推送监听失败 | | HaiCapacitorError.CAMERA_FAILED | hai:capacitor:040 | 相机操作失败 | | HaiCapacitorError.STATUS_BAR_FAILED | hai:capacitor:050 | 状态栏操作失败 |

测试

pnpm --filter @h-ai/capacitor test

由于原生插件依赖，测试中需 mock @capacitor/* 模块。

License

Apache-2.0