База знанияИзпитен център
BGБългарски
Избери език13

CKTIS / JavaScript

Приемник на WritableStream: start, write, close и abort

Четири незадължителни метода определят как потокът за запис подготвя приемника, записва части от данните, завършва нормално или освобождава ресурси след прекъсване.

Версия: ECMAScript 2024 and the current web platform; runtime support varies

Синтаксис

new WritableStream()
new WritableStream(underlyingSink)
new WritableStream(underlyingSink, queuingStrategy)

// Optional methods on underlyingSink:
const underlyingSink = {
  start(controller) { /* initialize the destination */ },
  write(chunk, controller) { /* write one chunk */ },
  close() { /* finalize successful output */ },
  abort(reason) { /* clean up after an abort request */ },
};

WritableStream е част от Web Streams API, а не от ECMAScript 2024; наличността зависи от средата за изпълнение. underlyingSink, първият незадължителен аргумент на конструктора, е обект с методи, които потокът извиква. Вторият незадължителен аргумент, queuingStrategy, определя как се измерва размерът на опашката за регулиране на темпото на запис (backpressure).

start(controller) се извиква веднъж при създаването. Синхронно изключение прекратява създаването; отхвърлен Promise поставя създадения поток в състояние на грешка. Потокът подава части от данните на приемника едва след успешно инициализиране. write(chunk, controller) обработва по една част в реда на подаването. Върни Promise, който отразява действителния асинхронен запис, за да може потокът да го изчака и да предаде евентуалните грешки.

close() не получава аргументи. След заявка за затваряне се извиква едва когато всички приети записи са завършили успешно. Използвай го, за да изпразниш буферите на приемника и да освободиш ресурси. abort(reason) служи за почистване след заявка за прекъсване; причината може да бъде произволна стойност в JavaScript. Незапочнатите записи се отхвърлят, но текущата операция не спира автоматично и завършените записи не се отменят. И двата метода могат да върнат Promise; не разчитай, че abort се извиква при всяка грешка или след затваряне.

start и write получават един и същ WritableStreamDefaultController. controller.signal позволява на текуща операция да реагира на заявка за прекъсване, ако тя поддържа отмяна. controller.error(error) съобщава за грешка в потока; това не е заявка за прекъсване и не замества почистването.

Кодът, който подава данните, извиква getWriter(), за да заключи потока за един обект за запис. Обработвай обектите Promise, върнати от writer.write(), writer.close() и writer.abort(); директните извиквания на stream.close() и stream.abort() връщат отхвърлени обекти Promise, докато потокът е заключен. writer.releaseLock() освобождава заключването, без да приключва потока.

Примери

(async () => {
  const log = [];
  const reason = new Error("stop");

  async function run(label, shouldAbort) {
    const stream = new WritableStream({
      start() {
        log.push(`${label}: start`);
      },
      async write(chunk) {
        await Promise.resolve();
        log.push(`${label}: write ${chunk}`);
      },
      close() {
        log.push(`${label}: close`);
      },
      abort(received) {
        log.push(`${label}: abort (${received === reason})`);
      },
    });

    const writer = stream.getWriter();
    try {
      await writer.write("A");
      if (shouldAbort) {
        await writer.abort(reason);
      } else {
        await writer.close();
      }
    } finally {
      writer.releaseLock();
    }
  }

  await run("normal", false);
  await run("interrupted", true);
  console.log(log.join("\n"));
})().catch(console.error);

Резултат

normal: start
normal: write A
normal: close
interrupted: start
interrupted: write A
interrupted: abort (true)

Примерът използва два отделни потока. И двата завършват записа на `A`; първият се затваря, а вторият се прекъсва. `true` показва, че приемникът е получил точно същия обект `Error`.

Свързани уроци

  • JavaScript · Урок 4 · Напреднало · Версия: 4

Източници