# @deltachat/dbus-next 中文文档

规范地址：https://npmcn.com/package/%40deltachat/dbus-next/

版本：1\.0\.1
npm 元数据更新时间：2025-10-13T15:24:20.527Z
中文译文更新时间：2026-11-11T21:53:08.793Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40deltachat/dbus-next
原文对照：https://npmcn.com/package/%40deltachat/dbus-next/?lang=original
项目主页：https://github.com/deltachat/node-dbus-next#readme
源码仓库：https://github.com/deltachat/node-dbus-next

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

- 包体积（解压后）：149 kB，29 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2024-03-01T17:10:20.862Z
- 最新版本发布：2024-03-01T18:00:26.579Z
- 近 30 天下载量：12758（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 0 个）

## 中文简介

dbus- next 不依赖本地用户

## 安装

```sh
npm install @deltachat/dbus-next
```

也可以使用：`pnpm add @deltachat/dbus-next`、`yarn add @deltachat/dbus-next`、`bun add @deltachat/dbus-next`

## README

# dbus 下一个

诺德JS的下一个伟大的 DBus 库.

[文档](https://acrisci.github.io/doc/node-dbus-next/)

[聊天](https://discord.gg/UdbXHVX)

## 关于

dbus-next是DBus的全功能高水平库,主要用于将应用程序整合到Linux桌面和移动环境中.

桌面应用程序开发人员可以通过实施通用的DBus标准接口或创建自定义插件接口,使用这个库将其应用程序集成到桌面环境中.

桌面用户可以利用这个库来创建自己的脚本和公用设备来与这些界面互动,以定制他们的桌面环境.

## 节点相容性

目前,dbus-next针对JavaScript的最新特性. 支持的最早版本是 `6.3.0`然而,图书馆使用 `BigInt` 默认的长整数类型 `10.8.0`。如果需要提前支持版本,请设置 BigInt 兼容模式。 这将配置要使用的库 [JSBI (联合履行机构)](https://github.com/GoogleChromeLabs/jsbi) 作为长类型的多填充.

```javascript
const dbus = require('dbus-next');
dbus.setBigIntCompat(true);
```

## 客户界面

您可以在总线上获得一个名称的代理对象 `bus.getProxyObject()` 函数,传递名称和路径。 代理对象包含关于对象的内向数据,包括节点和接口列表. 您可以与 `object.getInterface()` 函数传递接口的名称.

界面对象有您可以调用的方法与内向数据中的方法相对应. 将正常的JavaScript对象传递到函数的参数上,它们会被自动转换为被公示的 DBus 类型. 不过,你必须使用 `Variant` 类代表 DBus 变体.

方法同样会返回 JavaScript 从已公布的 DBus 类型转换出来的对象, 并带有 `Variant` 类用于表示返回的变体。 如果方法返回多个值,它们将在数组内返回.

界面对象是一个事件发报器,当信号在总线上被放出时会发出信号的名称. 对回调的参数应当与信号的参数对应.

这是使用代理对象与该代理对象的简单实例 [MPRIS (MPRIS) 维基百科中的相关条目](https://specifications.freedesktop.org/mpris-spec/latest/Player_Interface.html) 媒体播放器界面.

```js
let dbus = require('dbus-next');
let bus = dbus.sessionBus();
let Variant = dbus.Variant;

// getting an object introspects it on the bus and creates the interfaces
let obj = await bus.getProxyObject('org.mpris.MediaPlayer2.vlc', '/org/mpris/MediaPlayer2');

// the interfaces are the primary way of interacting with objects on the bus
let player = obj.getInterface('org.mpris.MediaPlayer2.Player');
let properties = obj.getInterface('org.freedesktop.DBus.Properties');

// call methods on the interface
await player.Play()

// get properties with the properties interface (this returns a variant)
let volumeVariant = await properties.Get('org.mpris.MediaPlayer2.Player', 'Volume');
console.log('current volume: ' + volumeVariant.value);

// set properties with the properties interface using a variant
await properties.Set('org.mpris.MediaPlayer2.Player', 'Volume', new Variant('d', volumeVariant.value + 0.05));

// listen to signals
properties.on('PropertiesChanged', (iface, changed, invalidated) => {
  for (let prop of Object.keys(changed)) {
    console.log(`property changed: ${prop}`);
  }
});
```

完整的例子见 [MPRIS 客户端](https://github.com/dbusjs/node-dbus-next/blob/master/examples/mpris.js) 实例,可用于控制命令行上的媒体播放器.

## 服务接口

你可以用这个 `Interface` 类以定义界面。 此接口使用拟议 [装饰语法](https://github.com/tc39/proposal-decorators) 尚未纳入ECMAScript标准,但应当包括一天。 不幸的是,你需要一个 [Babel 插件](https://www.npmjs.com/package/@babel/plugin-proposal-decorators) 使这个代码暂时有效.

```js
let dbus = require('dbus-next');
let Variant = dbus.Variant;

let {
  Interface, property, method, signal, DBusError,
  ACCESS_READ, ACCESS_WRITE, ACCESS_READWRITE
} = dbus.interface;

let bus = dbus.sessionBus();

class ExampleInterface extends Interface {
  @property({signature: 's', access: ACCESS_READWRITE})
  SimpleProperty = 'foo';

  _MapProperty = {
    'foo': new Variant('s', 'bar'),
    'bat': new Variant('i', 53)
  };

  @property({signature: 'a{sv}'})
  get MapProperty() {
    return this._MapProperty;
  }

  set MapProperty(value) {
    this._MapProperty = value;

    Interface.emitPropertiesChanged(this, {
      MapProperty: value
    });
  }

  @method({inSignature: 's', outSignature: 's'})
  Echo(what) {
    return what;
  }

  @method({inSignature: 'ss', outSignature: 'vv'})
  ReturnsMultiple(what, what2) {
    return [
      new Variant('s', what),
      new Variant('s', what2)
    ];
  }

  @method({inSignature: '', outSignature: ''})
  ThrowsError() {
    // the error is returned to the client
    throw new DBusError('org.test.iface.Error', 'something went wrong');
  }

  @method({inSignature: '', outSignature: '', noReply: true})
  NoReply() {
    // by setting noReply to true, dbus-next will NOT send a return reply through dbus 
    // after the method is called.
  }

  @signal({signature: 's'})
  HelloWorld(value) {
    return value;
  }

  @signal({signature: 'ss'})
  SignalMultiple(x) {
    return [
      'hello',
      'world'
    ];
  }
}

let example = new ExampleInterface('org.test.iface');

setTimeout(() => {
  // emit the HelloWorld signal by calling the method with the parameters to
  // send to the listeners
  example.HelloWorld('hello');
}, 500);

async function main() {
  // make a request for the name on the bus
  await bus.requestName('org.test.name');
  // export the interface on the path
  bus.export('/org/test/path', example);
}

main().catch((err) => {
  console.log('Error: ' + err);
});
```

接口扩展 `Interface` 课。 声明服务方法、属性和信号,由图书馆提供装饰。 您可以选择在总线上请求名称 `bus.requestName()` 所以客户有 众所周知的名称可以连接。 那就打电话 `bus.export()` 与路径和界面一起在总线上曝光此界面.

当一个 DBus 客户端在服务器上调用该方法时,方法被称为方法. 属性可以与 `org.freedesktop.DBus.Properties` 界面,并包含在后演化 xml 中.

要发出信号,请拨打标记为 `signal` 装饰器和信号会随返回值而出出.

如果您有 xml 接口描述, 可以从 `org.freedesktop.DBus.Introspect` 在导出接口上,您可以从 xml 文件生成 dbus- next JavaScript 类 `bin/generate-interfaces.js` 函数.

## 低级界面

低等界面可用于直接与消息交互. 创建新信件 `Message` 分类作为方法调用、信号、方法返回或出错发送到总线上。 方法调用与 `call()` 方法 `MessageBus` 等待回复 `send()` 可用于不需要回复的信息.

```js
let dbus = require('dbus-next');
let Message = dbus.Message;

let bus = dbus.sessionBus();

// send a method call to list the names on the bus
let methodCall = new Message({
  destination: 'org.freedesktop.DBus',
  path: '/org/freedesktop/DBus',
  interface: 'org.freedesktop.DBus',
  member: 'ListNames'
});

let reply = await bus.call(methodCall);
console.log('names on the bus: ', reply.body[0]);

// add a custom handler for a particular method
bus.addMethodHandler((msg) => {
  if (msg.path === '/org/test/path' &&
      msg.interface === 'org.test.interface'
      && msg.member === 'SomeMethod') {
    // handle the method by sending a reply
    let someMethodReply = Message.newMethodReturn(msg, 's', ['hello']);
    bus.send(someMethodReply);
    return true;
  }
});

// listen to any messages that are sent to the bus
bus.on('message', (msg) => {
  console.log('got a message: ', msg);
});
```

关于如何使用低等界面发送信件的完整实例,请参见 `dbus-next-send.js` 脚本在 `bin` 目录.

## 类型系统

通过消息总线发送或接收的值总是有一个相关的签名,指定了这些值的类型. 对于高级客户端和服务,这些签名在XML数据中加以具体说明,在XML数据中公布 [标准 DBus 接口](https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format). 高端客户端动态创建基于该内测数据的类,其方法和信号基于类型签名. 高端服务通过对班级进行回顾来进行反向,以创建在巴士上为客户公示的反向XML数据.

签名中的每个代码被映射为JavaScript类型,如下表所示.

| 名称 | 代码 | 联合来文类型 | 页:1 |
| --- | --- | --- | --- |
| 字节 | 尔 | 编号 |  |
| 玻利维亚 | 页:1 | 布尔 |  |
| INT16号卫星 | 无 | 编号 |  |
| UINT16 请检查URL=值 (帮助) | 页:1 | 编号 |  |
| INT32号 | (单位:千美元) | 编号 |  |
| UINT32 请检查URL=值 (帮助) | 欧 | 编号 |  |
| INT64 (英语) | 页:1 | 大点 | 使用 `dbus.setBigIntCompat(true)` 用于 `JSBI` |
| 联合INT64 | 页:1 | 大点 | 使用 `dbus.setBigIntCompat(true)` 用于 `JSBI` |
| 丢弃 | d. 国家 | 编号 |  |
| 绳子 | 编号 | 字符串 |  |
| 目标( P) | 欧 | 字符串 | 必须是有效的对象路径 |
| 签字 | 页:1 | 字符串 | 必须是有效的签名 |
| UNI( UNI)- FD | 页:1 | 编号 | 必须是有效的 unix 文件描述符 。 例如来自 `fs.open()` |
| 阿雷亚 | (单位:千美元) | 阵列 | 后面必须有一个指定儿童类型的完整类型 |
| 结 论 | (单位:千美元) | 阵列 | JS 阵列中的类型必须匹配 parens 之间的类型 |
| 候选人 | 页:1 | 备选案文 | 此课由图书馆提供. |
| 争端 | { | 对象 | 必须包含在数组类型中才能成为对象. |

Unix 文件描述符只在抽象或域(path)套接字上支持. 这是系统和会话总线的默认值 . 当发送文件描述符时,它必须一直打开直到消息被发送. 当收到文件描述器时,应用程序负责关闭.

类型 `a`, (中文(简体) ), `(`, (中文(简体) ), `v`,以及 `{` 是具有其他值的容器类型。 容器类型和JavaScript实例见下表.

| 签署 | 示例 | 页:1 |
| --- | --- | --- |
| `(su)` | `[ 'foo', 5 ]` | 阵列中的每个元素必须匹配结构成员的相应类型. |
| `as` | `[ 'foo', 'bar' ]` | 孩子的型号 紧接着 `a`。数组可以有任意数量的元素,但它们都必须与子类型相匹配. |
| `a{su}` | `{ 'foo': 5 }` | 以"对象"为代表的"dict项". 后面的类型 `{` 键类型和键类型 `}` 是数值类型. |
| `ay` | `Buffer.from([0x62, 0x75, 0x66])` | 特例: 由节点代表的字节数组 `Buffer`。 。 。 . |
| `v` | `new Variant('s', 'hello')` | 签名必须是单一类型。 值可能是一种容器类型. |
| `(asv)` | `[ ['foo'], new Variant('s', 'bar') ]` | 集装箱可能会被窝住. |

关于DBus 类型系统的更多信息,请参见 [规格](https://dbus.freedesktop.org/doc/dbus-specification.html#type-system)。 。 。 .

### 谈判 Unix 文件描述符

支持谈判 Unix 文件描述符( DBus 类型) `h`),设置 `negotiateUnixFd` 改为 `true` 在消息总线构建器选项中。 任意类型的值 `h` 在发送或接收的信件中,文件本身应当是描述符。 您负责关闭公共汽车发送或接收的文件描述符 .

## 捐款

欢迎捐款。 发展发生在 [吉图布](https://github.com/dbusjs/node-dbus-next)。 。 。 .

## 类似项目

dbus- next 是一个叉 [dbus- 内在](https://github.com/sidorares/dbus-native) 图书馆。 虽然这个库很棒,但它有许多错误,我认为如果不彻底重新设计用户API,它就无法被修复. 另一个库存在 [节点-dbus](https://github.com/Shouqun/node-dbus) 类似,但也不足以创建全功能的 DBus 服务.

## 版权

您可以在麻省理工学院许可下使用此代码(参见LICENSE).

2012年,安德烈·西多罗夫

2018年,东尼·克瑞西

## 常见问题

### @deltachat/dbus-next 是什么？

dbus- next 不依赖本地用户

### 如何安装 @deltachat/dbus-next？

在项目目录运行 npm install @deltachat/dbus-next，或使用 pnpm add / yarn add / bun add。

### @deltachat/dbus-next 支持 TypeScript 吗？

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

### @deltachat/dbus-next 支持 ESM 还是 CommonJS？

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

### @deltachat/dbus-next 可以商用吗？

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

### @deltachat/dbus-next 的下载量有多少？

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

### @deltachat/dbus-next 还在维护吗？

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