TaskSignal: prioritychange — Ereignis · JavaScript-Referenz

Signatur

taskSignal.addEventListener("prioritychange", handler)

Beschreibung

Das Ereignis prioritychange gehört zur Prioritized Task Scheduling API. Es wird an ein TaskSignal gesendet, nachdem sich dessen Priorität geändert hat. Meist geschieht das, weil der zugehörige TaskController setPriority() aufruft. Alle Aufgaben, die mit scheduler.postTask() und diesem Signal eingeplant wurden, werden dann mit der neuen Priorität ("user-blocking", "user-visible" oder "background") weiter ausgeführt.

Den Handler registriert man mit signal.addEventListener("prioritychange", handler) oder über die Eigenschaft signal.onprioritychange. Der Handler bekommt ein TaskPriorityChangeEvent. Dessen Eigenschaft previousPriority enthält die alte Priorität. Die neue Priorität liest man aus event.target.priority bzw. signal.priority.

Typische Anwendungen: UI-Zustände oder Protokolle aktualisieren, wenn eine Hintergrundaufgabe plötzlich dringend wird (z. B. weil der Nutzer einen Bereich öffnet). Oder abhängige Arbeit neu planen, wenn eine Aufgabe in den Hintergrund zurückgestuft wird. Auch Signale aus TaskSignal.any(signals, { priority: quellSignal }) übernehmen die Priorität des Quellsignals und senden dabei ebenfalls prioritychange.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"prioritychange"`.
$handler Pflicht	(event: TaskPriorityChangeEvent) => void		Rückruffunktion. Sie bekommt ein `TaskPriorityChangeEvent` mit der Eigenschaft `previousPriority` (`"user-blocking" \| "user-visible" \| "background"`).
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen wie `once` oder `signal`, mit denen sich der Listener automatisch wieder entfernen lässt.

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Der Handler bekommt ein TaskPriorityChangeEvent.

Beispiele

Prioritätswechsel mit addEventListener beobachten

const controller = new TaskController({ priority: 'background' });

controller.signal.addEventListener('prioritychange', (event) => {
  const vorher = event.previousPriority;
  const nachher = event.target.priority;
  console.log(`Priorität geändert: ${vorher} -> ${nachher}`);
});

controller.setPriority('user-blocking');

Priorität geändert: background -> user-blocking

Handler über die Eigenschaft onprioritychange setzen

const controller = new TaskController();

controller.signal.onprioritychange = (event) => {
  console.log('Alt:', event.previousPriority, '| Neu:', controller.signal.priority);
};

controller.setPriority('background');

// Handler wieder entfernen
controller.signal.onprioritychange = null;

Alt: user-visible | Neu: background

Hintergrundaufgabe bei Nutzerinteraktion hochstufen und Listener entfernen

if ('scheduler' in globalThis && 'TaskController' in globalThis) {
  const controller = new TaskController({ priority: 'background' });

  const onChange = (event) => {
    console.log(`Vorschau-Aufgabe jetzt "${event.target.priority}" (vorher "${event.previousPriority}")`);
  };
  controller.signal.addEventListener('prioritychange', onChange);

  const aufgabe = scheduler.postTask(() => {
    return 'Vorschau berechnet';
  }, { signal: controller.signal });

  // Nutzer öffnet die Vorschau -> Aufgabe wird dringend
  controller.setPriority('user-blocking');

  const ergebnis = await aufgabe;
  console.log(ergebnis);

  controller.signal.removeEventListener('prioritychange', onChange);
} else {
  console.log('Prioritized Task Scheduling API nicht verfügbar');
}

Vorschau-Aufgabe jetzt "user-blocking" (vorher "background") Vorschau berechnet

// Wichtig · Fallstricke

Browser-Unterstützung: In Chromium-Browsern ab Version 94 vorhanden, in Firefox erst in neueren Versionen. Safari unterstützt es nicht. Deshalb vorher mit 'TaskController' in globalThis prüfen, ob die API verfügbar ist.
Wird setPriority() mit der gleichen Priorität aufgerufen, die schon gilt, wird kein Ereignis gesendet.
Wer setPriority() innerhalb eines prioritychange-Handlers für dasselbe Signal aufruft, bekommt eine DOMException vom Typ NotAllowedError. Rekursive Prioritätswechsel sind also nicht möglich.
Das Ereignis wird synchron während setPriority() gesendet. Beim Aufruf des Handlers ist signal.priority bereits auf den neuen Wert gesetzt. Die alte Priorität steht nur in event.previousPriority.
Ein TaskSignal ohne zugehörigen TaskController (z. B. AbortSignal oder ein festes Prioritäts-Signal) sendet dieses Ereignis nie.
Das Abbrechen über controller.abort() löst abort aus, nicht prioritychange.

Siehe auch

XRSession: visibilitychange Document: visibilitychange XRSystem: devicechange AbortSignal: abort CookieStore: change