CanvasRenderingContext2D: lang-Eigenschaft

Wert

Die lang-Eigenschaft kann einen der folgenden String-Werte annehmen:

• Ein BCP 47-Sprachtag, der die Sprache des Canvas-Kontexts darstellt.
• Der String inherit, in welchem Fall die Sprache vom lang-Attribut des Ausgangs-<canvas>-Elements oder vom nächstgelegenen verfügbaren Vorfahren mit einem explizit gesetzten lang-Attribut geerbt wird.
• Ein leerer String (""), der gesetzt werden kann, um anzugeben, dass der Canvas-Kontext keine Sprache hat.

Der Standardwert ist inherit.

Beschreibung

Manchmal muss eine Sprache für einen Canvas-Zeichenkontext festgelegt werden, damit er weiß, wie sprachabhängige Merkmale zu rendern sind: Zum Beispiel haben einige Schriftarten bestimmte Zeichen, die in verschiedenen Sprachen unterschiedlich gerendert werden. Ein Bildschirm-Canvas-Kontxt (CanvasRenderingContext2D) ist immer mit einem bestimmten <canvas>-Element verknüpft und kann daher beim Rendern von Inhalten die Sprache aus dem Wert des lang-Attributs des <canvas>-Elements ableiten.

Ein Offscreen-Canvas-Kontext (OffscreenCanvasRenderingContext2D) hingegen rendert seinen Inhalt, bevor er mit einem <canvas>-Element verknüpft wird, sodass er die Rendersprache nicht aus dem lang-Attribut des <canvas>-Elements ableiten kann. Die lang-Eigenschaft adressiert dieses Problem, indem Sie eine Sprache direkt auf einem Canvas-Zeichenkontext setzen können, unabhängig davon, ob Sie einen Bildschirm- oder Offscreen-Canvas verwenden.

Der inherit-Wert

Wenn der inherit-Wert verwendet wird, wird die Sprache des Canvas-Kontexts vom lang-Attribut der nächstverfügbaren HTML-Quelle geerbt:

• Im Fall eines Bildschirmkontextes oder eines Offscreen-Kontextes, der von einem Bildschirmkontext übertragen wurde, ist dies das Ausgangs-<canvas>-Element, sofern es ein gültiges lang-Attribut gesetzt hat.
• Wenn ein lang-Attribut auf einem zugehörigen <canvas>-Element nicht verfügbar ist, was sowohl für Bildschirm- als auch Offscreen-Kontexte der Fall sein könnte, wird dies der nächstgelegene verfügbare Vorfahre mit einem explizit gesetzten lang sein, was üblicherweise die Dokumentwurzel ist.

Aufgrund technischer Einschränkungen verhält sich der inherit-Wert unterschiedlich für Bildschirm- und Offscreen-Canvas:

• Für Bildschirm-Canvas wird der lang-Wert des Kontexts geerbt, wenn das zugehörige CanvasRenderingContext2D-Objekt erstmals erstellt wird, und dynamisch aktualisiert, wenn das lang-Attribut des zugehörigen Canvas aktualisiert wird (entweder direkt oder durch Vererbung).
• Für Offscreen-Canvas wird der lang-Wert geerbt, wenn das zugehörige OffscreenCanvasRenderingContext2D-Objekt erstmals "als Schnappschuss" erstellt wird; nachfolgende Aktualisierungen des lang-Attributs, von dem der Offscreen-Kontext seinen Wert geerbt hat, ändern nicht dessen lang-Attribut. Aus diesem Grund kann die Sprache eines Offscreen-Canvas nur durch explizites Setzen seines lang-Wertes geändert werden.

Beispiele

Grundlegende Verwendung

const canvasElem = document.querySelector("canvas");
const ctx = canvasElem.getContext("2d");

// Get context language; returns "inherit" by default
console.log(ctx.lang);

// Set context language
ctx.lang = "en";
// Logs "en"
console.log(ctx.lang);

Demonstration der Lokalisierungsunterstützung für Canvas-Kontexte

In diesem Beispiel rendern wir einen Textstring in einem bestimmten Font in einen 2D-Canvas-Kontext, der sprachabhängige Ligaturen hat. Wir erlauben die Anpassung der Sprache des Canvas-Kontexts, damit Sie den Unterschied im Rendering sehen können.

HTML

Das HTML enthält ein <select>-Element, das Ihnen ermöglicht, eine Sprache auszuwählen — en (Englisch) oder tr (Türkisch) — und ein <canvas>-Element zum Rendern.

<p>
  <label for="lang">Choose language:</label>
  <select id="lang" name="lang">
    <option>en</option>
    <option>tr</option>
  </select>
</p>
<canvas></canvas>

JavaScript

Im JavaScript erfassen wir zuerst Verweise auf das <canvas>-Element, seinen CanvasRenderingContext2D und das <select>-Element, dann laden wir den sprachabhängigen Font mit der CSS-Font-Lade-API. Sobald der Font geladen ist, führen wir eine init()-Funktion aus. Diese Funktion definiert eine weitere Funktion — drawText(), die einige Texte in den Canvas-Kontext zeichnet, der den geladenen Font verwendet. Danach fügen wir einen change-Ereignislistener zum <select>-Element hinzu und rufen drawText() auf, damit der Text sofort in den Canvas gezeichnet wird, wenn die Seite das erste Mal geladen wird.

