# @burnt-labs/abstraxion-react-native 中文文档

规范地址：https://npmcn.com/package/%40burnt-labs/abstraxion-react-native/

版本：1\.0\.0-alpha\.25
npm 元数据更新时间：2026-10-23T16:30:39.433Z
中文译文更新时间：2026-11-08T20:32:52.418Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40burnt-labs/abstraxion-react-native
原文对照：https://npmcn.com/package/%40burnt-labs/abstraxion-react-native/?lang=original
项目主页：https://github.com/burnt-labs/xion.js#readme
源码仓库：https://github.com/burnt-labs/xion.js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：246 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：react \>=18\.0\.0，react-native \>=0\.75\.0，react-native-webview \>=13\.0\.0，react-native-quick-crypto ^0\.7\.0，react-native-get-random-values ^1\.11\.0
- 首次发布：2025-03-12T21:00:57.653Z
- 最新版本发布：2026-10-23T16:30:38.992Z
- 近 30 天下载量：2360（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 16 个）

## 中文简介

XION 区块链的原生执行

## 安装

```sh
npm install @burnt-labs/abstraxion-react-native
```

也可以使用：`pnpm add @burnt-labs/abstraxion-react-native`、`yarn add @burnt-labs/abstraxion-react-native`、`bun add @burnt-labs/abstraxion-react-native`

## README

# @burnt-labs/abstraxion- react-native (英语)

对XION Abstraxion认证系统进行回放原生装订. 镜像 : `@burnt-labs/abstraxion-react`,带有用于存储(AsyncStorage)的React-Native适配传输,重定向认证(Expo Web浏览器+深层链接),并嵌入认证(正在应用) `react-native-webview`) (中文(简体) ).

建造在 `@burnt-labs/abstraxion-js` —— 同样的框架- 不可知的运行时间, 赋予 React 和 Svelte 包装器的权力. 这个软件包是React-on-React-Native绑定,而不是单独的认证执行.

## 特征

-   通过 Expo Web浏览器(重定向) 或 in-app Web View(嵌入式) 对 XION 仪表板进行认证
-   AsyncStorage 备份会话存储; 幸存的应用程序重新启动
-   重定向流的深链接回调处理( Expo Linking)
-   下潜 `<AbstraxionEmbed>` 嵌入式WebView流量的组件,在登录和批准期间使用自动模式
-   默认情况下的会话键签名( 无气体); 元账户直接签名通过 `useAbstraxionSigningClient({ requireAuth: true })`
-   管理重定向模式和嵌入模式中支持的认证器(添加/删除密码、 OAuth等)

## 安装

```sh
npm install @burnt-labs/abstraxion-react-native \
  @react-native-async-storage/async-storage \
  expo-web-browser \
  expo-linking
```

