CanvasRenderingContext2D.direction — Eigenschaft · JavaScript-Referenz

Signatur

CanvasRenderingContext2D.direction

Beschreibung

Die Eigenschaft direction des 2D-Kontexts bestimmt, in welcher Richtung Text auf dem Canvas gezeichnet wird. Das ist vor allem bei Schriften wichtig, die von rechts nach links laufen, etwa Arabisch oder Hebräisch, und bei gemischtem Text mit lateinischen und RTL-Zeichen. Wie Satzzeichen, Zahlen und neutrale Zeichen angeordnet werden, richtet sich nach dem Unicode-Bidi-Algorithmus und der hier eingestellten Grundrichtung.

Mögliche Werte:

"ltr": von links nach rechts.
"rtl": von rechts nach links.
"inherit" (Standard): Die Richtung wird vom <canvas>-Element oder vom Dokument übernommen, also z. B. aus dem Attribut dir oder der CSS-Eigenschaft direction. Bei einem OffscreenCanvas gilt ohne Element "ltr".

direction wirkt sich auch auf textAlign aus. Die logischen Werte "start" (Standard) und "end" hängen von der Richtung ab: Bei "rtl" bedeutet "start", dass der Text am x-Punkt rechts endet. Wer Text an einem festen Punkt verankert, muss deshalb beide Eigenschaften zusammen betrachten.

Die Eigenschaft gehört zum Zeichenzustand. save() und restore() sichern und stellen sie wieder her. Wenn sich die Canvas-Größe ändert, wird sie auf "inherit" zurückgesetzt.

Parameter

Name	Typ	Default	Beschreibung
$value	"ltr" \| "rtl" \| "inherit"	"inherit"	Der neue Wert beim Zuweisen. Ungültige Zeichenketten werden stillschweigend ignoriert, der bisherige Wert bleibt erhalten.

Rückgabewert

Typ

string

Beschreibung

Die aktuelle Textrichtung: "ltr", "rtl" oder "inherit". Wenn "inherit" gesetzt ist, liefert das Auslesen genau diesen Wert und nicht die tatsächlich berechnete Richtung.

Beispiele

LTR und RTL im Vergleich

const canvas = document.querySelector('#canvas');
const ctx = canvas.getContext('2d');
ctx.font = '24px sans-serif';

// Hilfslinie am Ankerpunkt x = 200
ctx.strokeStyle = 'red';
ctx.beginPath();
ctx.moveTo(200, 0);
ctx.lineTo(200, 120);
ctx.stroke();

ctx.direction = 'ltr';
ctx.fillText('Hallo Welt!', 200, 40);   // beginnt bei x=200 und läuft nach rechts

ctx.direction = 'rtl';
ctx.fillText('Hallo Welt!', 200, 90);   // endet bei x=200, das "!" steht links

console.log(ctx.direction);

rtl

Arabischen Text mit textAlign = "start" rechtsbündig ausrichten

const ctx = document.querySelector('#canvas').getContext('2d');
const padding = 16;

const drawLabel = (text, lang) => {
  ctx.save();
  ctx.font = '20px system-ui';
  ctx.textAlign = 'start';
  const isRtl = ['ar', 'he', 'fa'].includes(lang);
  ctx.direction = isRtl ? 'rtl' : 'ltr';
  // Bei rtl bedeutet "start" den rechten Rand
  const x = isRtl ? ctx.canvas.width - padding : padding;
  ctx.fillText(text, x, 40);
  ctx.restore();
};

drawLabel('مرحبا بالعالم', 'ar');
console.log(ctx.direction); // nach restore() wieder der Standardwert

inherit

Richtung vom Dokument übernehmen

// <html dir="rtl"> oder <canvas dir="rtl">
const canvas = document.createElement('canvas');
canvas.dir = 'rtl';
document.body.append(canvas);

const ctx = canvas.getContext('2d');
console.log(ctx.direction); // ausgelesen wird der gesetzte Wert, nicht der berechnete

// Die tatsächlich wirksame Richtung ermitteln:
const effective = getComputedStyle(canvas).direction;
console.log(effective);

// Ungültige Werte werden ignoriert
ctx.direction = 'rechts';
console.log(ctx.direction);

inherit rtl inherit

// Wichtig · Fallstricke

Kompatibilität: Chrome, Edge und Safari unterstützen die Eigenschaft seit Langem. Firefox erst seit Version 101. In älteren Firefox-Versionen hat das Zuweisen keine Wirkung. Zur Erkennung eignet sich 'direction' in CanvasRenderingContext2D.prototype.
Zusammenspiel mit textAlign: Der häufigste Fehler ist, dass RTL-Text scheinbar „aus dem Canvas rutscht“: Bei "rtl" und textAlign = "start" liegt der Text links vom x-Punkt. Wer die Ausrichtung unabhängig von der Richtung festlegen will, nimmt "left" oder "right".
"inherit" wird beim Auslesen nicht aufgelöst. Die wirksame Richtung bekommt man über getComputedStyle(canvas).direction.
Die Eigenschaft ordnet die Zeichen nicht einfach um. Sie legt die Grundrichtung für den Bidi-Algorithmus fest. Bei lateinischem Text ändern sich deshalb vor allem die Position der Satzzeichen und die Verankerung.
In einem OffscreenCanvas (z. B. in einem Worker) gibt es kein Element, von dem geerbt werden kann. "inherit" bedeutet dort "ltr".
Wenn canvas.width oder canvas.height geändert wird, wird der gesamte Kontextzustand zurückgesetzt, also auch direction.

Siehe auch

CanvasRenderingContext2D.textAlign CanvasRenderingContext2D.fillText() CanvasRenderingContext2D.strokeText() CanvasRenderingContext2D.font CanvasRenderingContext2D.textBaseline CanvasRenderingContext2D.measureText() CanvasRenderingContext2D