# @cap-js/notifications 中文文档

规范地址：https://npmcn.com/package/%40cap-js/notifications/

版本：1\.1\.1
npm 元数据更新时间：2026-09-29T08:03:55.401Z
中文译文更新时间：2026-11-09T05:25:19.301Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cap-js/notifications
原文对照：https://npmcn.com/package/%40cap-js/notifications/?lang=original
项目主页：https://cap.cloud.sap/
源码仓库：https://github.com/cap-js/notifications

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

- 包体积（解压后）：87.4 kB，11 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.0\.0
- 运行依赖：3 个
- peer 依赖：@sap/cds \>=8\.0，@sap/cds-dk \>=8\.0
- 首次发布：2023-10-30T09:11:05.022Z
- 最新版本发布：2026-09-29T08:03:55.064Z
- 近 30 天下载量：7314（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 4 个）

## 中文简介

CDS插件在SAP Build WorkZone中为业务通知提供支持.

## 安装

```sh
npm install @cap-js/notifications
```

也可以使用：`pnpm add @cap-js/notifications`、`yarn add @cap-js/notifications`、`bun add @cap-js/notifications`

## README

[![REUSE status](https://api.reuse.software/badge/github.com/cap-js/notifications)](https://api.reuse.software/info/github.com/cap-js/notifications)

# 通知插件

这个 `@cap-js/notifications` 软件包是一个 [CDS 插件](https://cap.cloud.sap/docs/node.js/cds-plugins#cds-plugin-packages) 支持在SAP建设工作区内发布业务通知.

### 目录

-   [设置](https://npmcn.com/package/%40cap-js/notifications/#readme-setup)
-   [开始](https://npmcn.com/package/%40cap-js/notifications/#readme-getting-started)
-   [运行样本](https://npmcn.com/package/%40cap-js/notifications/#readme-running-the-sample)
-   [定义通知类型](https://npmcn.com/package/%40cap-js/notifications/#readme-define-notification-types)
-   [发送通知](https://npmcn.com/package/%40cap-js/notifications/#readme-send-notifications)
-   [实体通知](https://npmcn.com/package/%40cap-js/notifications/#readme-entity-notifications)
-   [API 参考](https://npmcn.com/package/%40cap-js/notifications/#readme-api-reference)
-   [本地测试驱动](https://npmcn.com/package/%40cap-js/notifications/#readme-test-drive-locally)
-   [在生产中运行](https://npmcn.com/package/%40cap-js/notifications/#readme-run-in-production)
-   [高级使用](https://npmcn.com/package/%40cap-js/notifications/#readme-advanced-usage)
    -   [自定义通知类型路径](https://npmcn.com/package/%40cap-js/notifications/#readme-custom-notification-types-path)
    -   [自定义通知类型前缀](https://npmcn.com/package/%40cap-js/notifications/#readme-custom-notification-type-prefix)
    -   [自定义目标名称](https://npmcn.com/package/%40cap-js/notifications/#readme-custom-destination-name)
    -   [认证标识符](https://npmcn.com/package/%40cap-js/notifications/#readme-authentication-identifier)
    -   [默认通道](https://npmcn.com/package/%40cap-js/notifications/#readme-default-channels)
    -   [发件箱行为](https://npmcn.com/package/%40cap-js/notifications/#readme-outbox-behavior)
    -   [关闭插件](https://npmcn.com/package/%40cap-js/notifications/#readme-disabling-the-plugin)
    -   [低级通知 API](https://npmcn.com/package/%40cap-js/notifications/#readme-low-level-notifications-api)
-   [捐款](https://npmcn.com/package/%40cap-js/notifications/#readme-contributing)
-   [行为守则](https://npmcn.com/package/%40cap-js/notifications/#readme-code-of-conduct)
-   [许可证发放](https://npmcn.com/package/%40cap-js/notifications/#readme-licensing)

## 设置

**所需经费:** 节点.js... 20, `@sap/cds` >=八.

要启用通知, 只需在您的工程中添加此自配置插件包 :

```sh
npm add @cap-js/notifications
```

## 开始

安装插件后,您可以通过两种方式发送通知:

### 快速启动: 直接通知

使用 `notify()`数字 :

```js
const alert = await cds.connect.to("notifications")

await alert.notify({
  recipients: ["user@example.com"],
  title: "Book Order Received",
  description: 'Your order for "Wuthering Heights" is being processed.'
})
```

### 建议: 界定通知类型

在服务模式中定义通知事件 `@notification`数字 :

```cds
using { CatalogService } from './cat-service';

extend service CatalogService with {
  @notification: {
    title: 'Book {{title}} Ordered',
    subtitle: '{{buyer}} ordered {{title}}'
  }
  event BookOrdered {
    title : String;
    buyer : String;
  }
}
```

从您的服务处理器中释放事件 :

```js
this.on("submitOrder", async req => {
  // ... process order ...

  await this.emit("BookOrdered", {
    title: book.title,
    buyer: req.user.id,
    recipients: ["user@example.com"]
  })
})
```

插件拦截事件并自动发送通知. 在当地开发期间,通知会被打印到控制台. 不需要 BTP 连接 .

## 运行样本

本节使用本寄存器中包含的书店样本.

### 1\. 启动样本应用

```sh
cd tests/bookshop
npm install
cds watch
```

服务器开始于 [http://localhost:4004 (英语)](http://localhost:4004/)。在本地开发过程中,插件将通知打印到控制台,因此尚不需要BTP账户.

### 2\. 触发通知

书店 `submitOrder` 动作减少账本存量并输出 a `BookOrderedNotify` 活动。 插件截取该事件并发送通知 .

打开 `tests/bookshop/test/http/CatalogService.http` 在VS代码中并单击 **发送请求** 上层 `submitOrder` 块。 此文件有服务器 URL 和预配置的证书 .

在服务器控制台中, 您可以看到打印的通知, 以确认通知成功 .

### 3\. 自定义通知类型

打开 `tests/bookshop/srv/notifications.cds`此文件定义了 `BookOrderedNotify` 及其所有活动 `@notification` 说明。 更改字幕模板以包含数量 :

```cds
// Before
subtitle: '{i18n>BOOK_ORDERED_SUBTITLE}',

// After
subtitle: '{{buyer}} ordered {{quantity}}x {{title}}',
```

保存文件并 `cds watch` 自动重装。 再次发送请求,更新后字幕出现在控制台输出中. 从这里开始,尝试调整优先级表达式,添加一个 `@description`,或探索活动的其他说明.

### 4\. 连接SAP建设区

要看到通知出现在工作区,需要配置SAP建设工作区的BTP子账户和SAP警报通知服务.

1.  跟着 [SAP 构建工作区设置指南](https://help.sap.com/docs/build-work-zone-standard-edition/sap-build-work-zone-standard-edition/enabling-notifications-for-custom-apps-on-sap-btp-cloud-foundry) 以订阅服务并配置所需的 `SAP_Notifications` 目标在您的子账户中 .
2.  用 CF 将本地环境绑入目的服务实例 `cds bind`运行 `cds watch --profile hybrid` 从本地机器连接到 BTP 目的地.

启动时, 插件自动注册您的通知类型 。 提交命令后,将向工作区内的铃声发送通知,通知接收者.

> \[!注\] 书店样本默认使用程序内通知. 工作区铃声图标显示由SAP BTP全球用户ID(UUID)识别的收件人的通知. 为了测试电子邮件的发送,还需要额外的设置。 关于启用,见 [电子邮件发送](https://npmcn.com/package/%40cap-js/notifications/#readme-email-delivery) 财务报告和审定财务报表 [默认邮件发送](https://npmcn.com/package/%40cap-js/notifications/#readme-default-email-delivery)。关于所需的BTP配置,请参见 [SMTP 邮件目的地指南](https://help.sap.com/docs/build-work-zone-standard-edition/sap-build-work-zone-standard-edition/configuring-smtp-mail-destination)。 。 。 .

## 定义通知类型

通知的依据是: _通知类型_:定义通知外观的模板,包括标题、字幕和电子邮件内容。 这些类型可以有两种方式定义,两种类型都可以一起使用,并在启动时被合并.

### 备选案文A:CDS说明(建议)

建议的做法是,在服务模式中直接界定通知类型,对事件进行注解 `@notification`。插件在启动时自动发现并注册它们.

在您定义一个事件 `srv/` 模式 :

```cds
using { CatalogService } from './cat-service';

extend service CatalogService with {

  @description: 'Sent when a book is ordered'
  @notification: {
    title        : 'Book {{title}} Ordered',
    publicTitle  : 'Book Ordered',
    subtitle     : '{{buyer}} ordered {{title}}',
    groupedTitle : 'Bookshop Updates'
  }
  @Common.SemanticObject: 'Books'
  @Common.SemanticObjectAction: 'display'
  event BookOrdered {
    title : String;
    buyer : String;
  }

}
```

至少有一个事件 `@notification` 注释(赤色) `@notification` 旗帜或任何 `@notification.*` 正在取回。 通知类型密钥取自事件名称. 命名空间前缀被剥去, `my.bookshop.BookOrdered` 变成 `BookOrdered`。 。 。 .

> \[!注\] 插件自动注入 a `recipients` 元素在模型装入时间进入每个通知事件;您不需要亲自声明.

> \[重要\] 事件必须包含在服务中,要么直接在服务中定义事件 `service` 或通过使用 `extend service` 编号 : `using` 将它纳入现有的一个.

> \[!注\] 说明也可以使用标准 CDS 放在单独的文件中 `annotate` 指令.

**共同说明:**

```cds
@notification: {
  title        : 'Book {{title}} Ordered',
  publicTitle  : 'Book Ordered',
  subtitle     : '{{buyer}} ordered {{title}}',
  groupedTitle : 'Bookshop Updates', // Group header for multiple notifications
  email: {
    subject: 'Your order: {{title}}',
    html   : './email-template.html' // Path to HTML template or inline HTML
  },
  priority: #HIGH // Priority: LOW, NEUTRAL, MEDIUM, HIGH
}
event BookOrdered { ... }
```

关于支持的说明及其绘图的完整清单,见 [注释](https://npmcn.com/package/%40cap-js/notifications/#readme-annotation-reference)。 。 。 .

#### 交付渠道(仅选择A)

使用 `@notification.channels` 指定通过下列方式发送通知类型的渠道:

```cds
@notification: {
  title   : 'Book Ordered',
  channels: ['email']
}
event BookOrdered { ... }
```

支持的值为: `email` (SAP邮件)和 `workzone` (SAP 建设工作区). 如果没有指定频道,频道默认值为 `cds.env.requires.notifications.channels`,或 `workzone` 如果没有设置.

#### i18n 支持(仅选项A)

这个 `@notification` 注释值支持 `{i18n>key}` 语法. 在启动时, 密钥会自动解决您的项目的 i18n 捆绑 。 在至少一个翻译与默认语言不同的地方,每个语言都会生成模板.

```cds
@notification.title:    '{i18n>BOOK_ORDERED_TITLE}'
@notification.subtitle: '{i18n>BOOK_ORDERED_SUBTITLE}'
event BookOrdered { ... }
```

#### HTML 电子邮件模板( 只有选项 A)

这个 `email.html` 注释接受内含的 HTML 字符串或路径 `.html` 文件相对 `.cds` 来源文件. 文件在启动时被读取,其中的i18n占位符被解决.

```cds
@notification: {
  email: {
    subject: 'Your order: {{title}}',
    html   : './book-ordered-email.html'
  }
}
event BookOrdered { ... }
```

#### 优先权(仅选择A)

通知可分配不同的优先级别: `LOW`, (中文(简体) ), `NEUTRAL` (违约), `MEDIUM`,或 `HIGH`这些优先事项影响在SAP建设区如何显示和排序通知.

优先事项可以静态设定,使用 `#` enum值,或动态使用 [CDS 表达式语言( CXL)](https://cap.cloud.sap/docs/cds/cxl) 在运行时评估条件.

**静态优先 :**

```cds
@notification.priority: #HIGH
event BookOrdered { ... }
```

**动态优先级 :**

优先级可以在运行时从使用根据数据库评估的 CDS 三进制表达式的事件数据中计算:

```cds
@notification.priority: (quantity > 5 ? #HIGH : #LOW)
event BookOrdered {
  quantity : Integer;
  title    : String;
}
```

使用 CDS 函数的复杂表达式也被支持:

```cds
@notification.priority: (days_between(orderDate, deliveryDate) > 7 ? #HIGH : #LOW)
event LateDelivery {
  orderDate    : Date;
  deliveryDate : Date;
}
```

动态优先级需要通过 `this.emit(...)` 因此插件可以截取并评价.

#### 建立一体化

运行 `cds build` 全部进程 `@notification` 附加说明的事件并生成合并 `notification-types.json` 转到构建输出,将CDS注释中的类型与JSON文件中的任何类型合并.

### 备选案文B:JSON文件

另一种办法是静态地在 `srv/notification-types.json` 或自定义路径(参见 [自定义通知类型路径](https://npmcn.com/package/%40cap-js/notifications/#readme-custom-notification-types-path):

```json
[
  {
    "NotificationTypeKey": "BookOrdered",
    "NotificationTypeVersion": "1",
    "Templates": [
      {
        "Language": "en",
        "TemplatePublic": "Book Ordered",
        "TemplateSensitive": "Book '{{title}}' Ordered",
        "TemplateGrouped": "Bookshop Updates",
        "TemplateLanguage": "mustache",
        "Subtitle": "{{buyer}} ordered {{title}}."
      }
    ]
  }
]
```

> \[!注\] i18n 分辨率、 HTML 文件路径和优先级说明(`@notification.priority`),只有在使用CDS说明(备选A)时才可用. JSON文件格式使用预解字符串.

### 电子邮件发送

在这两种方法中,电子邮件发送都可以用于通知类型。 它要求SAP警报通知处与 `business-notifications` 计划和配置 [SMTP 邮件目的地](https://help.sap.com/docs/build-work-zone-standard-edition/sap-build-work-zone-standard-edition/configuring-smtp-mail-destination)。 。 。 .

> \[! 警告\] 这个 `business-notifications` 计划验证 **全部** 您在注册时间的通知类型, 不仅仅是有电子邮件的。 这意味着你的应用程序中的每一个通知类型,即使是纯粹的应用程序,都必须有 `TemplatePublic` (从 `publicTitle`和 `TemplateGrouped` (从 `groupedTitle`)设置,或启动注册会失败.

**Via CDS 说明 :**

```cds
@notification: {
  title        : 'Book {{title}} Ordered',
  publicTitle  : 'Book Ordered',
  subtitle     : '{{buyer}} ordered {{title}}',
  groupedTitle : 'Bookshop Updates',
  email: {
    subject: 'Your order: {{title}}',
    html   : './book-ordered-email.html'
  },
  channels: ['email']
}
event BookOrdered { ... }
```

**维娅·杰森:**

```json
{
  "NotificationTypeKey": "BookOrdered",
  "Templates": [
    {
      "Language": "en",
      "TemplatePublic": "Book Ordered",
      "TemplateSensitive": "Book '{{title}}' Ordered",
      "TemplateGrouped": "Bookshop Updates",
      "TemplateLanguage": "mustache",
      "EmailSubject": "Your order: {{title}}",
      "EmailHtml": "<p>Thanks for ordering <b>{{title}}</b>!</p>"
    }
  ],
  "DeliveryChannels": [{ "Type": "MAIL", "Enabled": true, "DefaultPreference": true, "EditablePreference": true }]
}
```

> **说明:** `Enabled`, (中文(简体) ), `DefaultPreference`,以及 `EditablePreference` 需要ANS字段。 使用上面显示的数值而不更改它们 .

## 发送通知

发送通知有两种模式.

### 图案1:释放CDS事件(建议)

如果您将您的通知类型定义为带有 CDS 事件的 CDS `@notification` 注释,插件自动勾入您的服务。 从你的服务管理者那里释放这个事件.

```js
this.on("submitOrder", async req => {
  const book = await SELECT.one.from("Books").where({ ID: req.data.book })

  await this.emit("BookOrdered", {
    title: book.title,
    buyer: req.user.id,
    recipients: ["reader@bookshop.example"]
  })
})
```

插件注册事件处理器, 将通知转发给 ANS 。 如果您需要自己处理事件, 您仍然可以注册自己的事件处理器 。 插件的处理器和它们一起运行 .

### 图案2:呼叫通知( )

您也可以连接到通知服务并拨打 `notify()` 直接说 这与预先确定的通知类型或不存在.

**简单通知** (不需要预先定义的类型):

```js
const alert = await cds.connect.to("notifications")

await alert.notify({
  recipients: [...readers()],
  priority: "HIGH",
  title: "New book arrived!",
  description: "Book 'Wuthering Heights' has been added to the catalog."
})
```

> \[!注\] 简单的 API 只支持 `recipients`, (中文(简体) ), `priority`, (中文(简体) ), `title`,以及 `description`对于高级属性,使用命名的通知类型或 [低级 API](https://npmcn.com/package/%40cap-js/notifications/#readme-low-level-notifications-api)。 。 。 .

**命名的通知类型 :**

```js
await alert.notify("BookOrdered", {
  recipients: [buyer.id],
  data: {
    title: book.title,
    buyer: buyer.name
  }
})
```

### 批量通知

可以通过数组 `notify()` 在一个呼叫中发出多个通知。 这只触发一个发件箱事件,在通知许多收件人时减少交易次数. 如果有些项目失败,成功的项目仍然交付。 失败者会被记录为警告,只有 **全部** 项目失败.

```js
alert.notify("BookOrdered", [
  { recipients: [buyer1.id], data: { title: book.title, buyer: buyer1.name } },
  { recipients: [buyer2.id], data: { title: book.title, buyer: buyer2.name } }
])
```

> \[! 警告\] 批次发送只能通过 `notify([...])`. CDS事件的排放发送一次呼叫.

或者,可以使用默认的通知模板:

```js
await alert.notify([
  { type: "BookOrdered", recipients: [buyer1.id], data: { title: book1.title, buyer: buyer1.name } },
  { type: "BookOrdered", recipients: [buyer2.id], data: { title: book2.title, buyer: buyer2.name } }
])
```

## 实体通知

当实体数据被读取或更改时,实体通知允许您声明火灾通知,而不写任何处理器代码. 添加一个 `@notifications` 直接给一个CDS实体的注释,数组中的每个条目定义一个通知:

```cds
service CatalogService {
  @notifications: [{
    type      : 'BookOrdered',
    on        : ['READ'],
    recipients: ($self.createdBy),
    where     : ($self.stock < 5),
    priority  : #High
  }]
  entity Books as projection on my.Books;
}
```

### 注释属性

| 财产 | 需求 | 说明 |
| --- | --- | --- |
| `type` | 对 | 此通知类型的名称( 如“ BookOrdered ”) 。 插件自动注册 . |
| `on` | 对 | 需要收听的 CDS 事件列表 : `'READ'`, (中文(简体) ), `'CREATE'`, (中文(简体) ), `'UPDATE'` |
| `recipients` | 对 | 实地参考(例如:. `$self.createdBy`)或字面收件人标识符 |
| `where` | 没有 | 过滤表达式: 只有匹配此条件的实体点出通知 |
| `priority` | 没有 | `#Low`, (中文(简体) ), `#Neutral`, (中文(简体) ), `#Medium`,或 `#High` |
| `parameters` | 没有 | 明确将通知模板占位符映射到实体域 |

### 通知属性

默认情况下,所有实体字段都转到通知模板. 使用 `parameters` 仅映射特定字段:

```cds
@notifications: [{
  type      : 'BookOrdered',
  on        : ['READ'],
  recipients: ($self.createdBy),
  parameters: { bookTitle: $self.title, bookId: $self.ID }
}]
entity Books as projection on my.Books;
```

由此产生一份通知,其中只有 `bookTitle` 财务报告和审定财务报表 `bookId` 属性设置,匹配通知类型模板中的占位符.

## API 参考

### 简单通知

对于 `notify({ recipients, title, ... })`,不需要预先定义的通知类型。 插件使用内置 `Default` 模板.

| 参数 | 需求 | 说明 |
| --- | --- | --- |
| `recipients` | 对 | 接收者标识符组:电子邮件地址或SAP BTP 全球用户ID(UUID) |
| `title` | 对 | 通知标题字符串 |
| `priority` | 没有 | `LOW`, (中文(简体) ), `NEUTRAL` (违约), `MEDIUM`,或 `HIGH` |
| `description` | 没有 | 副标题文本 |

### 命名的通知类型

对于 `notify('TypeKey', payload)` 或者说 `notify({ type: 'TypeKey', ... })`,则使用预定义的通知类型发送通知.

| 参数 | 需求 | 说明 |
| --- | --- | --- |
| `recipients` | 对 | 接收者标识符组:电子邮件地址或SAP BTP 全球用户ID(UUID) |
| `type` | 对 | 通知类型密钥( 如 ). `'BookOrdered'`(中文(简体) ) |
| `data` | 没有 | 用于在类型模板中填充胡子占位符的密钥值配对 |
| `priority` | 没有 | `LOW`, (中文(简体) ), `NEUTRAL` (违约), `MEDIUM`,或 `HIGH` |

> **说明:** 收件人可以是电子邮件地址(例如. `user@example.com`)或SAP BTP Global用户ID(UUID格式,例如. `a1b2c3d4-...`) (中文(简体) ). 单位 `auto` 模式(默认),插件检测每个收件人的格式并自动使用正确的密钥。 见 [认证标识符](https://npmcn.com/package/%40cap-js/notifications/#readme-authentication-identifier) 详细情况.

### 验证

-   **财产价值** 不得超过 **255 个字符**。更长的数值导致通知被拒绝.
-   **目标参数值** 长于 **250个字符** 默然放弃.
-   **事件元素名称** 不得超过 **128个字符**被抓到的侵权行为 `cds build` 时间.

### 注释

对通知字段的 CDS 说明的完整映射 :

| 注释 | ANS 战地 | 说明 |
| --- | --- | --- |
| `@description` | `Description` | 通知类型说明 |
| `@notification.title` | `TemplateSensitive` | 主要通知标题( 支持占位符) |
| `@notification.publicTitle` | `TemplatePublic` | 公共退职头衔 |
| `@notification.subtitle` | `Subtitle` | 副标题文本 |
| `@notification.groupedTitle` | `TemplateGrouped` | 多个通知的组头 |
| `@notification.email.subject` | `EmailSubject` | 电子邮件主题行 |
| `@notification.email.html` | `EmailHtml` | 内嵌 HTML 或路径到 `.html` 文件 |
| `@Common.SemanticObject` | `NavigationTargetObject` | 导航目标对象 |
| `@Common.SemanticObjectAction` | `NavigationTargetAction` | 导航动作 |
| `@notification.priority` | `Priority` | `LOW`, (中文(简体) ), `NEUTRAL`, (中文(简体) ), `MEDIUM`,或 `HIGH` |

## 本地测试驱动

在当地开发期间,通知被嘲笑并被印刷到控制台. 不需要外部服务.

![Notify to console](https://npmcn.com/package/%40cap-js/notifications/_assets/notifyToConsole.png)

## 在生产中运行

### 通知目标

作为先决条件,配置 [目标](https://help.sap.com/docs/build-work-zone-standard-edition/sap-build-work-zone-standard-edition/enabling-notifications-for-custom-apps-on-sap-btp-cloud-foundry#configure-the-destination-to-the-notifications-service) 名称 `SAP_Notifications` 在您的 BTP 子账户中。 该插件默认使用此目的地在混合和生产环境中连接到通知服务.

### 通知类型登记

通知类型在每次申请启动时都会自动注册,并与通知服务同步. 通知类型的任何添加、更改或清除,无论是从CDS说明还是JSON文件中,都应用在下次启动时。 无手册 `cds build` 或内容部署步骤.

### 与SAP建设区一体化

一旦应用程序被部署并融入SAP建设工作区,通知就会出现在Fiori通知图标下.

![Sample Application Demo](https://npmcn.com/package/%40cap-js/notifications/_assets/incidentsNotificationDemo.gif)

## 高级使用

### 自定义通知类型路径

插件读取 `srv/notification-types.json` 作为默认 JSON 类型文件。 要使用不同的路径 :

```json
"cds": {
  "requires": {
    "notifications": {
      "types": "srv/my-notification-types.json"
    }
  }
}
```

### 自定义通知类型前缀

要让每个应用程序都独有通知类型密钥,插件会用应用程序名前缀它们 `package.json` 默认。 要使用自定义前缀 :

```json
"cds": {
  "requires": {
    "notifications": {
      "prefix": "my-custom-prefix"
    }
  }
}
```

### 自定义目标名称

覆盖默认值 `SAP_Notifications` 目标名称 :

```json
"cds": {
  "requires": {
    "notifications": {
      "destination": "MY_CUSTOM_DESTINATION"
    }
  }
}
```

### 认证标识符

`cds.env.requires.notifications.authenticationIdentifier` 控制在发布通知时使用的收件人密钥.

-   `auto` (默认):每个收件人选择收件人的密钥. UUID格式的值作为SAP BTP Global User ID处理并发布 `GlobalUserId`; 其它所有内容都与 `RecipientId`。如果一个值既不是UUID,也不是电子邮件地址,则会登录警告。 这样可以将UUID和电子邮件地址混合在同一处 `recipients` 没有配置的阵列.
-   `UserUUID`: 总是使用 `GlobalUserId`。当工作区认证标识符设定为 `User ID`。 。 。 .
-   `RecipientId`: 总是使用 `RecipientId`。当收件人通过电子邮件或登录名称识别时使用此选项.

> \[注\] 对于使用用户ID发送的电子邮件通知,必须配置身份目录服务(IDS)的目的地,用于电子邮件地址查询.

关于工作区认证标识符配置,见 [工作区子账户设置](https://help.sap.com/docs/build-work-zone-standard-edition/sap-build-work-zone-standard-edition/subaccount-settings)。 。 。 .

### 默认通道

默认情况下,所有通知类型都使用工作区通道. 更改所有类型的默认值 `channels` 注释, 设定 `channels` 在配置中:

```json
"cds": {
  "requires": {
    "notifications": {
      "channels": ["email"]
    }
  }
}
```

还支持多个频道:

```json
"notifications": {
  "channels": ["email", "workzone"]
}
```

每起事件 `channels` 说明总是优先于这一全球缺省.

### 发件箱行为

默认情况下,通知服务使用发件箱(`outbox: true`: `notify()` 将信件排入队列后立即解析,而不是发送到 ANS 时。 这意味着ANS的HTTP响应没有被返回. 要同步发送并接收 HTTP 响应 :

```json
"cds": {
  "requires": {
    "notifications": {
      "outbox": false
    }
  }
}
```

### 关闭插件

要禁用插件而不移除, 设置 `enabled: false`数字 :

```json
"cds": {
  "requires": {
    "notifications": {
      "enabled": false
    }
  }
}
```

这阻止了插件注册其不会自动生成的钩子 `this.emit()` 拦截,没有通知类型的注册,也没有建造任务. 直接电话: `cds.connect.to('notifications').notify()` 不受此旗帜的影响.

### 低级通知 API

为全面控制起见,可直接通过该附件所述的完整通知对象 [ANS API 文档](https://help.sap.com/docs/build-work-zone-standard-edition/sap-build-work-zone-standard-edition/developing-cloud-foundry-applications-with-notifications)。 。 。 .

#### 有个别参数

```js
alert.notify({
  recipients: [...readers()],
  type: "BookOrdered",
  priority: "NEUTRAL",
  data: {
    title: book.title,
    buyer: buyer.name
  },
  OriginId: "Example Origin Id",
  NotificationTypeVersion: "1",
  ProviderId: "/SAMPLEPROVIDER",
  ActorId: "BACKENDACTORID",
  ActorDisplayText: "ActorName",
  ActorImageURL: "https://some-url",
  NotificationTypeTimestamp: "2022-03-15T09:58:42.807Z",
  TargetParameters: [{ Key: "string", Value: "string" }] //tell Work Zone which record to open when the user clicks on the notification
})
```

#### 传递全部通知对象

```js
alert.notify({
  NotificationTypeKey: "BookOrdered",
  NotificationTypeVersion: "1",
  Priority: "NEUTRAL",
  Properties: [
    { Key: "title", IsSensitive: false, Language: "en", Value: "Wuthering Heights", Type: "String" },
    { Key: "buyer", IsSensitive: false, Language: "en", Value: "reader@bookshop.com", Type: "String" }
  ],
  Recipients: [{ RecipientId: "reader1@bookshop.com" }, { RecipientId: "reader2@bookshop.com" }]
})
```

## 捐款

此项目可通过下列方式对特性请求/建议、错误报告等开放: [GitHub 问题](https://github.com/cap-js/notifications/issues)鼓励并始终欢迎各方作出贡献和反馈。 关于如何作出贡献的更多信息,项目结构以及额外贡献信息见我们 [贡献准则](https://npmcn.com/package/%40cap-js/notifications/CONTRIBUTING.md)。 。 。 .

## 行为守则

作为成员、贡献者和领导人,我们保证使参加我们的社区成为每个人不受骚扰的经历。 通过参与这个项目,你同意遵守 [行为守则](https://npmcn.com/package/%40cap-js/notifications/CODE_OF_CONDUCT.md) 在任何时间.

## 许可证发放

版权2026 SAP SE或SAP下属公司和贡献者. 请看我们的 [自由主义](https://npmcn.com/package/%40cap-js/notifications/LICENSE) 版权和许可证信息。 详细信息,包括第三方组成部分及其许可证/版权信息 [通过REUSE工具](https://api.reuse.software/info/github.com/cap-js/notifications)。 。 。 .

## 常见问题

### @cap-js/notifications 是什么？

CDS插件在SAP Build WorkZone中为业务通知提供支持\.

### 如何安装 @cap-js/notifications？

在项目目录运行 npm install @cap-js/notifications，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@sap/cds（\>=8\.0）、@sap/cds-dk（\>=8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cap-js/notifications 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cap-js\_\_notifications 是否存在。

### @cap-js/notifications 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @cap-js/notifications 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cap-js/notifications 可以商用吗？

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

### @cap-js/notifications 的下载量有多少？

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

### @cap-js/notifications 还在维护吗？

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