92 行
3.6 KiB
Markdown
92 行
3.6 KiB
Markdown
# XuqmGroup React Native SDK
|
||
|
||
XuqmGroup 通用 React Native SDK 工作区。`@xuqm/rn-common` 是唯一基础包；其余扩展包都复用 common 的配置、初始化、会话、网络和通用能力。仅使用 common 时不放配置文件、不包装 Metro，也不要求初始化或登录；使用任一官方扩展时，由 `withXuqmConfig()` 在业务入口前自动启动一次共享上下文。
|
||
|
||
## 包结构
|
||
|
||
| 包 | 用途 | 可独立使用 |
|
||
| --- | --- | --- |
|
||
| `@xuqm/rn-common` | 可选 SDK 上下文、网络、文件、时间、加密、设备与通用 UI | 是，且无需初始化或登录 |
|
||
| `@xuqm/rn-update` | App 更新、RN 插件注册、下载、校验与运行 | 否，依赖 common |
|
||
| `@xuqm/rn-xwebview` | WebView、JSBridge、权限与下载 | 否，依赖 common |
|
||
| `@xuqm/rn-bugcollect` | 错误、事件、漏斗和批量上报 | 否，依赖 common |
|
||
| `@xuqm/rn-im` | IM 连接、消息和本地数据 | 否，依赖 common |
|
||
| `@xuqm/rn-push` | 多厂商原生推送桥接 | 否，依赖 common |
|
||
|
||
根包 `@xuqm/rn-sdk` 只用于仓库内聚合开发，不对外发布。应用应按需安装具体包，避免引入未使用的原生能力。
|
||
|
||
## 安装
|
||
|
||
项目 `.npmrc`：
|
||
|
||
```ini
|
||
registry=https://registry.npmjs.org/
|
||
@xuqm:registry=https://nexus.xuqinmin.com/repository/npm/
|
||
```
|
||
|
||
最小安装：
|
||
|
||
```bash
|
||
pnpm add @xuqm/rn-common axios \
|
||
@react-native-async-storage/async-storage
|
||
```
|
||
|
||
按需增加扩展包，例如：
|
||
|
||
```bash
|
||
pnpm add @xuqm/rn-update @xuqm/rn-xwebview @xuqm/rn-bugcollect
|
||
```
|
||
|
||
## common 独立使用
|
||
|
||
只安装 common 时，可以直接调用文件、时间、网络、加密、设备和 UI 能力，不要求配置、初始化或登录。`apiRequest` 使用绝对 URL，或先调用 `configureHttp` 配置基础地址即可。
|
||
|
||
## 扩展包一次初始化、一次登录
|
||
|
||
把平台生成的 `config.xuqmconfig` 放在 `src/assets/config/`，然后只包装一次 Metro 配置。使用 update 插件化时采用 update 组合器（它已包含 common 自动初始化）：
|
||
|
||
```js
|
||
const {getDefaultConfig} = require('@react-native/metro-config');
|
||
const {withXuqmModuleConfig} = require('@xuqm/rn-update/metro');
|
||
|
||
module.exports = withXuqmModuleConfig(getDefaultConfig(__dirname));
|
||
```
|
||
|
||
不使用 update 时仍调用 `@xuqm/rn-common/metro` 的 `withXuqmConfig()`。两种组合器都会把初始化模块注册为 Metro pre-main module，避免 `inlineRequires` 延迟扩展包加载。应用登录成功后只更新一次公共会话：
|
||
|
||
```ts
|
||
import {XuqmSDK} from '@xuqm/rn-common';
|
||
|
||
await XuqmSDK.awaitInitialization();
|
||
await XuqmSDK.login({
|
||
userId: 'user-id',
|
||
accessToken: 'http-access-token',
|
||
userSig: 'optional-im-credential',
|
||
});
|
||
|
||
await XuqmSDK.logout();
|
||
```
|
||
|
||
扩展包通过 `@xuqm/rn-common/internal` 接收同一次会话变化。宿主业务代码不得导入该内部子路径，也不得逐级传递公共 token 或用户状态。
|
||
|
||
无法使用配置文件自动初始化时，才调用一次：
|
||
|
||
```ts
|
||
await XuqmSDK.initialize({appKey: 'app-key'});
|
||
```
|
||
|
||
## 开发与验证
|
||
|
||
要求 Node.js 22、Corepack 和 pnpm 11：
|
||
|
||
```bash
|
||
corepack pnpm install
|
||
corepack pnpm validate
|
||
```
|
||
|
||
`validate` 会执行全部包的 TypeScript 校验和测试。开发 alpha 及正式包都只能由 Jenkins 发布到 Nexus，开发机不执行 npm publish。
|
||
|
||
集成 update 的宿主由 `xuqm-rn start` 和 `xuqm-rn run android` 统一代理 Metro 与 Android Debug 启动；宿主只保留简短的 `start/android` package script。
|
||
|
||
每个扩展包的安装要求与 API 以对应 `packages/<name>/README.md` 为准。整体设计见 `docs/架构总览.md`，公共接口见 `docs/SDK-API参考.md`。
|
