# @devioarts/capacitor-tcpclient 中文文档

规范地址：https://npmcn.com/package/%40devioarts/capacitor-tcpclient/

版本：0\.2\.1
npm 元数据更新时间：2026-07-07T19:06:14.227Z
中文译文更新时间：2026-11-14T13:46:45.672Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：393 kB，43 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core \>=8\.0\.0
- 首次发布：2025-08-30T21:43:25.314Z
- 最新版本发布：2026-07-07T19:06:14.127Z
- 近 30 天下载量：2021（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 4 个）

## 中文简介

在Android、iOS和Electron上工作的Capacitor的 TCP客户端

## 安装

```sh
npm install @devioarts/capacitor-tcpclient
```

也可以使用：`pnpm add @devioarts/capacitor-tcpclient`、`yarn add @devioarts/capacitor-tcpclient`、`bun add @devioarts/capacitor-tcpclient`

## README

# @deviots/ 电容- tcp客户端

拥有本土Android,iOS和Electron支持的Capacitorapp的TCP客户端插件.

当您的应用程序需要直接与 TCP 设备或服务交谈时使用它, 例如 打印机,扫描仪,控制器,网关或本地网络硬件.

## 特征

-   Android、iOS和Electron上的原生TCP套接字
-   多连接 API 与每个连接的孤立听众
-   原始写作、连续流读取和请求/答复读取
-   字节有效载荷为 `number[]` 或者说 `Uint8Array`
-   可选 `expect` 协议回复的匹配模式
-   用于浏览器开发的 Web stub 构建

## 安装

```bash
npm install @devioarts/capacitor-tcpclient
npx cap sync
```

Android网络权限从插件列表中自动合并. 见 [开始](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/docs/getting-started.md) 手动Android回落笔记 和所需的iOS设置.

## 快速启动

```ts
import { TCPClient } from '@devioarts/capacitor-tcpclient';

const conn = TCPClient.createConnection({
  host: '192.168.1.100',
  port: 9100,
  timeout: 3000,
});

await conn.connect();

const reply = await conn.writeAndRead({
  data: [0x1b, 0x40],
  timeout: 1000,
  maxBytes: 4096,
});

if (reply.error) {
  console.error(reply.errorMessage);
} else {
  console.log('Received bytes:', reply.data);
}

await conn.destroy();
```

## 控制器 App 示例

```ts
import { TCPClient, type TCPConnection } from '@devioarts/capacitor-tcpclient';

let connection: TCPConnection | undefined;

export async function connectToDevice(host: string) {
  connection = TCPClient.createConnection({ connectionId: 'main-device', host, port: 9100 });

  await connection.addListener('tcpDisconnect', ({ reason, error }) => {
    console.log('TCP disconnected:', reason, error ?? '');
  });

  return connection.connect();
}

export async function sendCommand(command: Uint8Array) {
  if (!connection) throw new Error('TCP connection is not ready');

  return connection.writeAndRead({
    data: command,
    expect: '0d0a',
    timeout: 1500,
    maxBytes: 8192,
  });
}

export async function disconnectFromDevice() {
  await connection?.destroy();
  connection = undefined;
}
```

## 文档

-   [开始](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/docs/getting-started.md):安装、Android/iOS设置和操场笔记
-   [使用指南](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/docs/usage.md):电容实例、流出、请求/响应和生命周期模式
-   [电能融合](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/docs/electron.md):电源和手动电桥设置
-   [行为和问题](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/docs/behavior.md): 超时、缓冲、平台注释和故障排除
-   [API 参考](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-api): 在此 README 中生成 TypeScript API 引用

## 平台支持

| 平台 | 状态 | 页:1 |
| --- | --- | --- |
| 机器人 | 原生 TCP | 互联网/网络权限自动合并 |
| iOS系统 | 原生 TCP | 需要本地设备的本地网络使用描述 |
| 电子 | 原生 TCP | 使用电容或手动桥 |
| 网页 | 发展支点 | 保持相同的 API 形状,但不打开真正的 TCP 套接字 |

## 常见命令

```bash
npm run build
npm test
npm run verify:web
```

## API 密码

下面生成的 API 文档根 `@devioarts/capacitor-tcpclient` capacitor apps使用的出入口. 手册 电桥直接在IPC上暴露出当地的方法,所以它使用 `connectionId` 每一次电话,而不是 `createConnection()`。 。 。 .

-   [`createConnection(...)`](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-createconnection)
-   [`getPluginPlatform()`](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-getpluginplatform)
-   [接口](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-interfaces)
-   [类型异名](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-type-aliases)

### 创建连接(...)

```typescript
createConnection(options?: TcpCreateConnectionOptions | undefined) => TCPConnection
```

创建( 或检索) TCP 连接实例 .

-   没有连接Id:总是用生成的UUID创建新实例.
-   连接Id: 如果已创建, 返回已有实例 , 否则就会产生新的问题.
-   这里提供的主机/端口/出站/无Delay/keepAlive成为连接的默认值 ().

| 参数 | 类型 |
| --- | --- |
| **`options`** | `[TcpCreateConnectionOptions](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpcreateconnectionoptions)` |