您还必须安装( 声明于 `peerDependencies`:

-   `react-native-get-random-values` 需要的,聚居地 `crypto.getRandomValues` 为 keypair 生成.
-   `react-native-quick-crypto` 签署交易所需;本地JSI模块,因此 **没有** 在 Expo Go (使用自定义dev 客户端或模拟器) 中工作.

如果使用嵌入式模式(`<AbstraxionEmbed>`),并安装:

-   `react-native-webview` - 被宣布为 **选项** 相对依赖。 包裹懒惰 --`require`只有在嵌入地上,消费者才会 `redirect` 编号 : `signer` 模式不支付本地模块的成本.

```sh
npm install react-native-webview            # only for embedded mode
```

## 快速启动( 重定向模式)

```tsx
import {
  AbstraxionProvider,
  useAbstraxionAccount,
} from "@burnt-labs/abstraxion-react-native";

const config = {
  rpcUrl: "https://rpc.xion-testnet-2.burnt.com",
  restUrl: "https://api.xion-testnet-2.burnt.com",
  gasPrice: "0.001uxion",
  treasury: "xion13jetl8j9kcgsva86l08kpmy8nsnzysyxs06j4s69c6f7ywu7q36q4k5smc",
  callbackUrl: "your-app-scheme://", // matches your app.json scheme
};

export default function App() {
  return (
    <AbstraxionProvider config={config}>
      <Screen />
    </AbstraxionProvider>
  );
}

function Screen() {
  const { data, isConnected, login, logout } = useAbstraxionAccount();
  return isConnected ? (
    <Text onPress={logout}>Connected as {data.bech32Address}</Text>
  ) : (
    <Text onPress={login}>Sign in</Text>
  );
}
```

## 演示

工作博览会 + React Industrial 演示居住在 [`demos/react-native/`](https://npmcn.com/package/demos/react-native/) 在雷波根。 它练习两种支持的仪表板模式:

-   `/` ——重定向模式(Expo Web浏览器会话+深链接回调)
-   `/embedded` ——嵌入式(在应用中) `<WebView>` + 键 `<AbstraxionEmbed>`(中文(简体) )

见 [`demos/react-native/README.md`](https://npmcn.com/package/demos/react-native/README.md) 用于运行时间选项(iOS simulate, Expo Go,自定义dev客户端)及其之间的取舍.

## 认证模式

| 模式 | 状态 | 运输 |
| --- | --- | --- |
| `redirect` | 获支持 | Expo Web浏览器验证会话 + Expo 链接深链接调用 |
| `embedded` | 获支持 | `react-native-webview` (单位:千美元)`<AbstraxionEmbed>` (单位:千美元) |
| `signer` | 获支持 | 调用程序提供的签名功能( Turnkey, Privy, MetaMask...) |
| `popup` 编号 : `auto` | 仅限网页 | `popup` 需求 `window.open`· ; `auto`'设备嗅觉取决于浏览器API. 在RN上方向供应商投掷两枚 `redirect` 或者说 `embedded` 当然. |

直接签名( U)`requireAuth: true`(在 `redirect` 模式(绕行到仪表板,通过Web浏览器),单位 `embedded` 模式(在 app WebView 中显示的签名UI),和 `signer` 模式(返回直接 `AAClient`) (中文(简体) ).

## 嵌入模式( E)`<AbstraxionEmbed>`(中文(简体) )

嵌入模式将仪表板挂入 a `react-native-webview` `<WebView>` 因此登录, 授予批准, 和签名发生 in-app —— 没有 Expo Web Browser 会话, 没有 深链接回路 .

```tsx
import {
  AbstraxionEmbed,
  AbstraxionProvider,
  useAbstraxionAccount,
} from "@burnt-labs/abstraxion-react-native";

const config = {
  rpcUrl: "https://rpc.xion-testnet-2.burnt.com",
  restUrl: "https://api.xion-testnet-2.burnt.com",
  gasPrice: "0.001uxion",
  authentication: { type: "embedded" as const },
};

export default function App() {
  return (
    <AbstraxionProvider config={config}>
      <AbstraxionEmbed
        idleView="button"
        connectedView="hidden"
        approvalView="modal"
      />
    </AbstraxionProvider>
  );
}
```

地点 `<AbstraxionEmbed>` 一旦在您的应用程序的根部, 一次只应该安装一个嵌入器, 所以控制器的 WebView 容器引用在状态变化中保持稳定 .

### 可见状态矩阵

嵌入有四个用户形态. 根据用户有工作要做时应当发生的情况为每个用户选择道具 _内部_ 仪表板(登录、批准、管理验证器)与嵌入器何时应避开.

| 状态 | 触发 | 默认渲染 |
| --- | --- | --- |
| 空闲( 还没有会话) | `!isConnected && !isConnecting` | `idleView="button"` 显示登录按钮; `"fullview"` 显示消费者的WebView `style`· ; `"hidden"` 无法让人看见. |
| 连接( 正在进行中) | `isConnecting` | Webview 自动推动全屏 `<Modal>` 何时 `idleView !== "fullview"` 财务报告和审定财务报表 `approvalView === "modal"`. 解除模式调用 `controller.cancelLogin()` 并返回闲置. |
| 已连接( 无待核准) | `isConnected && !isAwaitingApproval` | `connectedView="hidden"` 崩溃为 0×0; `"visible"` 在消费者家制作 `style`。 。 。 . |
| 待核准 | `isConnected && isAwaitingApproval` | `approvalView="modal"` 在中心打开 Webview `<Modal>` (违约); `"inline"` 在消费者家制作 `style`。 。 。 . |

#### 为什么连接模式存在

`react-native-webview` 当母体没有宽度或高度时,则不可见。 没有自动模式, 嵌入式配置为 `idleView="button"` 或者说 `idleView="hidden"` 没有 `style` 就会跌到0×0 `<View>` 开始登录的那一刻——用户无法看到仪表板的验证器取出器. 自动模式 `isConnecting` 把脚枪取出 设定 `approvalView="inline"` 如果您想要自己管理连接布局.

#### 当你需要通过 `style`

只有当WebView与您的布局相通时——即, `idleView="fullview"`, (中文(简体) ), `connectedView="visible"`,或 `approvalView="inline"`。崩溃和模式路径忽略 `style`。 。 。 .

### `<AbstraxionEmbed>` 道具和裁判

```typescript
interface AbstraxionEmbedProps {
  /** Default "button". */
  idleView?: "button" | "fullview" | "hidden";
  /** Default: same as idleView. */
  disconnectedView?: "button" | "fullview" | "hidden";
  /** Default "hidden". */
  connectedView?: "hidden" | "visible";
  /** Default "modal". */
  approvalView?: "modal" | "inline";
  /** Override the default "Sign in with XION" label. */
  loginLabel?: ReactNode;
  /** Required only when WebView renders inline (see "When you need to pass style" above). */
  style?: ViewStyle;
}

interface AbstraxionEmbedHandle {
  /** Force a reload of the dashboard WebView. Rarely needed. */
  reload(): void;
}
```

`AbstraxionEmbed` 是一个 `forwardRef` 部分——通过回拨 `reload()` 如果您的应用程序需要从被卡住的 WebView 恢复.

## 钩子

### `useAbstraxionAccount`

```typescript
const {
  data, // { bech32Address: string }
  isConnected, // session present
  isConnecting, // login in progress
  isInitializing, // restoring session from storage on mount
  isDisconnected, // true after explicit logout (distinct from idle)
  isLoading, // isInitializing || isConnecting
  isReturningFromAuth, // redirect mode only — handling deep-link callback
  isLoggingIn, // isConnecting && !isInitializing
  isError,
  error,
  login, // () => Promise<void>
  logout, // () => Promise<void>
} = useAbstraxionAccount();
```

### `useAbstraxionClient`

只读 CosmWasm 客户端 .

```typescript
const { client, error } = useAbstraxionClient();
// client: CosmWasmClient | undefined
```

### `useAbstraxionSigningClient`

默认返回无气会话键符号 。 过 `{ requireAuth: true }` 获取直接元账户签名符.

```typescript
const { client, signArb, rpcUrl, error, signResult, clearSignResult } =
  useAbstraxionSigningClient();
// client: GranteeSignerClient | undefined — session-key signing
// signArb: (signerAddress, message) => Promise<string>

const direct = useAbstraxionSigningClient({ requireAuth: true });
// embedded mode  → RequireSigningClient that pops the approval modal in-WebView
// redirect mode  → RequireSigningClient that round-trips through WebBrowser;
//                  the signed result lands in `direct.signResult` after the deep link
//                  fires. Call `direct.clearSignResult()` after consuming.
// signer mode    → AAClient built from your injected signing function
```

### `useManageAuthenticators`

在连接的账户上添加或移除认证符(passkeys,OAuth等).

```typescript
const {
  manageAuthenticators, // () => Promise<void>
  isSupported, // true in redirect or embedded mode
  unsupportedReason, // string when isSupported === false (e.g. signer mode)
  manageAuthResult, // redirect mode only — populated after deep-link return
  clearManageAuthResult,
} = useManageAuthenticators();
```

在重定向模式下,结果落在 `manageAuthResult` 一旦Expo Web浏览器关闭;在嵌入式模式下,调用直接解决,因为仪表板在WebView桥上报回.

### `useAbstraxionContext`

逃逸孵出到完整的提供者上下文. 更喜欢上面的打出钩子 用于覆盖的一切.

## 配置

```typescript
interface AbstraxionConfig {
  // Network: the only chain setting most apps need. Chain ID, RPC, REST, gas
  // price, fee granter, AA API and indexer URLs are resolved from it.
  // Defaults to testnet when neither network nor chainId is set.
  network?: "mainnet" | "testnet";

  // Overrides for a local or custom chain.
  chainId?: string;
  rpcUrl?: string;
  restUrl?: string;
  gasPrice?: string; // e.g. "0.001uxion"
  feeGranter?: string;

  // Optional grant configuration.
  treasury?: string;
  bank?: SpendLimit[];
  stake?: boolean;
  contracts?: ContractGrantDescription[];

  // Auth.
  authentication?:
    | { type: "redirect"; callbackUrl?: string; authAppUrl?: string }
    | { type: "embedded"; iframeUrl?: string }
    | {
        type: "signer";
        getSignerConfig: () => Promise<SignerConfig>;
        // Overrides for a local or custom AA API deployment.
        aaApiUrl?: string;
        smartAccountContract?: { addressPrefix?: string };
      };

  // Convenience for redirect mode — equivalent to authentication.callbackUrl.
  callbackUrl?: string;
}
```

主网上的签名程序只需要:

```typescript
const config = {
  network: "mainnet",
  treasury: "xion1...", // your app's treasury, if it grants permissions
  authentication: { type: "signer", getSignerConfig },
};
```

若为 `authentication` 删除,提供者默认为 `{ type: "redirect", callbackUrl }`。 。 。 . `{ type: "popup" }` 财务报告和审定财务报表 `{ type: "auto" }` 扔在供应商上架上——它们只使用网络.

## 深连接( 直接模式)

重定向流需要深链接回调, 这样仪表板就可以将用户( 和赠与者地址) 交给您的应用 .

为博览会, in `app.json`数字 :

```json
{
  "expo": {
    "scheme": "your-app-scheme",
    "android": {
      "intentFilters": [
        {
          "action": "VIEW",
          "category": ["DEFAULT", "BROWSABLE"],
          "data": { "scheme": "your-app-scheme" }
        }
      ]
    }
  }
}
```

对于赤裸反射原生,配置每个平台文件的深层链接. 您传递到的回调 URL `AbstraxionConfig.callbackUrl` 与上述计划相符。 Expo Web Browser的认证会话 API 处理在重定向后自动解除程序内浏览器.

## 建筑和出口

```typescript
import {
  // Provider + context
  AbstraxionProvider,
  AbstraxionContext,

  // Hooks
  useAbstraxionAccount,
  useAbstraxionClient,
  useAbstraxionSigningClient,
  useManageAuthenticators,

  // Embedded mode
  AbstraxionEmbed,
  type AbstraxionEmbedHandle,
  type AbstraxionEmbedProps,

  // Strategies (advanced — usually you don't import these directly)
  ReactNativeStorageStrategy, // wraps AsyncStorage as the SDK's StorageStrategy
  ReactNativeRedirectStrategy, // wraps Expo WebBrowser + Linking as RedirectStrategy
  RNWebViewIframeTransport, // bridges <AbstraxionEmbed>'s WebView to IframeController
  type RNWebViewControl,
} from "@burnt-labs/abstraxion-react-native";
```

供应商将这些策略接入 `createAbstraxionRuntime` 从 `@burnt-labs/abstraxion-js` 并揭露其后果 `runtime.controller` 通过上下文。 虎克从运行时间的外部商店读取通过 `useSyncExternalStore`,因此账户状态在React 18同时渲染时保持不变.

## 许可证

麻省理工学院

## 常见问题

### @burnt-labs/abstraxion-react-native 是什么？

XION 区块链的原生执行

### 如何安装 @burnt-labs/abstraxion-react-native？

在项目目录运行 npm install @burnt-labs/abstraxion-react-native，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18\.0\.0）、react-native（\>=0\.75\.0）、react-native-quick-crypto（^0\.7\.0）、react-native-get-random-values（^1\.11\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @burnt-labs/abstraxion-react-native 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @burnt-labs/abstraxion-react-native 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @burnt-labs/abstraxion-react-native 可以商用吗？

@burnt-labs/abstraxion-react-native 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @burnt-labs/abstraxion-react-native 的下载量有多少？

根据 npm 官方下载统计，@burnt-labs/abstraxion-react-native 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,360 次，日均约 79 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @burnt-labs/abstraxion-react-native 还在维护吗？

最新版本 1\.0\.0-alpha\.25 发布于 2026/10/24（16 天前）；至今共发布 26 个版本，其中过去 12 个月发布了 16 个；首次发布于 2025/03/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。