# @convex-dev/expo-push-notifications 中文文档

规范地址：https://npmcn.com/package/%40convex-dev/expo-push-notifications/

版本：0\.4\.2
npm 元数据更新时间：2026-10-10T01:13:44.131Z
中文译文更新时间：2026-11-10T17:47:33.389Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40convex-dev/expo-push-notifications
原文对照：https://npmcn.com/package/%40convex-dev/expo-push-notifications/?lang=original
项目主页：https://github.com/get-convex/expo-push-notifications#readme
源码仓库：https://github.com/get-convex/expo-push-notifications

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

- 包体积（解压后）：301 kB，84 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：convex ^1\.46\.0
- 首次发布：2024-10-14T17:20:31.595Z
- 最新版本发布：2026-10-10T01:13:43.694Z
- 近 30 天下载量：240689（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 10 个）

## 中文简介

用于与世博会管理推力通知的Convex组件.

## 安装

```sh
npm install @convex-dev/expo-push-notifications
```

也可以使用：`pnpm add @convex-dev/expo-push-notifications`、`yarn add @convex-dev/expo-push-notifications`、`bun add @convex-dev/expo-push-notifications`

## README

# Convex 按下通知组件

[![npm version](https://badge.fury.io/js/@convex-dev%2Fexpo-push-notifications.svg)](https://badge.fury.io/js/@convex-dev%2Fexpo-push-notifications)

这是与 [博览会的推力通知 API](https://docs.expo.dev/push-notifications/overview/) 允许向您的应用程序的用户发送移动推进通知。 会批出 打给博览会的API 并处理重试送货.

Demo GIF

![Demo of sending push notifications](https://npmcn.com/package/%40convex-dev/expo-push-notifications/output.gif)

示例用法:

```tsx
// App.tsx
<Button
  onPress={() => {
    void convex.mutation(api.example.sendPushNotification, {
      to: otherUser,
      title: `Hi from ${currentUser.name}`,
    });
  }}
>
  <Text>Say hi!</Text>
</Button>
```

```typescript
// convex/example.ts
export const sendPushNotification = mutation({
  args: { title: v.string(), to: v.id("users") },
  handler: async (ctx, args) => {
    // Sending a notification
    return pushNotifications.sendPushNotification(ctx, {
      userId: args.to,
      notification: {
        title: args.title,
      },
    });
  },
});
```

## 预先要求: Convex

你需要一个现有的 Convex 项目来使用组件。 Convex 是一个主机 后端平台,包括数据库、无服务器功能和多一个吨 可以学习 [这里](https://docs.convex.dev/get-started)。 。 。 .

运行 `npm create convex` 或遵循其中任何一条 [快速启动](https://docs.convex.dev/home) 来设置一个.

## 安装

安装组件包 :

```
npm i @convex-dev/expo-push-notifications
```

创建一个 `convex.config.ts` 应用程序中的文件 `convex/` 文件夹并安装 通过调用 `use`数字 :

```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import pushNotifications from "@convex-dev/expo-push-notifications/convex.config.js";

const app = defineApp();
app.use(pushNotifications, { env: {} });
// other components

export default app;
```

说明 `PushNotifications` convex 函数中的客户端 :

```ts
// convex/example.ts
import { PushNotifications } from "@convex-dev/expo-push-notifications";

const pushNotifications = new PushNotifications(components.pushNotifications);
```

它使用可选类型参数(默认为 `Id<"users">`用于 类型,用于驱动通知收件人的独有标识符 :

```ts
import { PushNotifications } from "@convex-dev/expo-push-notifications";

export type Email = string & { __isEmail: true };

const pushNotifications = new PushNotifications<Email>(
  components.pushNotifications,
);
```

### 正在使用 Expo 访问符认证( 可选)

如果你的博览会项目有 [加强推进安全](https://docs.expo.dev/push-notifications/sending-notifications/#additional-security) 启用后, 每一个对 Expo push API 的请求都必须包含访问符 。 改为: 选择加入, 从您的 Expo 访问符设置中生成一个令牌, 设置为您部署中的 Convex 环境变量 :

```bash
npx convex env set EXPO_ACCESS_TOKEN <your-token>
```

并经由 `app.use`数字 :

```ts
// convex/convex.config.ts
const app = defineApp({
  env: {
    EXPO_ACCESS_TOKEN: v.optional(v.string()),
  },
});

app.use(pushNotifications, {
  env: {
    EXPO_ACCESS_TOKEN: app.env.EXPO_ACCESS_TOKEN,
  }
});
```

## 注册一个用户以进行推进通知

在世博会文档之后获得用户的推出通知符 [这里](https://docs.expo.dev/push-notifications/push-notifications-setup/#registering-for-push-notifications), (中文(简体) ), 并使用 Convex 的变体记录:

```ts
// convex/example.ts
export const recordPushNotificationToken = mutation({
  args: { token: v.string() },
  handler: async (ctx, args) => {
    const userId = await getAuthUserId(ctx);
    await pushNotifications.recordToken(ctx, {
      userId,
      pushToken: args.token,
    });
  },
});
```

您可以暂停并恢复为用户发送按键通知 `pausePushNotifications` 财务报告和审定财务报表 `resumePushNotifications` 方法。 。 .

要确定用户是否有一个符号及其暂停状态, 您可以使用 `getStatusForUser`。 。 。 .

## 发送通知

```ts
// convex/example.ts
export const sendPushNotification = mutation({
  args: { title: v.string(), to: v.string() },
  handler: async (ctx, args) => {
    const pushId = await pushNotifications.sendPushNotification(ctx, {
      userId: args.to,
      notification: {
        title: args.title,
      },
    });
  },
});
```

这个 `notification` 对象支持 [博览推取信件格式](https://docs.expo.dev/push-notifications/sending-notifications/#message-request-format)。 。 。 .

您可以使用从 `sendPushNotifications` 以查询 使用 `getNotification`。在查询中使用此选项允许您 同意通知的地位.

您也可以通过 `getNotificationsForUser`。 。 。 .

## 如何交付

1.  **如何插入个别通知**
    
    `sendPushNotification` 财务报告和审定财务报表 `sendPushNotificationBatch` 先看那个 用户的 Expo 标志 。 如果用户没有符号,则组件会丢出或者 返回时 `null` 取决于 `allowUnregisteredTokens`。如果用户的符号是 暂停,通知被撤销 `null` 已返回。 否则 组件插入到 `notifications` 表格为 `state = "awaiting_delivery"`,失败计数 `0`简称 用于分批的时标.
    
2.  **运货员如何活活活活的**
    
    每个成功的插入都叫一个内部助手 确保准确的一位 未来批量运行将安排在有资格的最早通知中 部分。 如果新插入的通知比 目前计划运行,组件取消稍后的唤醒和 早点重新安排 当这批货被唤醒时 要么: 找到工作和安排一个或多个工作,或找不到工作和 清除待批量运行的标记。 每次工作完成后 如果还剩工作,组件将再次安排下批次通过.
    
3.  **工作池线条如何平行工作**
    
    每批都成为一份工作。 工作池限制了其中多少 工作可同时通过 `maxParallelism`,并保持自己的等待和 内部管理簿记。 在将一批货物交给工作池之前 标出该批通知 `in_progress`,从而防止 从同一批次选择同一通知的组件 时间.
    
4.  **部分失败如何反映**
    
    博览会可以接受批次中的某些通知,拒绝其他通知 反应。 构成部分记录每份通知的结果:已交付 通知最后敲定为 `delivered`,不可退票的出票失败为: 定稿 `failed`,并记录了临时罚单故障,例如 `MessageRateExceeded` 移动到 `needs_retry`。失败的通知是 在同一 HTTP 请求中没有重新进行内置处理; 它们由稍后取取 批次通过。 请求级别失败由工作池单独处理 重试策略 .
    
5.  **暂时失败如何被推迟**
    
    有两层复试. 如果整个博览会请求失败, 工作池 重试那批量的指数回放。 如果 Expo 返回成功 批量回复, 并附带一些单个临时消息故障, 这些 将通知移回队列中以 `needs_retry` 并用指数推进其下一个合格部分 备份。 下一个批次通过优先 `needs_retry` 通知结束 全新的,一旦他们的预定部分 符合条件,它睡觉 直到投票结束.
    
6.  **关闭和暂停符号如何相互作用**
    
    插入前暂停了指针短路, 因此暂停的用户不会创建 已排队通知 . `shutdown()` 取消未来的批量调度和 取消尚未开始的待办工作。 蝙蝠已经 标记 `in_progress` 允许排水 `restart()` 恢复排程 一旦飞行通知完成.
    

## 解决问题

为增加伐木,提供 `PushNotifications` 带有 `logLevel` 输入 构造器 :

```ts
const pushNotifications = new PushNotifications(components.pushNotifications, {
  logLevel: "DEBUG",
});
```

推进通知发送器可以优雅地关闭,然后重新启动 使用 `shutdown` 财务报告和审定财务报表 `restart` 方法。 。 .

## 常见问题

### @convex-dev/expo-push-notifications 是什么？

用于与世博会管理推力通知的Convex组件\.

### 如何安装 @convex-dev/expo-push-notifications？

在项目目录运行 npm install @convex-dev/expo-push-notifications，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：convex（^1\.46\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @convex-dev/expo-push-notifications 支持 TypeScript 吗？

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

### @convex-dev/expo-push-notifications 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @convex-dev/expo-push-notifications 可以商用吗？

@convex-dev/expo-push-notifications 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @convex-dev/expo-push-notifications 的下载量有多少？

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

### @convex-dev/expo-push-notifications 还在维护吗？

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