# @audc/botframework-directlinejs 中文文档

规范地址：https://npmcn.com/package/%40audc/botframework-directlinejs/

版本：0\.16\.0
npm 元数据更新时间：2026-06-21T11:09:33.652Z
中文译文更新时间：2026-11-09T20:39:43.305Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40audc/botframework-directlinejs
原文对照：https://npmcn.com/package/%40audc/botframework-directlinejs/?lang=original
项目主页：https://github.com/audiocodes/BotFramework-DirectLineJS#readme
源码仓库：https://github.com/audiocodes/BotFramework-DirectLineJS

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

- 包体积（解压后）：503 kB，19 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：6 个
- 首次发布：2026-02-15T08:12:15.581Z
- 最新版本发布：2026-06-21T11:09:33.410Z
- 近 30 天下载量：1740（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

Microsoft Bot框架直线3.0协议客户端库

## 安装

```sh
npm install @audc/botframework-directlinejs
```

也可以使用：`pnpm add @audc/botframework-directlinejs`、`yarn add @audc/botframework-directlinejs`、`bun add @audc/botframework-directlinejs`

## README

![Bot Framework DirectLineJS](https://npmcn.com/package/%40audc/botframework-directlinejs/docs/media/FrameWorkDirectLineJS@1x.png)

# 微软Bot框架直线JS客户端

[![Build Status](https://travis-ci.org/Microsoft/BotFramework-DirectLineJS.svg?branch=master)](https://travis-ci.org/Microsoft/BotFramework-DirectLineJS)

客户端库 [微软瓶子框架](http://www.botframework.com/) _[直线](https://docs.botframework.com/en-us/restapi/directline3/)_ 协议.

用于 [网络聊天](https://github.com/Microsoft/BotFramework-WebChat) 因此(延长) [模拟器](https://github.com/Microsoft/BotFramework-Emulator),网络聊天频道,以及 [Azure 瓶装服务](https://azure.microsoft.com/en-us/services/bot-service/)。 。 。 .

## 财务问题

### _这是谁的?_

正在构建 Bot Framework JavaScript 客户端但不想使用的人 [网络聊天](https://github.com/Microsoft/BotFramework-WebChat)。 。 。 .

如果您目前使用WebChat,您不需要做任何修改,因为它包含了这个软件包.

### _这有什么好笑的 `subscribe()` 下面的样本中的方法?_

这个库不使用回调或承诺,而是使用可观察操作处理合成操作. 试试看,你会喜欢的! 详细情况请查看 [RxJS 软件](https://github.com/reactivex/rxjs/)。 。 。 .

### _我可以用吗 [类型脚本](http://www.typescriptlang.com/)? 吗?_

当然.

### 这个图书馆准备多少?

这是一个由微软官方支持的库,被认为基本完成. 未来的变化(除了支持未来更新直接行协议外)可能仅限于错误修正,性能改进,教程,和样本. 这里丢失的大块 是单位测试.

虽然如此,公共API仍然有变化.

### 为什么文库没有检测出Web Socket断开?

在iOS/iPadOS上,当网络从Wi-Fi变为蜂窝时 `WebSocket` 对象将被停止而不发生任何错误。 如果没有任何额外的援助,这一点是无法察觉的,也是行不通的。 这个问题与一个名为"NSURL Session WebSocket"的实验性专题有关. 该功能默认启用于iOS/iPadOS 15并上.

命名选项 `networkInformation` 可用于帮助库发现任何连接问题。 该选项基于 [W3C 网络信息 API](https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API) 它应至少执行两个成员:

-   [A 类 `type` 属性](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/type) 以显示当前网络类型
    -   当 `type` 实值 `"offline"`,网络不可用,也不会连接
-   [A 类 `change` 事件](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/change_event) 应在 `type` 财产变更

然而,iOS/iPadOS上的Safari [不支持 W3C 网络信息 API](https://bugs.webkit.org/show_bug.cgi?id=185697)。由网络开发者实施 `NetworkInformation` 混合填充剂.

检测网络类型变化的一个有效方法是订阅 [服务器事件](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) 来源. 服务将每30秒发送一次信息。 如果网络类型被改变, 且当前网络类型已无法使用, 连接将提前关闭 `error` 活动将发送至 [`EventSource`](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) 举个例子 一经收到 `error` 活动 `NetworkInformation.type` 改为 `"offline"`。浏览器将自动重试 Server- Sent Events 连接。 一经收到 `open` 组合填充应更改 `type` 返回到 `"unknown"`。 。 。 .

如果图书馆被使用在一个本地的iOS/iPadOS应用程序中,资源密集程度较低的解决方案将部分实施 [网络信息 API](https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API) 使用 [`NWPathMonitor`](https://developer.apple.com/documentation/network/nwpathmonitor)当网络发生变化时 `NetworkInformation` 实例应更新 [`type` 属性](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/type) 根据网络类型和发送a [`change` 事件](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/change_event)。 。 。 .

## 如何从源头构建

0.  克隆这个还原
1.  `npm install`
2.  `npm run build` (或 `npm run watch` 以每次变化重建,或 `npm run prepublishOnly` 生产)

## 如何在应用程序中包含

有几种方式:

1.  从零开始构建并包含其中之一 `/directLine.js` (用rxjs包装)或 `lib/directline.js` 在您的应用程序中
2.  `npm install botframework-directlinejs`

## 从节点环境中使用

这个库使用RxJs/Ajax可观察器,用于DOM环境. 这并不意味着你不能同时使用它 从节点,你只需要做一些额外的事情:

1.  `npm install --save ws xhr2`
2.  在您主应用程序文件上方添加以下内容 :

```typescript
global.XMLHttpRequest = require('xhr2');
global.WebSocket = require('ws');
```

## 如何创建和使用直线对象

### 获取您的机器人安全证书 :

1.  如果你还没有, [注册您的机器人](https://azure.microsoft.com/en-us/services/bot-service/)。 。 。 .
2.  添加直线线( N)**不在网络聊天**(d) 频道,并生成直线密钥。 确保直接行3.0启用.
3.  对于测试,您可以使用您的直线密钥作为安全标志, 但是对于生产, 您可能想要将该密钥交换为直线所详述的托肯 [文档](https://docs.microsoft.com/en-us/azure/bot-service/bot-service-channel-directline?view=azure-bot-service-4.0)。 。 。 .

### 创建直线对象 :

```typescript
import { DirectLine } from 'botframework-directlinejs';
// For Node.js:
// const { DirectLine } = require('botframework-directlinejs');

var directLine = new DirectLine({
    secret: /* put your Direct Line secret here */,
    token: /* or put your Direct Line token here (supply secret OR token, not both) */,
    domain: /* optional: if you are not using the default Direct Line endpoint, e.g. if you are using a region-specific endpoint, put its full URL here */
    webSocket: /* optional: false if you want to use polling GET to receive messages. Defaults to true (use WebSocket). */,
    pollingInterval: /* optional: set polling interval in milliseconds. Defaults to 1000 */,
    timeout: /* optional: a timeout in milliseconds for requests to the bot. Defaults to 20000 */,
    conversationStartProperties: { /* optional: properties to send to the bot on conversation start */
        locale: 'en-US'
    }
});
```

### 机器人的邮政活动:

```typescript
directLine
  .postActivity({
    from: { id: 'myUserId', name: 'myUserName' }, // required (from.name is optional)
    type: 'message',
    text: 'a message for you, Rudy'
  })
  .subscribe(
    id => console.log('Posted activity, assigned ID ', id),
    error => console.log('Error posting activity', error)
  );
```

您也可以通过提供活动中合适的字段来发布信息,并发布附件,以及事件等非信息活动.

### 听从机器人发送的活动:

```typescript
directLine.activity$.subscribe(activity => console.log('received activity ', activity));
```

您可以在即将到来的活动中使用 RxJS 运算符 。 只查看信件活动 :

```typescript
directLine.activity$
  .filter(activity => activity.type === 'message')
  .subscribe(message => console.log('received message ', message));
```

直接行将帮助客户端发送每一次发送活动的复制件,所以一个常见的规律是过滤在 `from`数字 :

```typescript
directLine.activity$
  .filter(activity => activity.type === 'message' && activity.from.id === 'yourBotHandle')
  .subscribe(message => console.log('received message ', message));
```

### 监视连接状态

订阅其中之一 `postActivity` 或者说 `activity$` 将启动连接机器人的进程。 您的应用程序可以监听连接状态并作出适当的反应 :

```typescript
import { ConnectionStatus } from 'botframework-directlinejs';

directLine.connectionStatus$.subscribe(connectionStatus => {
  switch (connectionStatus) {
    case ConnectionStatus.Uninitialized: // the status when the DirectLine object is first created/constructed
    case ConnectionStatus.Connecting: // currently trying to connect to the conversation
    case ConnectionStatus.Online: // successfully connected to the converstaion. Connection is healthy so far as we know.
    case ConnectionStatus.ExpiredToken: // last operation errored out with an expired token. Your app should supply a new one.
    case ConnectionStatus.FailedToConnect: // the initial attempt to connect to the conversation failed. No recovery possible.
    case ConnectionStatus.Ended: // the bot ended the conversation
  }
});
```

### 重新连接到对话

如果你的应用程序通过传递一个符号创建了直线对象,直线将每15分钟刷新一个符号. 如果客户失去连通性(例如关闭膝上型计算机,不支付互联网接入费,进入隧道), `connectionStatus$` 将更改为 `ConnectionStatus.ExpiredToken`。您的应用程序可以从它的服务器上请求一个新的代号,它应该呼叫 页:1 [重新连接](https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-reconnect-to-conversation?view=azure-bot-service-4.0) API (英语). 由此而来的对话对象可以被app传递到DirectLine.

```typescript
var conversation = /* a Conversation object obtained from your app's server */;
directLine.reconnect(conversation);
```

### 恢复已有的对话

当使用有 WebChat 的 DirectLine 时,关闭当前标签或刷新页面在多数情况下会创建一个新的对话. 您可以恢复已有的对话, 以使用户保持相同的上下文 .

**当使用秘密时** 您可以通过下列方式恢复对话:

-   将对话符(在 _常设_ 地点,如本地存储)
-   在创建 DirectLine 对象和密件的同时将此值还原

```typescript
import { DirectLine } from 'botframework-directlinejs';

const dl = new DirectLine({
    secret: /* SECRET */,
    conversationId: /* the conversationid you stored from previous conversation */
});
```

**使用符号时** 您可以通过下列方式恢复对话:

-   将对话符和你的纪念物 _常设_ 地点,如本地存储)
-   给DirectLine重新连接API自己打电话,以获得更新的代号和一个流线器
-   使用 ConversationId、 Token 和 StreamUr 创建直线对象

```typescript
import { DirectLine } from 'botframework-directlinejs';

const dl = new DirectLine({
    token: /* the token you retrieved while reconnecting */,
    streamUrl: /* the streamUrl you retrieved while reconnecting */,
    conversationId: /* the conversationid you stored from previous conversation */
});
```

**获取直接行缓存的任何历史** : 您可以使用水印获取历史 : 你可以看到水印是一个 _活动“ 书签”_。恢复方案将重放您指定的水印中的所有对话活动.

```typescript
import { DirectLine } from 'botframework-directlinejs';

const dl = new DirectLine({
    token: /* the token you retrieved while reconnecting */,
    streamUrl: /* the streamUrl you retrieved while reconnecting */,
    conversationId: /* the conversationid you stored from previous conversation */,
    watermark: /* a watermark you saved from a previous conversation */,
    webSocket: false
});
```

## 捐款

该项目欢迎各方的贡献和建议。 大多数捐款要求您同意 撰稿人许可协议(CLA)宣布,你有权并且实际上确实给了我们 有权使用您的贡献。 详情请访问 [https://cla.microsoft.com (中文(简体) )](https://cla.microsoft.com/)。 。 。 .

当您提交拉动请求时, CLA 机器人会自动确定您是否需要提供 a CLA并适当装饰公关(例如标签、评论)。 只要听从指示 由机器人提供。 你只需要用我们的CLA 一次就能完成.

当您提交拉动请求时, CLA 机器人会自动确定您是否需要提供 a CLA并适当装饰公关(例如标签、评论)。 只要听从指示 由机器人提供。 你只需要用我们的CLA 一次就能完成. 该项目通过了 [Microsoft 开源行为守则](https://opensource.microsoft.com/codeofconduct/)。 。 。 . 更多信息见 [《行为守则》](https://opensource.microsoft.com/codeofconduct/faq/) 或者说 联系人 [打开码@ microsoft.com](mailto:opencode@microsoft.com) 并附上任何其他问题或评论.

## 报告安全问题

安全问题和错误应通过电子邮件私下向微软安全反应中心报告 [安全性@ microsoft.com](mailto:secure@microsoft.com)您应在24小时内收到回复。 如果你出于某种原因没有,请通过电子邮件跟进,以确保我们收到你的原始信息。 进一步信息,包括 [MSRC PGP 软件](https://technet.microsoft.com/en-us/security/dn606155) 键,可在 [安全技术中心](https://technet.microsoft.com/en-us/security/default)。 。 。 .

版权 (c) 微软公司。 版权所有.

## 常见问题

### @audc/botframework-directlinejs 是什么？

Microsoft Bot框架直线3\.0协议客户端库

### 如何安装 @audc/botframework-directlinejs？

在项目目录运行 npm install @audc/botframework-directlinejs，或使用 pnpm add / yarn add / bun add。

### @audc/botframework-directlinejs 支持 TypeScript 吗？

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

### @audc/botframework-directlinejs 支持 ESM 还是 CommonJS？

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

### @audc/botframework-directlinejs 需要什么版本的 Node\.js？

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

### @audc/botframework-directlinejs 可以商用吗？

@audc/botframework-directlinejs 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @audc/botframework-directlinejs 的下载量有多少？

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

### @audc/botframework-directlinejs 还在维护吗？

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