DelegatedInkTrailPresenter.updateInkTrailStartPoint() — Methode · JavaScript-Referenz

Signatur

DelegatedInkTrailPresenter.prototype.updateInkTrailStartPoint(event, style)

Beschreibung

updateInkTrailStartPoint() gehört zur Ink API und verringert die spürbare Verzögerung (Latenz) beim Zeichnen mit Stift, Maus oder Finger. Zwischen dem Zeitpunkt, an dem deine Anwendung einen Punkt auf das <canvas> zeichnet, und dem nächsten angezeigten Frame bewegt sich der Zeiger weiter. Dadurch „hinkt“ der Strich sichtbar hinter der Stiftspitze her.

Mit dieser Methode übergibst du das PointerEvent, das du im aktuellen Frame zuletzt selbst gezeichnet hast. Der Browser bzw. das Betriebssystem zeichnet dann direkt im Compositor eine kurze, vorläufige Spur von diesem Punkt bis zur tatsächlichen, aktuellen Zeigerposition. Diese „delegierte“ Tintenspur wird im nächsten Frame verworfen und durch deine eigene Zeichnung ersetzt. Sie dient also nur als visuelle Überbrückung.

Typischerweise rufst du die Methode in jedem pointermove-Handler auf, nachdem du die Linie bis zum Event gezeichnet hast. Farbe und Durchmesser in style sollten zu deinem eigenen Strich passen, sonst sieht man einen Bruch zwischen echter und vorläufiger Spur. Eine Instanz von DelegatedInkTrailPresenter bekommst du über navigator.ink.requestPresenter().

Parameter

Name	Typ	Default	Beschreibung
$event Pflicht	PointerEvent		Das vertrauenswürdige `PointerEvent` (`isTrusted === true`), das als letzter Punkt im aktuellen Frame gezeichnet wurde, meist aus einem `pointermove`-Handler.
$style Pflicht	{ color: string, diameter: number }		Aussehen der vorläufigen Spur: `color` ist ein gültiger CSS-Farbwert (z. B. `"#1e88e5"` oder `"rgb(0 0 0)"`), `diameter` ist die Strichstärke in CSS-Pixeln und muss größer als 0 sein.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Spur wird vom Browser als Nebeneffekt gezeichnet.

Beispiele

Presenter anfordern und Spur im pointermove aktualisieren

const canvas = document.querySelector('#zeichenflaeche');
const ctx = canvas.getContext('2d');
const stil = { color: '#1e88e5', diameter: 4 };

const presenter = await navigator.ink.requestPresenter({ presentationArea: canvas });

let letzterPunkt = null;

canvas.addEventListener('pointerdown', (e) => {
  letzterPunkt = { x: e.offsetX, y: e.offsetY };
});

canvas.addEventListener('pointermove', (e) => {
  if (!letzterPunkt) return;
  // Eigenen Strich bis zum aktuellen Event zeichnen
  ctx.strokeStyle = stil.color;
  ctx.lineWidth = stil.diameter;
  ctx.lineCap = 'round';
  ctx.beginPath();
  ctx.moveTo(letzterPunkt.x, letzterPunkt.y);
  ctx.lineTo(e.offsetX, e.offsetY);
  ctx.stroke();
  letzterPunkt = { x: e.offsetX, y: e.offsetY };

  // Browser zeichnet ab hier bis zur echten Stiftposition
  presenter.updateInkTrailStartPoint(e, stil);
});

canvas.addEventListener('pointerup', () => { letzterPunkt = null; });

Feature-Erkennung mit Fallback

const initInk = async (canvas) => {
  if (!('ink' in navigator) || !navigator.ink.requestPresenter) {
    console.log('Ink API nicht verfügbar – normales Zeichnen ohne Latenzverbesserung');
    return null;
  }
  const presenter = await navigator.ink.requestPresenter({ presentationArea: canvas });
  console.log('Presenter bereit:', presenter.presentationArea === canvas);
  return presenter;
};

const presenter = await initInk(document.querySelector('canvas'));

// Später im pointermove-Handler:
// presenter?.updateInkTrailStartPoint(event, { color: 'black', diameter: 2 });

Presenter bereit: true (in Chromium) Ink API nicht verfügbar – normales Zeichnen ohne Latenzverbesserung (in Firefox/Safari)

Coalesced Events: den letzten Teil-Event übergeben

canvas.addEventListener('pointermove', (e) => {
  const events = e.getCoalescedEvents?.() ?? [e];
  for (const teil of events) {
    zeichnePunkt(teil.offsetX, teil.offsetY); // eigene Zeichenfunktion
  }
  // Das zuletzt gezeichnete Event als Startpunkt angeben
  const letztes = events.at(-1) ?? e;
  try {
    presenter.updateInkTrailStartPoint(letztes, { color: 'rgb(20 20 20)', diameter: 3 });
  } catch (err) {
    console.warn('Tintenspur nicht möglich:', err.name);
  }
});

// Wichtig · Fallstricke

Experimentell: Die API gibt es nur in Chromium-Browsern (ab Version 94). Firefox und Safari unterstützen sie nicht, deshalb immer auf navigator.ink prüfen und eine Alternative ohne Latenzverbesserung vorsehen.
Nur vertrauenswürdige Events: Synthetische Events (z. B. mit new PointerEvent() erzeugt und per dispatchEvent() ausgelöst) haben isTrusted === false. Dann wird eine NotAllowedError-DOMException geworfen.
Ungültiger Stil: Eine nicht parsbare Farbe oder ein diameter kleiner oder gleich 0 führt zu einem TypeError.
Nur vorläufige Spur: Die delegierte Spur gibt es nur bis zum nächsten Frame. Deine Anwendung muss den Strich weiterhin selbst zeichnen, sonst verschwindet er.
Darstellung angleichen: Farbe und Stärke sollten zum eigenen Strich passen. Die Spur wird auf die presentationArea zugeschnitten (bzw. auf den Viewport, wenn keine angegeben wurde).
Übergib immer das Event, das du tatsächlich zuletzt gezeichnet hast. Bei getCoalescedEvents() ist das das letzte Teil-Event.

Siehe auch

Ink DOMMatrixReadOnly.transformPoint() DataTransferItem.getAsString() EditContext.updateCharacterBounds() Element.startViewTransition()