const canvasElem = document.querySelector("canvas");
const ctx = canvasElem.getContext("2d");

const selectElem = document.querySelector("select");

const latoMediumFontFace = new FontFace(
  // Lato-Medium is a font with language specific ligatures
  "Lato-Medium",
  'url("https://mdn.github.io/shared-assets/fonts/Lato-Medium.ttf")',
);

latoMediumFontFace.load().then((font) => {
  document.fonts.add(font);
  init();
});

function init() {
  function drawText() {
    ctx.clearRect(0, 0, canvasElem.width, canvasElem.height);
    ctx.font = "30px Lato-Medium";
    ctx.color = "black";
    ctx.fillText("finish crafting", 50, 100);
  }

  selectElem.addEventListener("change", () => {
    document.documentElement.lang = selectElem.value;
    drawText();
  });

  drawText();
}

Wenn der Wert des <select> geändert wird, wird die change-Ereignishandlerfunktion ausgelöst, die:

• Den Wert des lang-Attributs des <html>-Elements auf den Wert des <select>-Elements setzt und dadurch die Sprache des Dokuments effektiv ändert.
• Die drawText()-Funktion ausführt. Die CanvasRenderingContext2D.lang-Eigenschaft ist standardmäßig auf inherit gesetzt, daher erbt der Canvas-Kontext die Sprache des Dokuments.

Ergebnis

Das Beispiel wird wie folgt gerendert:

Versuchen Sie, die Dokumentensprache mit dem <select>-Element zu ändern. Wenn die Sprache auf Englisch gesetzt ist, wird die Schriftart mit der "fi" Ligatur gerendert. Wenn sie auf Türkisch gesetzt ist, wird die Schriftart ohne die "fi" Ligatur gerendert, da diese Lokalisierung sie nicht beinhaltet.

Sprachunterstützung für Offscreen-Canvas

Dieses Beispiel ähnelt dem vorherigen, mit der Ausnahme, dass die Schriftart in einem OffscreenCanvasRenderingContext2D gerendert wird, und das resultierende Bitmap auf das Bildschirm-<canvas> übertragen wird, um es anzuzeigen.

Außerdem, weil eine geerbte Offscreen-Canvas-Sprache nur einmal gesetzt wird und nicht dynamisch aktualisiert wird, wenn der geerbte lang-Attributswert geändert wird, setzen wir die lang-Eigenschaft explizit auf dem OffscreenCanvasRenderingContext2D.

HTML

<p>
  <label for="lang">Choose language:</label>
  <select id="lang" name="lang">
    <option>en</option>
    <option>tr</option>
  </select>
</p>
<canvas></canvas>

JavaScript

Das JavaScript funktioniert genauso wie im vorherigen Beispiel, mit der Ausnahme, dass:

• Der Bildschirm-Canvas-Kontext als ImageBitmapRenderingContext definiert ist.
• Wir einen neuen OffscreenCanvasRenderingContext2D definieren, um den Text darauf zu zeichnen, das Ergebnis mit transferToImageBitmap() in ein Bitmap konvertieren und dann mit transferFromImageBitmap() auf den <canvas> rendern.
• Wenn der Wert des <select> geändert wird, aktualisieren wir direkt die lang-Eigenschaft auf dem OffscreenCanvasRenderingContext2D anstelle des lang-Attributswertes im <html> zu ändern.

const canvasElem = document.querySelector("canvas");
const ctx = canvasElem.getContext("bitmaprenderer");

const offscreen = new OffscreenCanvas(canvasElem.width, canvasElem.height);
const offscreenCtx = offscreen.getContext("2d");

const selectElem = document.querySelector("select");

const latoMediumFontFace = new FontFace(
  // Lato-Medium is a font with language specific ligatures.
  "Lato-Medium",
  'url("https://mdn.github.io/shared-assets/fonts/Lato-Medium.ttf")',
);

latoMediumFontFace.load().then((font) => {
  document.fonts.add(font);
  init();
});

function init() {
  function drawText() {
    offscreenCtx.clearRect(0, 0, canvasElem.width, canvasElem.height);
    offscreenCtx.lang = selectElem.value;
    offscreenCtx.font = "30px Lato-Medium";
    offscreenCtx.color = "black";
    offscreenCtx.fillText("finish crafting", 50, 100);

    const bitmap = offscreen.transferToImageBitmap();
    ctx.transferFromImageBitmap(bitmap);
  }

  selectElem.addEventListener("change", () => {
    drawText();
  });

  drawText();
}

Ergebnis

Das Beispiel wird wie folgt gerendert:

Spezifikationen

Browser-Kompatibilität

Siehe auch

• CanvasRenderingContext2D
• Canvas Localization Support von Igalia (2025)