TaskController.setPriority() — Methode · JavaScript-Referenz

Signatur

TaskController.prototype.setPriority(priority)

Beschreibung

setPriority() gehört zur Prioritized Task Scheduling API. Ein TaskController besitzt ein TaskSignal (controller.signal), das du an scheduler.postTask() übergibst. Mit setPriority() änderst du nachträglich die Priorität aller noch nicht ausgeführten Aufgaben, die an dieses Signal gebunden sind. Der Scheduler ordnet sie dann in der passenden Prioritätswarteschlange neu ein.

Typische Anwendungsfälle: Ein Bild, das zunächst im Hintergrund dekodiert wird, rückt in den sichtbaren Bereich und soll jetzt schneller verarbeitet werden. Umgekehrt kann ein Tab, der in den Hintergrund wechselt, seine Aufgaben auf "background" herabstufen. So lässt sich die Reaktionsfähigkeit der Oberfläche steuern, ohne Aufgaben abbrechen und neu planen zu müssen.

Weicht die neue Priorität von der alten ab, löst das Signal ein prioritychange-Ereignis aus (ein TaskPriorityChangeEvent mit der Eigenschaft previousPriority). Setzt du dieselbe Priorität erneut, passiert nichts. Ein TaskController kann außerdem wie ein AbortController Aufgaben per abort() abbrechen, weil TaskController von AbortController erbt.

Parameter

Name	Typ	Default	Beschreibung
$priority Pflicht	"user-blocking" \| "user-visible" \| "background"		Die neue Priorität. `"user-blocking"` ist die höchste (für direkt wahrnehmbare Interaktionen), `"user-visible"` die Standardpriorität und `"background"` die niedrigste (für nicht zeitkritische Arbeit wie Logging oder Vorabladen).

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Änderung wirkt sich auf controller.signal.priority und die Reihenfolge der wartenden Aufgaben aus.

Beispiele

Priorität einer geplanten Aufgabe erhöhen

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

scheduler.postTask(() => {
  console.log('Aufgabe läuft mit Priorität:', controller.signal.priority);
}, { signal: controller.signal });

// Noch bevor die Aufgabe läuft: Priorität anheben
controller.setPriority('user-blocking');

Aufgabe läuft mit Priorität: user-blocking

Auf prioritychange reagieren

const controller = new TaskController();

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

controller.setPriority('background');
controller.setPriority('background'); // gleiche Priorität: kein Ereignis

Priorität geändert: user-visible → background

Bildverarbeitung je nach Sichtbarkeit priorisieren

const controller = new TaskController({ priority: 'background' });
const img = document.querySelector('#hero');

const processImage = async () => {
  const bitmap = await createImageBitmap(img);
  console.log('Bild verarbeitet:', bitmap.width, 'x', bitmap.height);
};

scheduler.postTask(processImage, { signal: controller.signal })
  .catch((err) => console.warn('Abgebrochen:', err.name));

const observer = new IntersectionObserver(([entry]) => {
  controller.setPriority(entry.isIntersecting ? 'user-visible' : 'background');
});
observer.observe(img);

Bild verarbeitet: 1200 x 800

Funktionsprüfung mit Rückfallebene

const runTask = (fn, priority = 'user-visible') => {
  if ('scheduler' in globalThis && 'TaskController' in globalThis) {
    const controller = new TaskController({ priority });
    scheduler.postTask(fn, { signal: controller.signal });
    return controller;
  }
  setTimeout(fn, 0); // Rückfall ohne Prioritäten
  return null;
};

const ctrl = runTask(() => console.log('erledigt'), 'background');
ctrl?.setPriority('user-blocking');

erledigt

// Wichtig · Fallstricke

NotAllowedError: Rufst du setPriority() auf, während bereits eine Prioritätsänderung läuft (zum Beispiel innerhalb eines prioritychange-Handlers desselben Signals), wird eine DOMException vom Typ NotAllowedError geworfen.
TypeError: Ungültige Werte wie 'high' werfen einen TypeError, weil nur die drei festgelegten Prioritätswerte erlaubt sind.
Die Priorität wirkt sich nur auf Aufgaben aus, die noch nicht gestartet sind. Eine bereits laufende Aufgabe wird nicht unterbrochen, auch nicht an einem await. Fortsetzungen nach await laufen als Microtasks und werden vom Scheduler nicht priorisiert.
Wurde der Aufgabe bei postTask() zusätzlich die Option priority übergeben, gilt diese feste Priorität und das Signal wird nur noch zum Abbrechen verwendet. setPriority() hat dann keinen Einfluss auf diese Aufgabe.
Kompatibilität: Verfügbar in Chromium-basierten Browsern ab Version 94 und in Firefox ab Version 142, Safari unterstützt die API nicht. Prüfe vorher mit 'TaskController' in globalThis, ob sie vorhanden ist, oder nutze ein Polyfill wie scheduler-polyfill. Die API steht auch in Web Workern zur Verfügung.

Siehe auch

XRCompositionLayer.destroy() AbortController.abort() console.error() console.profile() AudioListener.setPosition()