1# @ohos.util.stream (数据流基类stream) 2<!--Kit: ArkTS--> 3<!--Subsystem: CommonLibrary--> 4<!--Owner: @xliu-huanwei; @shilei123; @huanghello--> 5<!--Designer: @yuanyao14--> 6<!--Tester: @kirl75; @zsw_zhushiwei--> 7<!--Adviser: @ge-yafang--> 8 9本模块提供基本流类型的处理能力，支持数据分块读取或写入，避免一次性加载整个数据到内存。 10 11包括可写流（[Writable](#writable)）、可读流（[Readable](#readable)）、双工流（[Duplex](#duplex)）和转换流（[Transform](#transform)）。 12 13> **说明：** 14> 15> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 16 17## 导入模块 18 19```ts 20import { stream } from '@kit.ArkTS'; 21``` 22 23## Writable 24 25可写入数据的流。可写流允许将数据写入到目标中，这个目标可以是文件、HTTP 响应、标准输出、另一个流等。 26 27### 属性 28 29**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 30 31**系统能力：** SystemCapability.Utils.Lang 32 33| 名称 | 类型 | 只读 | 可选 | 说明 | 34| ------- | -------- | ------ | ------ | ----------- | 35| writableObjectMode | boolean | 是 | 否 | 指定可写流是否以对象模式工作。true表示流被配置为对象模式，false表示流处于非对象模式。当前版本只支持原始数据（字符串和Uint8Array），返回值为false。 | 36| writableHighWatermark | number | 是 | 否 | 定义可写流缓冲区数据量的水位线大小。当前版本不支持开发者自定义修改水位线大小。调用[write()](#write)写入数据后，若缓冲区数据量达到该值，[write()](#write)会返回false。默认值为16 * 1024字节。| 37| writable | boolean | 是 | 否 | 表示可写流是否处于可写状态。true表示流当前是可写的，false表示流当前不再接受写入操作。| 38| writableLength | number | 是 | 否 | 表示可写流缓冲区中待写入的字节数。| 39| writableCorked | number | 是 | 否 | 表示可写流cork状态计数。值大于0时，可写流处于强制写入缓冲区状态；值为0时，该状态解除。使用[cork()](#cork)方法时计数加一，使用[uncork()](#uncork)方法时计数减一，使用[end()](#end)方法时计数清零。| 40| writableEnded | boolean | 是 | 否 | 表示当前可写流的[end()](#end)是否被调用，该状态不代表数据已经全部写入。true表示[end()](#end)已被调用，false表示[end()](#end)未被调用。 | 41| writableFinished | boolean | 是 | 否 | 表示当前可写流是否处于写入完成状态。true表示当前流已处于写入完成状态，false表示当前流的写入操作可能还在进行中。 | 42 43### constructor 44 45constructor() 46 47Writable的构造函数。 48 49**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 50 51**系统能力：** SystemCapability.Utils.Lang 52 53**示例：** 54 55```ts 56let writableStream = new stream.Writable(); 57``` 58 59### write 60 61write(chunk?: string | Uint8Array, encoding?: string, callback?: Function): boolean 62 63将数据写入流的缓冲区中。使用callback异步回调。 64 65**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 66 67**系统能力：** SystemCapability.Utils.Lang 68 69**参数：** 70 71| 参数名 | 类型 | 必填 | 说明 | 72| ------ | ------ | ---- | -------------------------- | 73| chunk | string \| Uint8Array | 否 | 需要写入的数据。当前版本不支持null、undefined和空字符串。 | 74| encoding | string | 否 | 字符编码类型。默认值是'utf8'，当前版本支持'utf8'、'gb18030'、'gbk'以及'gb2312'。| 75| callback | Function | 否 | 回调函数。默认不调用。 | 76 77**返回值：** 78 79| 类型 | 说明 | 80| ------ | ---------------------- | 81| boolean | 可写流的缓冲区中是否还有空间。true表示缓冲区还有空间，false表示流的内部缓冲区数据量已达到设定水位线，不建议继续写入。 | 82 83**错误码：** 84 85以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 86 87| 错误码ID | 错误信息 | 88| -------- | -------- | 89| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 90| 10200035 | The doWrite method has not been implemented. | 91| 10200036 | The stream has been ended. | 92| 10200037 | The callback is invoked multiple times consecutively. | 93 94**示例：** 95 96```ts 97class TestWritable extends stream.Writable { 98 constructor() { 99 super(); 100 } 101 102 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 103 console.info("Writable chunk is", chunk); // Writable chunk is test 104 callback(); 105 } 106} 107 108let writableStream = new TestWritable(); 109writableStream.write('test', 'utf8'); 110``` 111 112### end 113 114end(chunk?: string | Uint8Array, encoding?: string, callback?: Function): Writable 115 116结束可写流的写入操作。如果属性writableCorked的值大于0，会置零该值并输出缓冲区剩余数据。如果传入chunk参数，则根据实际运行情况，通过write或者doWrite将其作为最后一块数据写入。其中通过doWrite写入时，encoding参数的合法性检查依赖doWrite。end单独使用（不使用write）并传入chunk参数的情况下，必然通过doWrite写入。使用callback异步回调。 117 118**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 119 120**系统能力：** SystemCapability.Utils.Lang 121 122**参数：** 123 124| 参数名 | 类型 | 必填 | 说明 | 125| ------ | ------ | ---- | -------------------------- | 126| chunk | string \| Uint8Array | 否 | 需要写入的数据。默认为undefined。 | 127| encoding | string | 否 | 字符编码类型。默认值是'utf8'，当前版本支持'utf8'、'gb18030'、'gbk'以及'gb2312'。| 128| callback | Function | 否 | 回调函数。| 129 130**返回值：** 131 132| 类型 | 说明 | 133| ------ | ---------------------- | 134| [Writable](#writable) | 返回当前可写流对象。 | 135 136**错误码：** 137 138以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 139 140| 错误码ID | 错误信息 | 141| -------- | -------- | 142| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 143| 10200035 | The doWrite method has not been implemented. | 144 145**示例：** 146 147```ts 148class TestWritable extends stream.Writable { 149 constructor() { 150 super(); 151 } 152 153 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 154 console.info("Writable chunk is", chunk); 155 callback(); 156 } 157 // Writable chunk is test 158 // Writable chunk is finish 159} 160 161let writableStream = new TestWritable(); 162writableStream.write('test', 'utf8'); 163writableStream.end('finish', 'utf8', () => { 164 console.info("Writable is end"); // Writable is end 165}); 166``` 167 168### setDefaultEncoding 169 170setDefaultEncoding(encoding?: string): boolean 171 172设置可写流的默认字符编码。 173 174**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 175 176**系统能力：** SystemCapability.Utils.Lang 177 178**参数：** 179 180| 参数名 | 类型 | 必填 | 说明 | 181| -------- | -------- | -------- | -------- | 182| encoding | string | 否 | 设置默认字符编码。默认值是'utf8'，当前版本支持'utf8'、'gb18030'、'gbk'以及'gb2312'。| 183 184**返回值：** 185 186| 类型 | 说明 | 187| -------- | -------- | 188| boolean | 返回是否设置成功。true表示成功，false表示失败。 | 189 190**错误码：** 191 192以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 193 194| 错误码ID | 错误信息 | 195| -------- | -------- | 196| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 197 198**示例：** 199 200```ts 201class TestWritable extends stream.Writable { 202 constructor() { 203 super(); 204 } 205 206 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 207 callback(); 208 } 209} 210 211let writableStream = new TestWritable(); 212let result = writableStream.setDefaultEncoding('utf8'); 213console.info("Writable is result", result); // Writable is result true 214``` 215 216### cork 217 218cork(): boolean 219 220使后续写入的数据强制写入缓冲区，优化连续写入操作的性能。使用后属性writableCorked的值会加一。建议和[uncork()](#uncork)成对使用。 221 222**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 223 224**系统能力：** SystemCapability.Utils.Lang 225 226**返回值：** 227 228| 类型 | 说明 | 229| -------- | -------- | 230| boolean | 返回设置cork状态是否成功。true表示成功，false表示失败。 | 231 232**示例：** 233 234```ts 235class TestWritable extends stream.Writable { 236 constructor() { 237 super(); 238 } 239 240 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 241 callback(); 242 } 243} 244 245let writableStream = new TestWritable(); 246let result = writableStream.cork(); 247console.info("Writable cork result", result); // Writable cork result true 248``` 249 250### uncork 251 252uncork(): boolean 253 254解除cork状态，解除后刷新缓冲区数据并写入目标位置。使用后属性writableCorked的值会减一，如果该值降为0，则解除cork状态，否则流依然处于cork状态。建议和[cork()](#cork)成对使用。 255 256**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 257 258**系统能力：** SystemCapability.Utils.Lang 259 260**返回值：** 261 262| 类型 | 说明 | 263| -------- | -------- | 264| boolean | 返回解除cork状态是否成功。true表示成功，false表示失败。 | 265 266**示例：** 267 268```ts 269class TestWritable extends stream.Writable { 270 constructor() { 271 super(); 272 } 273 274 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 275 callback(); 276 } 277} 278 279let writableStream = new TestWritable(); 280writableStream.cork(); 281writableStream.write('data1', 'utf8'); 282writableStream.write('data2', 'utf8'); 283writableStream.uncork(); 284writableStream.end(); 285writableStream.on('finish', () => { 286 console.info("all Data is End"); // all Data is End 287}); 288``` 289 290### on 291 292on(event: string, callback: Callback<emitter.EventData>): void 293 294注册事件处理函数来监听可写流上的不同事件。 295 296**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 297 298**系统能力：** SystemCapability.Utils.Lang 299 300**参数：** 301 302| 参数名 | 类型 | 必填 | 说明 | 303| -------- | -------- | -------- | -------- | 304| event | string | 是 | 事件回调类型，支持的事件包括：`'close'` \| `'drain' `\|`'error'` \| `'finish'` 。<br/>\- `'close'`：完成[end()](#end)调用，结束写入操作，触发该事件。<br/>\- `'drain'`：在可写流缓冲区中数据清空时触发该事件。<br/>\- `'error'`：在可写流发生异常时触发该事件。<br/>\- `'finish'`：在数据缓冲区全部写入到目标后触发该事件。 | 305| callback | Callback\<[emitter.EventData](../apis-basic-services-kit/js-apis-emitter.md#eventdata)\> | 是 | 回调函数，返回事件传输的数据。 | 306 307**错误码：** 308 309以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 310 311| 错误码ID | 错误信息 | 312| -------- | -------- | 313| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 314 315**示例：** 316 317```ts 318class TestWritable extends stream.Writable { 319 constructor() { 320 super(); 321 } 322 323 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 324 callback(new Error()); 325 } 326} 327 328let callbackCalled = false; 329let writable = new TestWritable(); 330writable.on('error', () => { 331 console.info("Writable event test", callbackCalled.toString()); // Writable event test false 332}); 333writable.write('hello', 'utf8', () => { 334}); 335``` 336 337### off 338 339off(event: string, callback?: Callback<emitter.EventData>): void 340 341移除通过[on](#on)注册的事件处理函数。 342 343**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 344 345**系统能力：** SystemCapability.Utils.Lang 346 347**参数：** 348 349| 参数名 | 类型 | 必填 | 说明 | 350| -------- | -------- | -------- | -------- | 351| event | string | 是 | 事件回调类型，支持的事件包括：`'close'` \| `'drain' `\|`'error'` \| `'finish'` 。<br/>\- `'close'`：完成[end()](#end)调用，结束写入操作，触发该事件。<br/>\- `'drain'`：在可写流缓冲区中数据清空时触发该事件。<br/>\- `'error'`：在可写流发生异常时触发该事件。<br/>\- `'finish'`：在数据缓冲区全部写入到目标后触发该事件。 | 352| callback | Callback\<[emitter.EventData](../apis-basic-services-kit/js-apis-emitter.md#eventdata)\> | 否 | 回调函数。 | 353 354**错误码：** 355 356以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 357 358| 错误码ID | 错误信息 | 359| -------- | -------- | 360| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 361 362**示例：** 363 364```ts 365class TestWritable extends stream.Writable { 366 constructor() { 367 super(); 368 } 369 370 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 371 callback(); 372 } 373} 374 375let writableStream = new TestWritable(); 376let testListenerCalled = false; 377let testListener = () => { 378 testListenerCalled = true; 379}; 380writableStream.on('finish', testListener); 381writableStream.off('finish'); 382writableStream.write('test'); 383writableStream.end(); 384setTimeout(() => { 385 console.info("Writable off test", testListenerCalled.toString()); // Writable off test false 386}, 0); 387``` 388 389### doInitialize 390 391doInitialize(callback: Function): void 392 393用户实现这个函数。该函数在可写流初始化阶段被调用，无需用户调用。使用callback异步回调。 394 395**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 396 397**系统能力：** SystemCapability.Utils.Lang 398 399**参数：** 400 401| 参数名 | 类型 | 必填 | 说明 | 402| -------- | -------- | -------- | -------- | 403| callback | Function | 是 | 回调函数。 | 404 405**错误码：** 406 407以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 408 409| 错误码ID | 错误信息 | 410| -------- | -------- | 411| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 412 413**示例：** 414 415```ts 416class MyWritable extends stream.Writable { 417 doInitialize(callback: Function) { 418 super.doInitialize(callback); 419 console.info("Writable doInitialize"); // Writable doInitialize 420 } 421 422 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 423 super.doWrite(chunk, encoding, callback); 424 } 425} 426 427new MyWritable(); 428``` 429 430### doWrite 431 432doWrite(chunk: string | Uint8Array, encoding: string, callback: Function): void 433 434提供一个数据写出接口供开发者实现，该接口函数会在数据被成功写出时自动调用，无需手动触发。使用callback异步回调。 435 436**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 437 438**系统能力：** SystemCapability.Utils.Lang 439 440**参数：** 441 442| 参数名 | 类型 | 必填 | 说明 | 443| ------ | ------ | ---- | -------------------------- | 444| chunk | string \| Uint8Array | 是 | 要写出的数据。 | 445| encoding | string | 是 | 字符编码类型。当前版本支持'utf8'、'gb18030'、'gbk'以及'gb2312'。| 446| callback | Function | 是 | 回调函数。 | 447 448**错误码：** 449 450以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 451 452| 错误码ID | 错误信息 | 453| -------- | -------- | 454| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 455 456**示例：** 457 458```ts 459class TestWritable extends stream.Writable { 460 constructor() { 461 super(); 462 } 463 464 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 465 console.info("Writable chunk is", chunk); // Writable chunk is data 466 callback(); 467 } 468} 469 470let writableStream = new TestWritable(); 471writableStream.write('data', 'utf8'); 472``` 473 474### doWritev 475 476doWritev(chunks: string[] | Uint8Array[], callback: Function): void 477 478提供一个数据批量写出接口供使用者实现，该接口函数会在数据被成功写出时自动调用，无需用户手动触发。使用callback异步回调。 479 480**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 481 482**系统能力：** SystemCapability.Utils.Lang 483 484**参数：** 485 486| 参数名 | 类型 | 必填 | 说明 | 487| -------- | -------- | -------- | -------- | 488| chunks | string[] \| Uint8Array[] | 是 | 被批量写出的数据数组。 | 489| callback | Function | 是 | 回调函数。 | 490 491**错误码：** 492 493以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 494 495| 错误码ID | 错误信息 | 496| -------- | -------- | 497| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 498 499**示例：** 500 501```ts 502class TestWritable extends stream.Writable { 503 constructor() { 504 super(); 505 } 506 507 doWritev(chunks: string[] | Uint8Array[], callback: Function) { 508 console.info("Writable chunk", chunks); 509 callback(); 510 } 511 // Writable chunk data1 512 // Writable chunk data2 513} 514 515let writableStream = new TestWritable(); 516writableStream.write('data1', 'utf8'); 517writableStream.write('data2', 'utf8'); 518writableStream.uncork(); 519writableStream.end(); 520``` 521 522## ReadableOptions 523 524Readable构造函数的选项信息。 525 526**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 527 528**系统能力：** SystemCapability.Utils.Lang 529 530| 名称 | 类型 | 必填 | 说明 | 531| ---- | -------- | ---- | -------------- | 532| encoding | string | 否 | 指定数据的编码格式，如果传入非法字符串，将会在Readable构造函数中抛出异常。<br/>- 支持格式：utf-8、UTF-8、GBK、GB2312、gb2312、GB18030、gb18030、ibm866、iso-8859-2、iso-8859-3、iso-8859-4、iso-8859-5、iso-8859-6、iso-8859-7、iso-8859-8、iso-8859-8-i、iso-8859-10、iso-8859-13、iso-8859-14、iso-8859-15、koi8-r、koi8-u、macintosh、windows-874、windows-1250、windows-1251、windows-1252、windows-1253、windows-1254、windows-1255、windows-1256、windows-1257、windows-1258、gbk、big5、euc-jp、iso-2022-jp、shift_jis、euc-kr、x-mac-cyrillic、utf-16be、utf-16le。 <br/>- 默认值是：'utf-8'。| 533 534## Readable 535 536表示可读取数据的流。可读流用于从数据源（如文件、网络套接字等）读取数据。 537 538### 属性 539 540**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 541 542**系统能力：** SystemCapability.Utils.Lang 543 544| 名称 | 类型 | 只读| 可选 | 说明 | 545| ------- | -------- | ------ | ------ | ----------- | 546| readableObjectMode | boolean | 是 | 否 | 用于指定可读流是否以对象模式工作。true表示流被配置为对象模式，false表示流处于非对象模式。当前版本只支持原始数据（字符串和Uint8Array），返回值为false。| 547| readable | boolean | 是 | 否 | 表示可读流是否处于可读状态。true表示流处于可读状态，false表示流中没有更多数据可供读取。 | 548| readableHighWatermark | number | 是 | 否 | 定义缓冲区的最大数据量。默认值为16 * 1024字节。| 549| readableFlowing | boolean \| null | 是 | 否 | 表示当前可读流的状态。true表示流处于流动模式，false表示流处于非流动模式。默认值是true。| 550| readableLength | number | 是 | 否 | 表示缓冲区的当前字节数。| 551| readableEncoding | string \| null | 是 | 否 | 被解码成字符串时所使用的字符编码。默认值是'utf8'，当前版本支持'utf8'、'gb18030'、'gbk'以及'gb2312'。| 552| readableEnded | boolean | 是 | 否 | 表示当前可读流是否已经结束。true表示流已经没有更多数据可读且已结束，false表示流尚未结束，仍有数据可读或等待读取。 | 553 554### constructor 555 556constructor() 557 558Readable的构造函数。 559 560**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 561 562**系统能力：** SystemCapability.Utils.Lang 563 564**示例：** 565 566```ts 567let readableStream = new stream.Readable(); 568``` 569 570### constructor 571 572constructor(options: ReadableOptions) 573 574Readable的构造函数。 575 576**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 577 578**系统能力：** SystemCapability.Utils.Lang 579 580**参数：** 581 582| 参数名 | 类型 | 必填 | 说明 | 583| ------ | -------- | -------- | -------- | 584| options | [ReadableOptions](#readableoptions) | 是 | Readable构造函数的选项信息。| 585 586**错误码：** 587 588以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 589 590| 错误码ID | 错误信息 | 591| -------- | -------- | 592| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 593 594**示例：** 595 596```ts 597let option : stream.ReadableOptions = { 598 encoding : 'utf-8' 599}; 600let readableStream = new stream.Readable(option); 601``` 602 603### read 604 605read(size?: number): string | null 606 607从可读流缓冲区读取数据，并返回读取到的数据，如果未读取到数据，则返回null。 608 609**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 610 611**系统能力：** SystemCapability.Utils.Lang 612 613**参数：** 614 615| 参数名 | 类型 | 必填 | 说明 | 616| ------ | -------- | -------- | -------- | 617| size | number | 否 | 读取数据的字节数。默认为undefined。 | 618 619**返回值：** 620 621| 类型 | 说明 | 622| ------ | ---------------------- | 623| string \| null | 可读流读取出的数据。 | 624 625**错误码：** 626 627以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 628 629| 错误码ID | 错误信息 | 630| -------- | -------- | 631| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 632| 10200038 | The doRead method has not been implemented. | 633 634**示例：** 635 636```ts 637class TestReadable extends stream.Readable { 638 constructor() { 639 super(); 640 } 641 642 doRead(size: number) { 643 } 644} 645 646let readableStream = new TestReadable(); 647readableStream.push('test'); 648readableStream.pause(); 649let dataChunk = readableStream.read(); 650console.info('Readable data is', dataChunk); // Readable data is test 651``` 652 653### resume 654 655resume(): Readable 656 657将流的读取模式从暂停切换到流动模式，可用接口isPaused判断是否已切换。 658 659**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 660 661**系统能力：** SystemCapability.Utils.Lang 662 663**返回值：** 664 665| 类型 | 说明 | 666| ------ | ---------------------- | 667| [Readable](#readable) | 当前可读流本身。 | 668 669**示例：** 670 671```ts 672class TestReadable extends stream.Readable { 673 constructor() { 674 super(); 675 } 676 677 doRead(size: number) { 678 } 679} 680 681let readableStream = new TestReadable(); 682readableStream.resume(); 683console.info("Readable test resume", !readableStream.isPaused()); // 切换流动模式成功时，此处日志将打印"Readable test resume true" 684``` 685 686### pause 687 688pause(): Readable 689 690将流的读取模式从流动切换到暂停模式，可用接口isPaused判断是否已切换。 691 692**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 693 694**系统能力：** SystemCapability.Utils.Lang 695 696**返回值：** 697 698| 类型 | 说明 | 699| ------ | ---------------------- | 700| [Readable](#readable) | 当前可读流本身。 | 701 702**示例：** 703 704```ts 705class TestReadable extends stream.Readable { 706 constructor() { 707 super(); 708 } 709 710 doRead(size: number) { 711 } 712} 713 714let readableStream = new TestReadable(); 715readableStream.pause(); 716console.info("Readable test pause", readableStream.isPaused()); // Readable test pause true 717``` 718 719### setEncoding 720 721setEncoding(encoding?: string): boolean 722 723设置可读流的字符编码。 724当缓冲区有数据时，不允许设置字符编码，返回值为false。 725 726**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 727 728**系统能力：** SystemCapability.Utils.Lang 729 730**参数：** 731 732| 参数名 | 类型 | 必填 | 说明 | 733| -------- | -------- | -------- | -------- | 734| encoding | string | 否 | 需要设置的字符编码。默认值是'utf8'，当前版本支持'utf8'、'gb18030'、'gbk'以及'gb2312'。 | 735 736**返回值：** 737 738| 类型 | 说明 | 739| -------- | -------- | 740| boolean | 返回是否设置成功。true表示设置成功，false表示设置失败。 | 741 742**错误码：** 743 744以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 745 746| 错误码ID | 错误信息 | 747| -------- | -------- | 748| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 749 750**示例：** 751 752```ts 753class TestReadable extends stream.Readable { 754 constructor() { 755 super(); 756 } 757 758 doRead(size: number) { 759 } 760} 761 762let readableStream = new TestReadable(); 763let result = readableStream.setEncoding('utf8'); 764console.info("Readable result", result); // Readable result true 765``` 766 767### isPaused 768 769isPaused(): boolean 770 771检查流是否处于暂停模式，调用[pause()](#pause)后，返回值为true；调用[resume()](#resume)后，返回值为false。 772 773**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 774 775**系统能力：** SystemCapability.Utils.Lang 776 777**返回值：** 778 779| 类型 | 说明 | 780| -------- | -------- | 781| boolean | 返回流是否处于暂停模式。true表示流处于暂停模式，false表示流未处于暂停模式。 | 782 783**示例：** 784 785```ts 786class TestReadable extends stream.Readable { 787 constructor() { 788 super(); 789 } 790 791 doRead(size: number) { 792 } 793} 794 795let readableStream = new TestReadable(); 796console.info("Readable isPaused", readableStream.isPaused()); // Readable isPaused false 797readableStream.pause(); 798console.info("Readable isPaused", readableStream.isPaused()); // Readable isPaused true 799``` 800 801### pipe 802 803pipe(destination: Writable, options?: Object): Writable 804 805将一个可读流与一个可写流连接起来，实现数据的自动传输。 806 807**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 808 809**系统能力：** SystemCapability.Utils.Lang 810 811**参数：** 812 813| 参数名 | 类型 | 必填 | 说明 | 814| -------- | -------- | -------- | -------- | 815| destination | [Writable](#writable) | 是 | 接收数据的可写流。| 816| options | Object | 否 | 预留字段，暂不支持使用。 | 817 818**返回值：** 819 820| 类型 | 说明 | 821| -------- | -------- | 822| [Writable](#writable) | 返回当前可写流对象。 | 823 824**错误码：** 825 826以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 827 828| 错误码ID | 错误信息 | 829| -------- | -------- | 830| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 831 832**示例：** 833 834```ts 835class TestReadable extends stream.Readable { 836 constructor() { 837 super(); 838 } 839 840 doRead(size: number) { 841 this.push('test'); 842 this.push(null); 843 } 844} 845 846class TestWritable extends stream.Writable { 847 constructor() { 848 super(); 849 } 850 851 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 852 console.info("Readable test pipe", chunk); // Readable test pipe test 853 callback(); 854 } 855} 856 857let readable = new TestReadable(); 858let writable = new TestWritable(); 859readable.pipe(writable); 860``` 861 862### unpipe 863 864unpipe(destination?: Writable): Readable 865 866从可写流中移除所有或指定的已连接的可读流。 867 868**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 869 870**系统能力：** SystemCapability.Utils.Lang 871 872**参数：** 873 874| 参数名 | 类型 | 必填 | 说明 | 875| -------- | -------- | -------- | -------- | 876| destination | [Writable](#writable) | 否 | 从当前可写流中移除指定的这个可读流。默认为undefined。| 877 878**返回值：** 879 880| 类型 | 说明 | 881| -------- | -------- | 882| [Readable](#readable) | 返回当前可读流对象。 | 883 884**错误码：** 885 886以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 887 888| 错误码ID | 错误信息 | 889| -------- | -------- | 890| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 891 892**示例：** 893 894```ts 895class TestReadable extends stream.Readable { 896 constructor() { 897 super(); 898 } 899 900 doRead(size: number) { 901 this.push('test'); 902 this.push(null); 903 } 904} 905 906class TestWritable extends stream.Writable { 907 constructor() { 908 super(); 909 } 910 911 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 912 callback(); 913 } 914} 915 916let readable = new TestReadable(); 917let writable = new TestWritable(); 918readable.pipe(writable); 919readable.unpipe(writable); 920readable.on('data', () => { 921 console.info("Readable test unpipe data event triggered"); 922}); 923// unpipe成功断开连接之后，data事件将不会触发，不会打印"Readable test unpipe data event triggered" 924``` 925 926### on 927 928on(event: string, callback: Callback<emitter.EventData>): void 929 930注册事件处理函数来监听可读流上的不同事件。 931 932**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 933 934**系统能力：** SystemCapability.Utils.Lang 935 936**参数：** 937 938| 参数名 | 类型 | 必填 | 说明 | 939| -------- | -------- | -------- | -------- | 940| event | string | 是 | 事件回调类型，支持的事件包括：`'close'` \| `'data' `\|`'end'` \| `'error'`\|`'readable'`\|`'pause'`\|`'resume'` 。<br/>\- `'close'`：完成[push()](#push)调用，传入null值，触发该事件。<br/>\- `'data'`：当流传递给消费者一个数据块时触发该事件。<br/>\- `'end'`：完成[push()](#push)调用，传入null值，触发该事件。<br/>\- `'error'`：流发生异常时触发。<br/>\- `'readable'`：当有可从流中读取的数据时触发该事件。<br/>\- `'pause'`：完成[pause()](#pause)调用，触发该事件。<br/>\- `'resume'`：完成[resume()](#resume)调用，触发该事件。 | 941| callback | Callback\<[emitter.EventData](../apis-basic-services-kit/js-apis-emitter.md#eventdata)\> | 是 | 回调函数，返回事件数据。 | 942 943**错误码：** 944 945以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 946 947| 错误码ID | 错误信息 | 948| -------- | -------- | 949| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 950 951**示例：** 952 953```ts 954class TestReadable extends stream.Readable { 955 constructor() { 956 super(); 957 } 958 959 doRead(size: number) { 960 throw new Error('Simulated error'); 961 } 962} 963 964let readable = new TestReadable(); 965readable.push('test'); 966readable.on('error', () => { 967 console.info("error event called"); // error event called 968}); 969``` 970 971### off 972 973off(event: string, callback?: Callback<emitter.EventData>): void 974 975移除通过[on](#on)注册的事件处理函数。 976 977**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 978 979**系统能力：** SystemCapability.Utils.Lang 980 981**参数：** 982 983| 参数名 | 类型 | 必填 | 说明 | 984| -------- | -------- | -------- | -------- | 985| event | string | 是 | 事件回调类型，支持的事件包括：`'close'` \| `'data' `\|`'end'` \| `'error'`\|`'readable'`\|`'pause'`\|`'resume'` 。<br/>\- `'close'`：完成[push()](#push)调用，传入null值，触发该事件。<br/>\- `'data'`：当流传递给消费者一个数据块时触发该事件。<br/>\- `'end'`：完成[push()](#push)调用，传入null值，触发该事件。<br/>\- `'error'`：流发生异常时触发。<br/>\- `'readable'`：当有可从流中读取的数据时触发该事件。<br/>\- `'pause'`：完成[pause()](#pause)调用，触发该事件。<br/>\- `'resume'`：完成[resume()](#resume)调用，触发该事件。 | 986| callback | Callback\<[emitter.EventData](../apis-basic-services-kit/js-apis-emitter.md#eventdata)\> | 否 | 回调函数。 | 987 988**错误码：** 989 990以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 991 992| 错误码ID | 错误信息 | 993| -------- | -------- | 994| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 995 996**示例：** 997 998```ts 999class TestReadable extends stream.Readable { 1000 constructor() { 1001 super(); 1002 } 1003 1004 doRead(size: number) { 1005 } 1006} 1007 1008let readable = new TestReadable(); 1009 1010function read() { 1011 console.info("read() called"); 1012} 1013 1014readable.setEncoding('utf8'); 1015readable.on('readable', read); 1016readable.off('readable'); 1017readable.push('test'); 1018// off注销对readable事件的监听后，read函数不会被调用，"read() called"也不会被打印 1019``` 1020 1021### doInitialize 1022 1023doInitialize(callback: Function): void 1024 1025使用者实现这个函数，这个函数在可读流第一次使用[on](#on-1)监听时被调用。使用callback异步回调。 1026 1027**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1028 1029**系统能力：** SystemCapability.Utils.Lang 1030 1031**参数：** 1032 1033| 参数名 | 类型 | 必填 | 说明 | 1034| -------- | -------- | -------- | -------- | 1035| callback | Function | 是 | 回调函数。 | 1036 1037**错误码：** 1038 1039以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1040 1041| 错误码ID | 错误信息 | 1042| -------- | -------- | 1043| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1044 1045**示例：** 1046 1047```ts 1048class MyReadable extends stream.Readable { 1049 doInitialize(callback: Function) { 1050 super.doInitialize(callback); 1051 console.info("Readable doInitialize"); // Readable doInitialize 1052} 1053 1054 doRead(size: number) { 1055 } 1056} 1057 1058let myReadable = new MyReadable(); 1059myReadable.on('data', () => { 1060}); 1061``` 1062 1063### doRead 1064 1065doRead(size: number): void 1066 1067数据读取接口，需要在子类中被实现。 1068 1069**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1070 1071**系统能力：** SystemCapability.Utils.Lang 1072 1073**参数：** 1074 1075| 参数名 | 类型 | 必填 | 说明 | 1076| -------- | -------- | -------- | -------- | 1077| size | number | 是 | 读取数据的字节数。 取值范围：0 <= size <= Number.MAX_VALUE。| 1078 1079**错误码：** 1080 1081以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1082 1083| 错误码ID | 错误信息 | 1084| -------- | -------- | 1085| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1086 1087**示例：** 1088 1089```ts 1090class TestReadable extends stream.Readable { 1091 constructor() { 1092 super(); 1093 } 1094 1095 doRead(size: number) { 1096 console.info("doRead called"); // doRead called 1097 } 1098} 1099 1100let readable = new TestReadable(); 1101readable.on('data', () => { 1102}); 1103``` 1104 1105### push 1106 1107push(chunk: Uint8Array | string | null, encoding?: string): boolean 1108 1109将数据推送到可读流缓冲区中。 1110 1111**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1112 1113**系统能力：** SystemCapability.Utils.Lang 1114 1115**参数：** 1116 1117| 参数名 | 类型 | 必填 | 说明 | 1118| -------- | -------- | -------- | -------- | 1119| chunk | Uint8Array \| string \| null | 是 | 读取的数据。 | 1120| encoding | string | 否 | 数据的编码格式。默认值是'utf8'，当前版本支持'utf8'、'gb18030'、'gbk'以及'gb2312'。| 1121 1122**返回值：** 1123 1124| 类型 | 说明 | 1125| -------- | -------- | 1126| boolean | 可读流的缓冲区中是否还有空间。true表示缓冲区还有空间，false表示流的内部缓冲区已满。输入null时，固定返回false表示推送结束，没有数据块可推送。 | 1127 1128**错误码：** 1129 1130以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1131 1132| 错误码ID | 错误信息 | 1133| -------- | -------- | 1134| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 1135 1136**示例：** 1137 1138```ts 1139class TestReadable extends stream.Readable { 1140 constructor() { 1141 super(); 1142 } 1143 1144 doRead(size: number) { 1145 } 1146} 1147 1148let readable = new TestReadable(); 1149let testData = 'Hello world'; 1150readable.push(testData); 1151console.info("Readable push test", readable.readableLength); // Readable push test 11 1152``` 1153 1154## Duplex 1155 1156双工流是一个同时支持可读和可写能力的流。双工流允许数据在两个方向上进行传输，既可以读取数据，又可以写入数据。 1157Duplex类继承[Readable](#readable)，支持Readable中所有的方法。 1158 1159### 属性 1160 1161**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1162 1163**系统能力：** SystemCapability.Utils.Lang 1164 1165| 名称 | 类型 | 只读 | 可选 | 说明 | 1166| ------- | -------- | ------ | ------ | ----------- | 1167| writableObjectMode | boolean | 是 | 否 | 用于指定双工流的写模式是否以对象模式工作。true表示流的写模式被配置为对象模式，false表示流的写模式处于非对象模式。当前版本只支持原始数据（字符串和Uint8Array），返回值为false。 | 1168| writableHighWatermark | number | 是 | 否 | 定义双工流的写模式下缓冲区数据量的水位线大小。当前版本不支持开发者自定义修改设置水位线大小。调用[write()](#write-1)写入后，若缓冲区数据量达到该值，[write()](#write-1)会返回false。默认值为16 * 1024字节。| 1169| writable | boolean | 是 | 否 | 表示双工流是否处于可写状态。true表示当前流是可写的，false表示流当前不再接受写入操作。| 1170| writableLength | number | 是 | 否 | 表示双工流缓冲区中待写入的字节数。| 1171| writableCorked | number | 是 | 否 | 表示双工流cork状态计数。值大于0时，双工流处于强制写入缓冲区状态，值为0时，该状态解除。使用[cork()](#cork-1)方法时计数加一，使用[uncork()](#uncork-1)方法时计数减一，使用[end()](#end-1)方法时计数清零。| 1172| writableEnded | boolean | 是 | 否 | 表示当前双工流的[end()](#end-1)是否被调用，该状态不代表数据已经全部写入。true表示[end()](#end-1)已被调用，false表示[end()](#end-1)未被调用。| 1173| writableFinished | boolean | 是 | 否 | 表示当前双工流是否处于写入完成状态。true表示当前流已处于写入完成状态，false表示当前流的写入操作可能还在进行中。| 1174 1175### constructor 1176 1177constructor() 1178 1179Duplex的构造函数。 1180 1181**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1182 1183**系统能力：** SystemCapability.Utils.Lang 1184 1185**示例：** 1186 1187```ts 1188let duplex = new stream.Duplex(); 1189``` 1190 1191### write 1192 1193write(chunk?: string | Uint8Array, encoding?: string, callback?: Function): boolean 1194 1195将数据写入流的缓冲区中。使用callback异步回调。 1196 1197**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1198 1199**系统能力：** SystemCapability.Utils.Lang 1200 1201**参数：** 1202 1203| 参数名 | 类型 | 必填 | 说明 | 1204| ------ | ------ | ---- | -------------------------- | 1205| chunk | string \| Uint8Array | 否 | 需要写入的数据。当前版本不支持null、undefined和空字符串。 | 1206| encoding | string | 否 | 字符编码类型。默认值是'utf8'，当前版本支持'utf8'、'gb18030'、'gbk'以及'gb2312'。| 1207| callback | Function | 否 | 回调函数。默认不调用。 | 1208 1209**返回值：** 1210 1211| 类型 | 说明 | 1212| ------ | ---------------------- | 1213| boolean | 可写流的缓冲区中是否还有空间。true表示缓冲区还有空间，false表示流的内部缓冲区数据量已达到设定水位线，不建议继续写入。 | 1214 1215**错误码：** 1216 1217以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1218 1219| 错误码ID | 错误信息 | 1220| -------- | -------- | 1221| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1222| 10200036 | The stream has been ended. | 1223| 10200037 | The callback is invoked multiple times consecutively. | 1224| 10200039 | The doTransform method has not been implemented for a class that inherits from Transform. | 1225 1226**示例：** 1227 1228```ts 1229class TestDuplex extends stream.Duplex { 1230 constructor() { 1231 super(); 1232 } 1233 1234 doRead(size: number) { 1235 } 1236 1237 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 1238 console.info("duplexStream chunk is", chunk); // duplexStream chunk is test 1239 callback(); 1240 } 1241} 1242 1243let duplexStream = new TestDuplex(); 1244let result = duplexStream.write('test', 'utf8'); 1245console.info("duplexStream result", result); // duplexStream result true 1246``` 1247 1248### end 1249 1250end(chunk?: string | Uint8Array, encoding?: string, callback?: Function): Writable 1251 1252结束双工流的写入操作。如果属性writableCorked的值大于0，会置零该值并输出缓冲区剩余数据。如果传入chunk参数，则根据实际运行情况，通过write或者doWrite将其作为最后一块数据写入。其中通过doWrite写入时，encoding参数的合法性检查依赖doWrite。end单独使用（不使用write）并传入chunk参数的情况下，必然通过doWrite写入。使用callback异步回调。 1253 1254**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1255 1256**系统能力：** SystemCapability.Utils.Lang 1257 1258**参数：** 1259 1260| 参数名 | 类型 | 必填 | 说明 | 1261| ------ | ------ | ---- | -------------------------- | 1262| chunk | string \| Uint8Array | 否 | 需要写入的数据。默认为undefined。 | 1263| encoding | string | 否 | 字符编码类型。默认值是'utf8'，当前版本支持'utf8'、'gb18030'、'gbk'以及'gb2312'。| 1264| callback | Function | 否 | 回调函数。默认不调用。 | 1265 1266**返回值：** 1267 1268| 类型 | 说明 | 1269| ------ | ---------------------- | 1270| [Writable](#writable) | 返回可写流对象。 | 1271 1272**错误码：** 1273 1274以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[语言基础类库错误码](errorcode-utils.md)。 1275 1276| 错误码ID | 错误信息 | 1277| -------- | -------- | 1278| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1279| 10200039 | The doTransform method has not been implemented for a class that inherits from Transform. | 1280 1281**示例：** 1282 1283```ts 1284class TestDuplex extends stream.Duplex { 1285 constructor() { 1286 super(); 1287 } 1288 1289 doRead(size: number) { 1290 } 1291 1292 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 1293 console.info("Duplex chunk is", chunk); // Duplex chunk is test 1294 callback(); 1295 } 1296} 1297 1298let duplexStream = new TestDuplex(); 1299duplexStream.end('test', 'utf8', () => { 1300 console.info("Duplex is end"); // Duplex is end 1301}); 1302``` 1303 1304### setDefaultEncoding 1305 1306setDefaultEncoding(encoding?: string): boolean 1307 1308设置双工流的默认字符编码，确保在读取数据时正确解析字符。 1309 1310**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1311 1312**系统能力：** SystemCapability.Utils.Lang 1313 1314**参数：** 1315 1316| 参数名 | 类型 | 必填 | 说明 | 1317| -------- | -------- | -------- | -------- | 1318| encoding | string | 否 | 需要设置的默认字符编码。默认值是'utf8'，当前版本支持'utf8'、'gb18030'、'gbk'以及'gb2312'。| 1319 1320**返回值：** 1321 1322| 类型 | 说明 | 1323| -------- | -------- | 1324| boolean | 返回是否设置成功。true表示设置成功，false表示设置失败。 | 1325 1326**错误码：** 1327 1328以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1329 1330| 错误码ID | 错误信息 | 1331| -------- | -------- | 1332| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1333 1334**示例：** 1335 1336```ts 1337class TestDuplex extends stream.Duplex { 1338 constructor() { 1339 super(); 1340 } 1341 1342 doRead(size: number) { 1343 } 1344 1345 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 1346 callback(); 1347 } 1348} 1349 1350let duplexStream = new TestDuplex(); 1351let result = duplexStream.setDefaultEncoding('utf8'); 1352console.info("duplexStream is result", result); // duplexStream is result true 1353``` 1354 1355### cork 1356 1357cork(): boolean 1358 1359将写入的数据强制写入缓冲区暂存，用来优化连续写入操作的性能。使用后属性writableCorked的值会加一。建议和[uncork()](#uncork-1)成对使用。 1360 1361**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1362 1363**系统能力：** SystemCapability.Utils.Lang 1364 1365**返回值：** 1366 1367| 类型 | 说明 | 1368| -------- | -------- | 1369| boolean | 返回设置cork状态是否成功。true表示设置成功，false表示设置失败。 | 1370 1371**示例：** 1372 1373```ts 1374let duplexStream = new stream.Duplex(); 1375let result = duplexStream.cork(); 1376console.info("duplexStream cork result", result); // duplexStream cork result true 1377``` 1378 1379### uncork 1380 1381uncork(): boolean 1382 1383解除cork状态，解除后将缓冲区中的数据全部刷新，并将其写入目标位置。使用后属性writableCorked的值会减一，如果该值降为0，则解除cork状态，否则流依然处于cork状态。建议和[cork()](#cork-1)成对使用。 1384 1385**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1386 1387**系统能力：** SystemCapability.Utils.Lang 1388 1389**返回值：** 1390 1391| 类型 | 说明 | 1392| -------- | -------- | 1393| boolean | 返回解除cork状态是否成功。true表示成功，false表示失败。 | 1394 1395**示例：** 1396 1397```ts 1398let dataWritten = ''; 1399class TestDuplex extends stream.Duplex { 1400 constructor() { 1401 super(); 1402 } 1403 1404 doRead(size: number) { 1405 } 1406 1407 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 1408 dataWritten += chunk; 1409 callback(); 1410 } 1411} 1412 1413let duplexStream = new TestDuplex(); 1414duplexStream.cork(); 1415duplexStream.write('a'); 1416duplexStream.write('b'); 1417duplexStream.uncork(); 1418console.info("Duplex test uncork", dataWritten); // Duplex test uncork ab 1419``` 1420 1421### doWrite 1422 1423doWrite(chunk: string | Uint8Array, encoding: string, callback: Function): void 1424 1425数据写出接口是一个由使用者实现的函数，在数据被写出时自动调用，而不需要用户手动调用。使用callback异步回调。 1426 1427**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1428 1429**系统能力：** SystemCapability.Utils.Lang 1430 1431**参数：** 1432 1433| 参数名 | 类型 | 必填 | 说明 | 1434| ------ | ------ | ---- | -------------------------- | 1435| chunk | string \| Uint8Array | 是 | 要写出的数据。 | 1436| encoding | string | 是 | 字符编码类型。当前版本支持'utf8'、'gb18030'、'gbk'以及'gb2312'。| 1437| callback | Function | 是 | 回调函数。 | 1438 1439**错误码：** 1440 1441以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1442 1443| 错误码ID | 错误信息 | 1444| -------- | -------- | 1445| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1446 1447**示例：** 1448 1449```ts 1450class TestDuplex extends stream.Duplex { 1451 constructor() { 1452 super(); 1453 } 1454 1455 doRead(size: number) { 1456 } 1457 1458 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 1459 console.info("duplexStream chunk is", chunk); // duplexStream chunk is data 1460 callback(); 1461 } 1462} 1463 1464let duplexStream = new TestDuplex(); 1465duplexStream.write('data', 'utf8'); 1466``` 1467 1468### doWritev 1469 1470doWritev(chunks: string[] | Uint8Array[], callback: Function): void 1471 1472数据分批写出接口是一个由使用者实现的函数，在数据被写出时自动调用，而不需要用户手动调用。使用callback异步回调。 1473 1474**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1475 1476**系统能力：** SystemCapability.Utils.Lang 1477 1478**参数：** 1479 1480| 参数名 | 类型 | 必填 | 说明 | 1481| -------- | -------- | -------- | -------- | 1482| chunks | string[] \| Uint8Array[] | 是 | 被批量写出的数据数组。 | 1483| callback | Function | 是 | 回调函数。 | 1484 1485**错误码：** 1486 1487以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1488 1489| 错误码ID | 错误信息 | 1490| -------- | -------- | 1491| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1492 1493**示例：** 1494 1495```ts 1496class TestDuplex extends stream.Duplex { 1497 constructor() { 1498 super(); 1499 } 1500 1501 doRead(size: number) { 1502 } 1503 1504 doWrite(chunk: string | Uint8Array, encoding: string, callback: Function) { 1505 callback(); 1506 } 1507 1508 doWritev(chunks: string[] | Uint8Array[], callback: Function) { 1509 console.info("duplexStream chunk", chunks[0]); // duplexStream chunk data1 1510 callback(); 1511 } 1512} 1513 1514let duplexStream = new TestDuplex(); 1515duplexStream.cork(); 1516duplexStream.write('data1', 'utf8'); 1517duplexStream.write('data2', 'utf8'); 1518duplexStream.uncork(); 1519duplexStream.end(); 1520``` 1521 1522## Transform 1523 1524转换流是一个特殊的双工流，支持可读和可写能力的流，可以对数据进行转换并输出结果。Transform类继承[Duplex](#duplex)，支持Duplex中所有的方法。 1525 1526### constructor 1527 1528constructor() 1529 1530Transform的构造函数。 1531 1532**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1533 1534**系统能力：** SystemCapability.Utils.Lang 1535 1536**示例：** 1537 1538```ts 1539let transform = new stream.Transform(); 1540``` 1541 1542### doTransform 1543 1544doTransform(chunk: string, encoding: string, callback: Function): void 1545 1546对输入的数据块进行转换或处理，并通过回调函数通知操作完成。 1547 1548**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1549 1550**系统能力：** SystemCapability.Utils.Lang 1551 1552**参数：** 1553 1554| 参数名 | 类型 | 必填 | 说明 | 1555| -------- | -------- | -------- | -------- | 1556| chunk | string | 是 | 需要写入的数据。 | 1557| encoding | string | 是 | 字符编码类型。当前版本支持'utf8'、'gb18030'、'gbk'以及'gb2312'。 | 1558| callback | Function | 是 | 回调函数。 | 1559 1560**错误码：** 1561 1562以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1563 1564| 错误码ID | 错误信息 | 1565| -------- | -------- | 1566| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1567 1568**示例：** 1569 1570```ts 1571class TestTransform extends stream.Transform { 1572 constructor() { 1573 super(); 1574 } 1575 1576 doTransform(chunk: string, encoding: string, callback: Function) { 1577 let stringChunk = chunk.toString().toUpperCase(); 1578 console.info("Transform test doTransform", stringChunk); // Transform test doTransform HELLO 1579 this.push(stringChunk); 1580 callback(); 1581 } 1582} 1583 1584let tr = new TestTransform(); 1585tr.write("hello"); 1586``` 1587 1588### doFlush 1589 1590doFlush(callback: Function): void 1591 1592该函数会在流结束时被调用，用于处理剩余的数据。使用callback异步回调。 1593 1594**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。 1595 1596**系统能力：** SystemCapability.Utils.Lang 1597 1598**参数：** 1599 1600| 参数名 | 类型 | 必填 | 说明 | 1601| -------- | -------- | -------- | -------- | 1602| callback | Function | 是 | 回调函数。 | 1603 1604**错误码：** 1605 1606以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1607 1608| 错误码ID | 错误信息 | 1609| -------- | -------- | 1610| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 1611 1612**示例：** 1613 1614```ts 1615class TestTransform extends stream.Transform { 1616 constructor() { 1617 super(); 1618 } 1619 1620 doTransform(chunk: string, encoding: string, callback: Function) { 1621 callback(); 1622 } 1623 1624 doFlush(callback: Function) { 1625 callback(null, 'test'); 1626 } 1627} 1628 1629let transform = new TestTransform(); 1630transform.end('my test'); 1631transform.on('data', (data) => { 1632 console.info("data is", data.data); // data is test 1633}); 1634```