readable.read([size])

新增于: v0.9.4

readable.read() 方法从内部缓冲区中读取数据并返回。如果没有数据可以读取，则返回 null。默认情况下，除非使用 readable.setEncoding() 方法指定了编码或流在对象模式下运行，否则数据将作为 Buffer 对象返回。

¥The readable.read() method reads data out of the internal buffer and returns it. If no data is available to be read, null is returned. By default, the data is returned as a Buffer object unless an encoding has been specified using the readable.setEncoding() method or the stream is operating in object mode.

可选的 size 参数指定要读取的特定字节数。如果无法读取 size 个字节，则将返回 null，除非流已结束，在这种情况下，将返回内部缓冲区中剩余的所有数据。

¥The optional size argument specifies a specific number of bytes to read. If size bytes are not available to be read, null will be returned unless the stream has ended, in which case all of the data remaining in the internal buffer will be returned.

如果未指定 size 参数，则将返回内部缓冲区中包含的所有数据。

¥If the size argument is not specified, all of the data contained in the internal buffer will be returned.

size 参数必须小于或等于 1 GiB。

¥The size argument must be less than or equal to 1 GiB.

readable.read() 方法应该只在暂停模式下操作的 Readable 流上调用。在流动模式下，会自动调用 readable.read()，直到内部缓冲区完全排空。

¥The readable.read() method should only be called on Readable streams operating in paused mode. In flowing mode, readable.read() is called automatically until the internal buffer is fully drained.

const readable = getReadableStreamSomehow();

// 'readable' may be triggered multiple times as data is buffered in
readable.on('readable', () => {
  let chunk;
  console.log('Stream is readable (new data received in buffer)');
  // Use a loop to make sure we read all currently available data
  while (null !== (chunk = readable.read())) {
    console.log(`Read ${chunk.length} bytes of data...`);
  }
});

// 'end' will be triggered once when there is no more data available
readable.on('end', () => {
  console.log('Reached end of stream.');
});

每次调用 readable.read() 都会返回一个数据块或 null，表示此时没有更多数据可读取。这些块不会自动连接。由于单个 read() 调用不会返回所有数据，因此可能需要使用 while 循环来连续读取块，直到检索到所有数据。读取大文件时，.read() 可能会暂时返回 null，表示它已使用完所有缓冲内容，但可能还有更多数据需要缓冲。在这种情况下，一旦缓冲区中有更多数据，就会触发新的 'readable' 事件，而 'end' 事件表示数据传输结束。

¥Each call to readable.read() returns a chunk of data or null, signifying that there's no more data to read at that moment. These chunks aren't automatically concatenated. Because a single read() call does not return all the data, using a while loop may be necessary to continuously read chunks until all data is retrieved. When reading a large file, .read() might return null temporarily, indicating that it has consumed all buffered content but there may be more data yet to be buffered. In such cases, a new 'readable' event is emitted once there's more data in the buffer, and the 'end' event signifies the end of data transmission.

因此，要从 readable 读取文件的全部内容，必须跨越多个 'readable' 事件来收集块：

¥Therefore to read a file's whole contents from a readable, it is necessary to collect chunks across multiple 'readable' events:

const chunks = [];

readable.on('readable', () => {
  let chunk;
  while (null !== (chunk = readable.read())) {
    chunks.push(chunk);
  }
});

readable.on('end', () => {
  const content = chunks.join('');
});

对象模式下的 Readable 流将始终从对 readable.read(size) 的调用返回单个条目，而不管 size 参数的值如何。

¥A Readable stream in object mode will always return a single item from a call to readable.read(size), regardless of the value of the size argument.

如果 readable.read() 方法返回数据块，则还将触发 'data' 事件。

¥If the readable.read() method returns a chunk of data, a 'data' event will also be emitted.

在触发 'end' 事件后调用 stream.read([size]) 将返回 null。不会引发运行时错误。

¥Calling stream.read([size]) after the 'end' event has been emitted will return null. No runtime error will be raised.