**回返情况:** `[TCPConnection](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpconnection)`

* * *

### 获取 Plugin 公式 ()

```typescript
getPluginPlatform() => Promise<TcpGetPlatformResult>
```

返回此插件本地执行的平台标识符 ("ios""android""electron""网站").

与电容核心的区别 `Capacitor.getPlatform()` ——当 你需要知道TCP层是否有iOS,Android,Electron的支持, 或浏览器开发根.

**回返情况:** `Promise<[TcpGetPlatformResult](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpgetplatformresult)>`

* * *

### 接口

#### 技术合作中心

由 TCPClient.createConnection () 返回的单个 TCP 连接实例 . 每个实例都有自己的插座、事件听众和生命周期.

| Prop | 类型 |
| --- | --- |
| **`connectionId`** | `string` |

| 方法 | 签署 | 说明 |
| --- | --- | --- |
| **连接** | (选择? ) [部分](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-partial)<[Tcp 连接选项](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpconnectoptions)\> QQ未定义) QQ 承诺 <[TcpConnect 结果](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpconnectresult)\> 翻译: | 打开接头 选项与创建Connection()中提供的默认合并. 主机必须在创建连接( Connection) 中或此处存在 . |
| **断开** | (.) 承诺 <[Tcp 断开连接结果](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpdisconnectresult)\> 翻译: | 关上插座 同上,注: 原地拆分完成后解决. Emits tcpDisconnect(理由:手动). |
| **已连接** | (.) 承诺 <[TcpIsConnected 成果](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpisconnectedresult)\> 翻译: |  |
| **正在读取** | (.) 承诺 <[TcpIs 读取结果](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpisreadingresult)\> 翻译: |  |
| **写入** | (选项 : [TcpWrite 选项](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpwriteoptions)) (中文(简体) ). 承诺 <[TcpWrite 结果](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpwriteresult)\> 翻译: |  |
| **写入和读** | (选项 : [TcpWrite 读取选项](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpwriteandreadoptions)) (中文(简体) ). 承诺 <[TcpWriteAndRead Result (英语)](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpwriteandreadresult)\> 翻译: |  |
| **开始读取** | (选择? ) [Tcp 开始读取选项](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpstartreadoptions) QQ 未定义) QQ 承诺 <[TcpStart 停止执行](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpstartstopresult)\> 翻译: |  |
| **停止读取** | (.) 承诺 <[TcpStart 停止执行](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpstartstopresult)\> 翻译: |  |
| **设置读取时间** | (选项 : { readTimeout: number;}}}\\\\ 承诺}错误:布尔; 错误: 字符串 {}无效;} | 配置流读超时 。 - 安卓:套装 `SO_TIMEOUT` 连续读取器套接字(在 `startRead`) - iOS:无-op(有I/O,没有阻断超时). - 电:设置默认值 `timeout` 使用的数值 `writeAndRead` 当没有通过明确的超时; 如果在连接前调用, 默认会被存储而不创建套接字状态条目 . |
| **添加倾听器** | (活动名:"tcpData",听众Func: (活动名: [TcpData 事件](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpdataevent)(虚空) 承诺 <[插件听筒](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-pluginlistenerhandle)\> 翻译: | 订阅为流数据. 只有此连接Id的事件才会被发送 . |
| **添加倾听器** | (活动名:"tcpDisk",听众Func: (活动名: [Tcp 断开事件](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpdisconnectevent)(虚空) 承诺 <[插件听筒](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-pluginlistenerhandle)\> 翻译: | 订阅此连接的断开通知 . |
| **删除全部收听器** | (.) 承诺<有效> | 删除所有通过此实例注册的听众 . |
| **销毁** | (.) 承诺<有效> | 断开连接, 删除所有收听者, 即使收听者清理失败, 也会从注册中释放此实例 . |

#### TcpConnect 结果

| Prop | 类型 |
| --- | --- |
| **`error`** | `boolean` |
| **`errorMessage`** | `string | null` |
| **`connected`** | `boolean` |

#### Tcp 连接选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`host`** | `string` | 主机名或IP地址 。 需要( 这里或创建连接) . |
| **`port`** | `number` | TCP端口,默认为9100. 有效范围为1.65535. |
| **`timeout`** | `number` | 连接超时以毫秒计,默认为3000. 包括DNS和套接字连接预算. |
| **`noDelay`** | `boolean` | 启用 TCP NODELAY (鼻音关闭)。 默认真实. |
| **`keepAlive`** | `boolean` | 启用 SO KEINALIVE 。 默认真实. |

#### Tcp 断开连接结果

| Prop | 类型 |
| --- | --- |
| **`error`** | `boolean` |
| **`errorMessage`** | `string | null` |
| **`disconnected`** | `boolean` |
| **`reading`** | `boolean` |

#### TcpIsConnected 成果

| Prop | 类型 |
| --- | --- |
| **`error`** | `boolean` |
| **`errorMessage`** | `string | null` |
| **`connected`** | `boolean` |

#### TcpIs 读取结果

| Prop | 类型 |
| --- | --- |
| **`error`** | `boolean` |
| **`errorMessage`** | `string | null` |
| **`reading`** | `boolean` |

#### TcpWrite 结果

| Prop | 类型 |
| --- | --- |
| **`error`** | `boolean` |
| **`errorMessage`** | `string | null` |
| **`bytesSent`** | `number` |

#### TcpWrite 选项

| Prop | 类型 |
| --- | --- |
| **`data`** | `[TcpBytePayload](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpbytepayload)` |

#### TcpByte 箭头类似

类似字节的数组被写入 API 所接受. 支持Uint8Array是因为它有数值索引和长度.

| Prop | 类型 |
| --- | --- |
| **`length`** | `number` |

#### TcpWriteAndRead Result (英语)

| Prop | 类型 |
| --- | --- |
| **`error`** | `boolean` |
| **`errorMessage`** | `string | null` |
| **`bytesSent`** | `number` |
| **`bytesReceived`** | `number` |
| **`data`** | `number[]` |
| **`matched`** | `boolean` |

#### TcpWrite 读取选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`data`** | `[TcpBytePayload](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpbytepayload)` |  |
| **`timeout`** | `number` | RR超时数为ms. 默认1000. 值 QQ 0 回到默认值 . |
| **`maxBytes`** | `number` | 要累积的最大字节 。 默认为4096,封顶为16 MiB. |
| **`expect`** | `string | [TcpBytePayload](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpbytepayload)` | 可选模式——找到后停止读取. 接受数字 \[\] / Uint8Array 或 十六进制字符串(例如"1B40","0x1b 0x40"). 空值被视为无预期模式 . |
| **`suspendStreamDuringRR`** | `boolean` | 在 RR 期间暂停流读取器, 以避免消耗回复 。 默认真实. |

#### TcpStart 停止执行

| Prop | 类型 |
| --- | --- |
| **`error`** | `boolean` |
| **`errorMessage`** | `string | null` |
| **`reading`** | `boolean` |

#### Tcp 开始读取选项

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`chunkSize`** | `number` | 以字节形式流出读取块大小 。 默认为4096,封顶为16 MiB. - Android/iOS:每个本地套接字的大小在桥上微打前读取. - 电:微打后每发射tcpData事件的最大字节. |
| **`readTimeout`** | `number` | 流读超时数以毫秒计。 - 安卓:套装 `SO_TIMEOUT` 为连续的读者。 iOS: no-op. Electron:更新每次连接默认值 `writeAndRead` 超时; 流读取器本身仍由事件驱动 . |

#### 插件听筒

| Prop | 类型 |
| --- | --- |
| **`remove`** | `() => Promise<void>` |

#### TcpData 事件

被溪读取者所入. 连接ID 识别哪个连接发送数据 .

| Prop | 类型 |
| --- | --- |
| **`connectionId`** | `string` |
| **`data`** | `number[]` |

#### Tcp 断开事件

连接关闭时发出通知 .

| Prop | 类型 |
| --- | --- |
| **`connectionId`** | `string` |
| **`disconnected`** | `true` |
| **`reading`** | `boolean` |
| **`reason`** | `'error' | 'manual' | 'remote'` |
| **`error`** | `string` |

#### Tcp 创建连接选项

TCPClient.createConnection () 的选项. 所有字段都是可选的. 这里设置的主机/ 端口和其他连接选项变为 在返回实例上调用每个连接的默认值 .

| Prop | 类型 | 说明 |
| --- | --- | --- |
| **`connectionId`** | `string` | 此连接的可选稳定标识符 。 如果在登记簿中已经存在这种身份证明,则按原样返回。 允许每次用生成的 UUID 获取新实例 . |

#### TcpGetPlatform 结果

| Prop | 类型 |
| --- | --- |
| **`error`** | `boolean` |
| **`errorMessage`** | `string | null` |
| **`platform`** | `[TcpPlatform](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpplatform)` |

### 类型异名

#### 部分

让 T 中的所有属性可选

`{ [P in keyof T]?: T[P]; }`

#### TcpBytePay 负荷

被写入 API 接受的字节有效载荷 。 值必须是0.255范围内的整数字节.

`number[] | [TcpByteArrayLike](https://npmcn.com/package/%40devioarts/capacitor-tcpclient/#readme-tcpbytearraylike)`

#### Tcp 公式

`'ios' | 'android' | 'web' | 'electron'`

## 许可证

麻省理工学院

## 常见问题

### @devioarts/capacitor-tcpclient 是什么？

在Android、iOS和Electron上工作的Capacitor的 TCP客户端

### 如何安装 @devioarts/capacitor-tcpclient？

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

### @devioarts/capacitor-tcpclient 支持 TypeScript 吗？

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

### @devioarts/capacitor-tcpclient 支持 ESM 还是 CommonJS？

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

### @devioarts/capacitor-tcpclient 可以商用吗？

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

### @devioarts/capacitor-tcpclient 的下载量有多少？

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

### @devioarts/capacitor-tcpclient 还在维护吗？

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