In einem WebIDL-Dokument enthaltene Informationen

Wo Sie WebIDL-Dokumente finden

WebIDL kann an mehreren Orten gefunden werden:

• Jede Spezifikation enthält WebIDL im Text: Es ist eine sehr bequeme Möglichkeit, präzise Definitionen zu übermitteln. Diese beschreiben die Syntax der API. Obwohl es die kanonische Referenz ist, müssen wir beachten, dass sie von der tatsächlichen Implementierung abweichen kann. Auf MDN möchten wir praktisch sein und dokumentieren, was die Webplattform wirklich ist, und nicht, was sie idealerweise sein sollte. Überprüfen Sie daher, was da ist, mit den Implementierungen (und zögern Sie nicht, Fehler zu melden, wenn Sie Ungereimtheiten entdecken).
• Drei Browser-Engines verwenden (modifiziertes) WebIDL als Bestandteil ihrer Toolchain: Gecko, Chromium/Blink und WebCore/WebKit. Edge-Versionen vor Chromium verwendeten es intern, aber diese sind leider nicht öffentlich.
  • Für Gecko sind alle WebIDL-Dokumente in einem Verzeichnis zusammengefasst: https://searchfox.org/firefox-main/source/dom/webidl/. Ihre Erweiterung ist .webidl. Es gibt andere *.idl-Dateien im Gecko-Quellbaum, aber diese sind nicht WebIDL, sodass Sie sie ignorieren können. Ältere Versionen von Gecko haben einige ihrer WebIDL-Dokumente verstreut, und verwenden möglicherweise sogar Mozilla's IDL anstelle von WebIDL, um einige Web-Schnittstellen zu beschreiben, aber dies wird in jedem aktuellen Gecko-Code kein Problem darstellen.
  • Für Chromium sind sie an zwei Standorten innerhalb der Unterbäume des Source-Codes renderer/ Verzeichnisses zu finden: core/ und modules/. Im Chromium-Quellcode gibt es auch IDL-Dokumente an anderen Orten, aber diese sind Teil des Testsystems und nicht relevant für API-Implementierungen.
  • Für WebCore sind sie im Quellcode verstreut, also müssen Sie etwas mehr graben: z.B. https://github.com/WebKit/webkit/blob/main/Source/WebCore/html/DOMTokenList.idl

Unterschiedliche Dialekte von WebIDL

WebIDL ist in ihrer Spezifikation definiert. Sie wurde jedoch so gestaltet, dass sie erweitert werden kann, um mehr Informationen zu vermitteln, und Browseranbieter haben dies getan:

• Für Gecko hat Mozilla die Dokumentation ihres dialektalen WebIDLs erstellt.
• Für Chromium hat Google ebenfalls ein Dokument erstellt, um seine Erweiterungen zu beschreiben.
• Für WebCore hat Apple ebenfalls eine Seite für seinen Dialekt verfügbar gemacht.

Schnittstellen

Dieser Abschnitt erklärt die WebIDL-Syntax, die allgemeine API-Funktionen beschreibt.

Name der Schnittstelle

Der Name der Schnittstelle ist der String, der nach dem Schlüsselwort interface und vor der nächsten öffnenden geschweiften Klammer ('{') oder dem Doppelpunkt (':') erscheint.

interface URL {};

Jede WebIDL-Schnittstelle, ob es sich um eine echte Schnittstelle oder ein Mixin handelt, hat eine eigene Seite in der Dokumentation, die jeden Konstruktor, jede Eigenschaft und jede Methodik auflistet, die dafür definiert sind.

Vererbungskette

Das Elternteil, falls vorhanden, einer gegebenen Schnittstelle wird nach dem Schnittstellennamen und hinter einem Doppelpunkt (':') definiert. Es kann nur ein Elternteil pro Schnittstelle geben.

interface HTMLMediaElement : HTMLElement {…}

Die Vererbungskette wird automatisch in der Seitenleiste aufgelistet (unter Verwendung des {{APIRef}}-Makros). Es kann auch als SVG-Bild über das Makro {{InheritanceDiagram}} hinzugefügt werden.

Mixins

Einige Eigenschaften oder Methoden sind für mehrere Schnittstellen verfügbar. Um eine erneute Definition zu verhindern, werden sie in speziellen WebIDL-Schnittstellen, den sogenannten Mixins, definiert.

Seit September 2019 wurde die Mixin-Syntax aktualisiert. In der neuen Syntax verwenden Sie interface mixin, um eine Mixin-Schnittstelle zu definieren:

interface MyInterface {};

interface mixin MyMixin {
  void somethingMixedIn();
}

Dann verwenden Sie das Schlüsselwort includes, um zu sagen, dass die in einem Mixin definierten Eigenschaften in einer Schnittstelle verfügbar sind:

MyInterface includes MyMixin;

Mixins haben keine Vererbung und können keine anderen Mixins enthalten. Sie unterstützen jedoch Partials, sodass Sie Dinge wie dieses sehen werden:

interface MyInterface {};
interface mixin MyMixin {};

partial interface mixin MyMixin {
  void somethingMixedIn();
};

MyInterface includes MyMixin;

Für Dokumentationszwecke verbirgt MDN Mixins. Sie sind abstrakte und ausschließlich in der Spezifikation vorkommende Konstrukte. Sie können sie nicht in der Browser-Konsole sehen, und es ist nützlicher zu wissen, auf welchen realen Schnittstellen Methoden und Eigenschaften implementiert sind.

Wenn Sie ein Mixin im IDL begegnen, wie HTMLHyperlinkElementUtils, suchen Sie nach den Schnittstellen, die das Mixin implementieren, z.B. HTMLAnchorElement, und dokumentieren Sie die Mixin-Mitglieder direkt auf diesen Schnittstellen.

In der Praxis bedeutet dies, dass anstelle der Dokumentation von HTMLHyperlinkElementUtils, die Dokumentation zu den konkreten Schnittstellen hinzugefügt wird, wie HTMLAnchorElement und HTMLAreaElement.

Siehe die folgenden zwei Seiten, die HTMLHyperlinkElementUtils.hash entsprechend dokumentieren:

• HTMLAnchorElement.hash
• HTMLAreaElement.hash

Für Kompatibilitätsdaten konsultieren Sie die Datenrichtlinie für Mixins in BCD.

Alte Mixin-Syntax

In der alten WebIDL-Mixin-Syntax, die Sie noch an einigen Stellen antreffen könnten, sind Mixins durch die Verwendung der Annotation [NoInterfaceObject] gekennzeichnet:

[NoInterfaceObject]
   interface MyMixin {…}

In der alten Syntax werden Mixins, die in einer Schnittstelle implementiert sind, durch das Schlüsselwort implements definiert.

MyInterface implements MyMixin;

Verfügbarkeit in Fenster und Workern

Die Verfügbarkeit in Web-Workern (jedes Typs) und im Window-Scope wird durch eine Annotation definiert: [Exposed=(Window,Worker)]. Die Annotation gilt für das Partial Interface, mit dem sie aufgeführt ist.

[Exposed=(Window,Worker)]
interface Performance {
   [DependsOn=DeviceState, Affects=Nothing]
   DOMHighResTimeStamp now();
};

[Exposed=Window]
partial interface Performance {
   [Constant]
   readonly attribute PerformanceTiming timing;
   [Constant]
   readonly attribute PerformanceNavigation navigation;

   jsonifier;
};

In diesem Fall ist Performance.now() im Window-Scope und in jedem Worker verfügbar, während Performance.timing, Performance.navigation und Performance.toJSON() nicht für Web-Worker verfügbar sind.

Die häufigsten Werte für [Exposed] sind:

Window

Das Partial Interface ist im globalen Scope von Window verfügbar.

Worker

Das Partial Interface ist in jedem Art von Worker verfügbar, das heißt, wenn der globale Scope ein Nachfahre von WorkerGlobalScope ist — DedicatedWorkerGlobalScope, SharedWorkerGlobalScope, oder ServiceWorkerGlobalScope (es ist auch für ChromeWorker verfügbar, aber wir dokumentieren dies nicht, da sie nicht im Web sichtbar sind und intern für Firefox sind.)

DedicatedWorker

Das Partial Interface ist nur im DedicatedWorkerGlobalScope verfügbar.

SharedWorker

Das Partial Interface ist nur im SharedWorkerGlobalScope verfügbar.

ServiceWorker

Das Partial Interface ist nur im ServiceWorkerGlobalScope verfügbar.

Ein anderer Wert ist möglich, wie System, aber dies hat eine besondere Bedeutung, die nicht dokumentiert werden muss.

Beachten Sie, dass diese möglichen Werte selbst in WebIDL-Dokumenten definiert sind. Schnittstellen können eine [Global=xyz] Annotation haben. Das bedeutet, dass, wenn ein Objekt dieses Typs als globaler Scope verwendet wird, jede Schnittstelle, Eigenschaft oder Methode, die xyz als Wert in [Exposed] hat, verfügbar ist.

[Global=(Worker,DedicatedWorker), Exposed=DedicatedWorker]
interface DedicatedWorkerGlobalScope : WorkerGlobalScope {…}

Hier wird definiert, dass, wenn der globale Scope vom Typ DedicatedWorkerGlobalScope ist, das heißt, wenn wir in einem dedizierten Worker sind, jede Schnittstelle, Eigenschaft oder Methode, die – über die [Exposed] Annotation – an Worker oder DedicatedWorker verfügbar ist, verfügbar ist.

Präferenzen

In Gecko kann die Verfügbarkeit einer Partial Interface, einschließlich seines Konstruktors, seiner Eigenschaften und Methoden, durch eine Präferenz gesteuert werden (normalerweise als "pref" bezeichnet). Dies wird auch im WebIDL markiert.

[Pref="media.webspeech.synth.enabled"]
interface SpeechSynthesis {
   readonly attribute boolean pending;
   readonly attribute boolean speaking;
   readonly attribute boolean paused;
};

Hier steuert media.webspeech.synth.enabled die SpeechSynthesis-Schnittstelle und ihre Eigenschaften (das vollständige Listing hat mehr als 3).

Nur im Systemcode verfügbar

Einige Schnittstellenfunktionen sind möglicherweise nur im internen Systemcode des Browsers oder im Chrome-Code verfügbar. Um dies anzuzeigen, verwenden wir in Gecko [ChromeOnly], zum Beispiel die Eigenschaft propName im folgenden Beispiel ist nur über Chrome-Code aufrufbar:

interface MyInterface {
  [ChromeOnly]
  readonly attribute PropValue propName;
};

Eigenschaften

Sie erkennen die Definition einer Eigenschaft an der Verwendung des attribute-Schlüsselworts.

Name der Eigenschaft

readonly attribute MediaError? error;

Im obigen Beispiel ist der Name der Eigenschaft error; in der Dokumentation beziehen wir uns darauf als HTMLMediaElement.error, da es zur HTMLMediaElement-Schnittstelle gehört. Das Verlinken zur Seite erfolgt entweder mit dem Schnittstellenpräfix mit {{domxref('HTMLMediaElement.error')}} oder ohne das Präfix mit {{domxref('HTMLMediaElement.error', 'error')}} wenn der Kontext offensichtlich und eindeutig ist.

Typ der Eigenschaft

readonly attribute MediaError? error;

Der Eigenschaftswert ist ein Objekt vom Typ MediaError. Das Fragezeichen ('?') gibt an, dass es den Wert null haben kann, und die Dokumentation muss wann dies auftreten kann, erklären. Wenn kein Fragezeichen vorhanden ist, kann die error-Eigenschaft nicht null sein.

Der Typ der Eigenschaft kann mit einem erweiterten Attribut vorangestellt sein, ein in eckigen Klammern eingeschlossener String (wie [LegacyNullToEmptyString]). Solche erweiterten Attribute weisen auf spezielle Verhaltensweisen hin, die in der Prosa beschrieben werden müssen. Hier ist eine Liste standardmäßiger erweiterter Attributtypen und der Ergänzungen, die gemacht werden müssen:

[LegacyNullToEmptyString]

Der null-Wert wird auf eine nicht standardmäßige Weise in einen String konvertiert. Der Standardweg besteht darin, ihn in den String "null" zu konvertieren, aber in diesem Fall wird er in "" konvertiert.

Fügen Sie am Ende des Wert-Abschnitts des Artikels den folgenden Satz hinzu:

Wenn auf den null-Wert gesetzt, wird dieser null-Wert in den leeren String ("") konvertiert, also ist elt.innerHTML = null gleichbedeutend mit elt.innerHTML = "".

Das kleine Inline-Beispiel muss für jede Eigenschaft angepasst werden.

Schreibrechte an der Eigenschaft

readonly attribute MediaError? error;

Wenn das Schlüsselwort readonly vorhanden ist, kann die Eigenschaft nicht verändert werden. Dies muss markiert werden als:

• In der Schnittstelle, indem das {{ReadOnlyInline}}-Makro neben dessen Definitionsterm hinzugefügt wird.
• Im ersten Satz seiner eigenen Seite, indem die Beschreibung mit: Die schreibgeschützte HTMLMediaElement.error-Eigenschaft… beginnt.
• Indem die Beschreibung auf der Schnittstellenseite mit Gibt zurück… beginnt.

Einige Eigenschaften haben die [PutForwards=xyz] Annotation. Dies bedeutet, dass die Eigenschaft ein Verweis auf ein anderes Objekt ist, und wenn ein neuer Wert zugewiesen wird, wird die Zuweisung an die xyz-Eigenschaft des referenzierten Objekts weitergeleitet.

Fügen Sie am Ende des Wert-Abschnitts des Artikels einen ähnlichen Absatz hinzu:

Obwohl die style-Eigenschaft an sich schreibgeschützt ist, insofern als Sie das CSSStyleDeclaration-Objekt nicht ersetzen können, können Sie trotzdem direkt der style-Eigenschaft einen Wert zuweisen, was dem Zuweisen an die cssText-Eigenschaft entspricht. Sie können das CSSStyleDeclaration-Objekt auch mit den Methoden setProperty() und removeProperty() ändern.

Auslösende Ausnahmen

[SetterThrows]
            attribute DOMString src;

In einigen Fällen, zum Beispiel wenn einige Werte illegal sind, kann das Setzen eines neuen Werts dazu führen, dass eine Ausnahme ausgelöst wird. Dies wird mit der [SetterThrows]-Annotation markiert. Wenn dies geschieht, muss der Syntaxabschnitt der Eigenschaftsseite einen Abschnitt für Ausnahmen enthalten. Die Liste der Ausnahmen und die Bedingungen, unter denen sie ausgelöst werden, sind als textliche Informationen in der Spezifikation dieser API aufgeführt.

Beachten Sie, dass einige Ausnahmen nicht explizit markiert sind, sondern durch die JavaScript-Bindungen definiert werden. Der Versuch, einen illegalen Enumerationswert (gemappt auf einen JavaScript String) zu setzen, führt zu einer TypeError-Ausnahme. Dies muss dokumentiert werden, ist jedoch nur implizit im WebIDL-Dokument markiert.

Es ist unüblich, dass Getter Ausnahmen auslösen, obwohl dies in einigen Fällen vorkommt. In diesem Fall wird die [GetterThrows]-Annotation verwendet. Auch hier muss der Syntaxabschnitt der Eigenschaftsseite einen Abschnitt für Ausnahmen haben.

partial interface Blob {
  [GetterThrows]
  readonly attribute unsigned long long size;
};

Keine Ausnahmen auslösen

Wenn die Bedeutung von WebIDL nicht befolgt wird, wird oft eine Ausnahme ausgelöst, selbst ohne [SetterThrows] oder [GetterThrows] gesetzt. Zum Beispiel, wenn wir im strikten Modus versuchen, einer schreibgeschützten Eigenschaft einen neuen Wert zuzuweisen, das heißt ihren impliziten Setter aufzurufen, wird eine schreibgeschützte Eigenschaft im strikten Modus eine Ausnahme auslösen.

Meist aus Kompatibilitätsgründen ist dieses Verhalten manchmal ärgerlich. Um dies durch Erstellen eines No-Op-Setters zu verhindern (das heißt, indem jeder Versuch, die Eigenschaft auf einen neuen Wert zu setzen, stillschweigend ignoriert wird), kann die [LenientSetter]-Annotation verwendet werden.

partial interface Document {
  [LenientSetter]
  readonly attribute boolean fullscreen;
  [LenientSetter]
  readonly attribute boolean fullscreenEnabled;
};

In diesen Fällen wird dem Beschreibungstext der Eigenschaft ein zusätzlicher Satz hinzugefügt, z.B.:

Obwohl diese Eigenschaft schreibgeschützt ist, wird keine Ausnahme ausgelöst, wenn sie geändert wird (auch im strikten Modus); der Setter ist eine No-Operation und wird ignoriert.

Neue Objekte oder Referenzen

Der Rückgabewert einer Eigenschaft kann entweder eine Kopie eines internen Objekts, ein neu erstelltes synthetisches Objekt oder eine Referenz auf ein internes Objekt sein.

Basise Objekte mit Typen wie String (ein IDL DOMString, oder andere), Number (ein IDL byte, octet, unsigned int, oder andere), und Boolean werden immer kopiert und es muss darüber nichts Besonderes gesagt werden (dies ist das natürliche Verhalten, das von einem JavaScript-Entwickler erwartet wird).

Für Schnittstellenobjekte ist der Standard, eine Referenz auf das interne Objekt zurückzugeben. Dies muss sowohl in der kurzen Beschreibung auf der Schnittstellenseite als auch in der Beschreibung auf den spezifischen Unterseiten angegeben werden.

Manchmal muss eine API ein neues Objekt oder eine Kopie eines internen Objekts zurückgeben. Dieser Fall wird im WebIDL durch die [NewObject]-Annotation angezeigt.

[NewObject]
   readonly attribute TimeRanges buffered;

In diesem Fall gibt jeder Aufruf von buffered ein anderes Objekt zurück: Die Änderung beeinflusst nicht den internen Wert, und eine Änderung des internen Werts wird sich nicht auf jedes Objektinstanz auswirken. In der Dokumentation werden wir dies markieren, indem wir das Adjektiv neu neben dem Objekt verwenden:

Die schreibgeschützte Eigenschaft HTMLMediaElement.buffered gibt ein neues {{domxref("TimeRanges")}}-Objekt zurück, das…

und

{{domxref("HTMLMediaElement.buffered")}}{{ReadOnlyInline}}

Gibt ein neues {{domxref("TimeRanges")}}-Objekt zurück, das …

Im Fall einer Referenz auf ein Sammlung-Objekt (wie HTMLCollection, HTMLFormElementsCollection, oder HTMLOptionsCollection, immer ohne [NewObject]), machen wir es explizit, dass Änderungen am zugrunde liegenden Objekt über die zurückgegebene Referenz verfügbar sein werden. Um dies zu kennzeichnen, qualifizieren wir die Sammlung als live HTMLCollection (oder HTMLFormElementsCollections, oder HTMLOptionsCollection), sowohl in der Schnittstellenbeschreibung als auch in der Unterseite.

Zum Beispiel:

{{domxref("HTMLFormElement.elements")}}{{ReadOnlyInline}}

Gibt eine live {{domxref("HTMLFormControlsCollection")}} zurück, die…

Verfügbarkeit in Workern

Die Verfügbarkeit einzelner Eigenschaften in Workern wird ebenfalls im WebIDL angegeben. Für eine Eigenschaft ist der Standard die gleiche Verfügbarkeit wie die Schnittstelle (das heißt, nur im Window-Kontext verfügbar, wenn nichts Besonderes markiert ist) oder wie das partial interface, in dem sie definiert ist.

Für die Dokumentation muss die Unterseite einen Satz enthalten, der angibt, ob sie in Web-Workern verfügbar ist oder nicht, direkt vor dem Abschnitt "Syntax".

Präferenzen

In Gecko kann die Verfügbarkeit einiger Eigenschaften durch eine Präferenz gesteuert werden. Dies wird auch im WebIDL markiert.

[Pref="media.webvtt.enabled"]
    readonly attribute TextTrackList? textTracks;

Hier steuert media.webvtt.enabled die Eigenschaft textTracks.

Methoden

Sie erkennen die Definition einer Methode an den Klammern nach dem Namen.

Name der Methode

DOMString canPlayType(DOMString type);

Der Name der Methode ist canPlayType, und wir werden uns darauf als HTMLMediaElement.canPlayType() (mit den Klammern, die darauf hinweisen, dass es sich um eine Methode handelt) in der Dokumentation beziehen, da sie zur HTMLMediaElement-Schnittstelle gehört. Das Verlinken zur Seite erfolgt entweder mit dem Schnittstellenpräfix mit {{domxref('HTMLMediaElement.canPlayType()')}}, oder ohne das Präfix mit {{domxref('HTMLMediaElement.canPlayType', 'canPlayType()')}} wenn der Kontext offensichtlich und eindeutig ist. Die Klammern sollten immer enthalten sein.

Parameter

TextTrack addTextTrack(TextTrackKind kind,
                       optional DOMString label = "",
                       optional DOMString language = "");

Die Parameter einer Methode sind im Abschnitt Syntax der Unterseite der Methode aufgelistet. Sie sind im WebIDL der Reihenfolge nach aufgeführt, zwischen den Klammern, als durch Komma getrennte Liste. Jeder Parameter hat einen Namen (oben angegeben) und einen Typ (z.B. ein '?' bedeutet, dass der null-Wert gültig ist). Wenn als optional markiert, ist der Parameter optional, in einem Methodenaufruf enthalten zu sein und muss das {{optional_inline}}-Flag enthalten, wenn er im Syntaxabschnitt aufgeführt ist. Der Standardwert des Parameters ist nach dem Gleichheitszeichen ('=') aufgelistet.

Parametertypen können spezielles Verhalten haben, das mit erweiterten Attributen beschrieben wird (wie [LegacyNullToEmptyString]). Hier ist die Liste solcher Attribute und die Ergänzung, die Sie in der Prosa vornehmen müssen:

[LegacyNullToEmptyString]

Fügen Sie am Ende der Parameterbeschreibung folgenden Satz hinzu: Ein null-Wert wird als leerer String ("") behandelt.

Typ des Rückgabewertes

DOMString canPlayType(DOMString type);

Der Typ des Rückgabewertes wird vor dem Methodennamen angegeben — im obigen Fall ist der Wert ein Objekt des Typs DOMString. Wenn der Rückgabetyp von einem Fragezeichen ('?') gefolgt wird, kann auch ein Wert von null zurückgegeben werden, und die Dokumentation muss wann dies geschehen kann, erklären. Wenn kein Fragezeichen vorhanden ist, wie hier, kann der Rückgabewert nicht null sein.

Wenn der Rückgabewert das Schlüsselwort void ist, bedeutet das, dass es keinen Rückgabewert gibt. Es ist kein Rückgabewerttyp. Wenn der WebIDL-Eintrag void liest, sollte der Abschnitt Rückgabewert in den Dokumenten einfach "None ({{jsxref("undefined")}})." angeben.

Auslösende Ausnahmen

[Throws]
   void fastSeek(double time);

Einige Methoden können Ausnahmen auslösen. Dies wird durch die [Throws]-Annotation markiert. Wenn dies geschieht, muss der Syntaxabschnitt der Methodenseite einen Abschnitt für Ausnahmen haben. Die Liste der Ausnahmen und die Bedingungen, unter denen sie ausgelöst werden, sind als textliche Informationen in der Spezifikation dieser API aufgeführt.

Beachten Sie, dass einige Ausnahmen nicht explizit markiert sind, sondern durch die JavaScript-Bindungen definiert werden. Der Versuch, einen illegalen Enumerationswert (gemappt auf einen JavaScript String) als Parameter zu setzen, führt zu einer TypeError-Ausnahme. Dies muss dokumentiert werden, ist jedoch nur implizit im WebIDL-Dokument markiert.

Sehen Sie sich einen dieser Exceptions sections.

Verfügbarkeit in Workern

Die Verfügbarkeit einzelner Methoden in Workern wird ebenfalls im WebIDL angegeben. Für eine Methode ist der Standard die gleiche Verfügbarkeit wie die Schnittstelle (das heißt, nur im Window-Kontext verfügbar, wenn nichts Besonderes markiert ist) oder wie das partial interface, in dem sie definiert ist.

Für die Dokumentation muss die Unterseite einen Satz enthalten, der angibt, ob sie in Web-Workern verfügbar ist oder nicht, direkt vor dem Abschnitt "Syntax".

Präferenzen

In Gezcko kann die Verfügbarkeit einiger Methoden durch eine Präferenz gesteuert werden. Dies wird auch im WebIDL markiert.

[Pref="media.webvtt.enabled"]
   TextTrack addTextTrack(TextTrackKind kind,
                          optional DOMString label = "",
                          optional DOMString language = "");

Hier steuert media.webvtt.enabled die Methode addTextTrack().

Besondere Methoden

Einige Methoden werden nicht als reguläre Methoden im WebIDL aufgelistet, sondern als spezielle Schlüsselwörter, die in bestimmte Standard-JavaScript-Methoden übersetzt werden.

toString() und toJSON()

Ein Stringifier gibt an, wie ein auf einer Schnittstelle basierendes Objekt in Kontexten aufgelöst wird, die einen String erwarten. (Siehe den Abschnitt Stringifizierer.) Zusätzlich wird das Schlüsselwort auf toString() abgebildet und definiert als:

stringifier;

Die toString()-Methode wird genauso aufgelistet wie jede andere Methode der Schnittstelle und hat ihre eigene Unterseite (z.B. Range.toString())

Ein Jsonifier wird auf toJSON() abgebildet und definiert als:

jsonifier; // Gecko version
serializer; // Standard version

Die toJSON()-Methode wird genauso wie jede andere Methode der Schnittstelle aufgelistet und hat ihre eigene Unterseite (z.B. Performance.toJSON())

Iterator-ähnliche Methoden

Eine Schnittstelle kann als iterierbar definiert werden, was bedeutet, dass sie die folgenden Methoden haben wird: entries(), keys(), values() und forEach(). Sie unterstützt auch den Einsatz von for...of auf einem Objekt, das diese Schnittstelle implementiert.

Es gibt zwei Arten von Iterationen: den Werte-Iterator und den Paar-Iterator.

Werte-Iterator

iterable<valueType>

Der Iterator wird über Werte vom Typ valueType iterieren. Die generierten Methoden werden sein:

• entries(), die einen iterator auf den Indizes (die unsigned long sind) zurückgibt.
• values(), die einen iterator auf den Werten zurückgibt.
• keys(), die einen iterator auf den Schlüsseln, die seine Indizes sind (die unsigned long sind), zurückgibt. Im Fall von Werte-Iteratoren sind keys() und entries() identisch.
• forEach(), die eine gegebene Rückruffunktion einmal für jeden Eintrag in der Liste ausführt.

Ein solcher Iterator erlaubt es, die Syntax for (const p in object) als Kurzform für for (const p in object.entries()) zu verwenden. Wir fügen einen Satz darüber in die Schnittstellenbeschreibung ein.

Die Werte, die durchlaufen werden sollen, können auf eine der folgenden Arten definiert werden:

• Im WebIDL-Dokument, unter Verwendung der Notation iterable<valueType>. Zum Beispiel siehe DOMTokenList.
• Implizit im WebIDL-Dokument, wenn die Schnittstelle indizierte Eigenschaften unterstützt. Dies wird angezeigt, wenn die Schnittstelle getter-Methoden mit einem Parameter vom Typ unsigned long enthält.
• Außerhalb des WebIDL-Dokuments, in der Begleitprosa. Eine solche Prosa ist typischerweise in der Spezifikation zu finden und beginnt normalerweise mit: "Die Werte, die durchlaufen werden sollen…".

Paar-Iterator

iterable<keyType, valueType>

Der Iterator wird über Werte vom Typ valueType mit Schlüsseln vom Typ keyType iterieren, das heißt, die Wertepaare. Die generierten Methoden werden sein:

• entries(), die einen iterator auf die Wertepaare zurückgibt. Zum Beispiel siehe FormData.entries().
• values(), die einen iterator auf die Werte zurückgibt. Zum Beispiel siehe FormData.values().
• keys(), die einen iterator auf die Schlüssel zurückgibt. Zum Beispiel siehe FormData.keys().
• forEach(), die eine gegebene Rückrufunktion einmal für jeden Eintrag in der Liste ausführt. Zum Beispiel siehe Headers.forEach().

Ein solcher Iterator erlaubt es, die Syntax for (const p in object) als Kurzform für for (const p in object.entries()) zu verwenden. Wir fügen einen Satz darüber in die Schnittstellenbeschreibung ein. Zum Beispiel FormData.

Die Wertepaare, die durchlaufen werden sollen, können auf eine der folgenden Arten definiert werden:

• Im WebIDL-Dokument, unter Verwendung der Notation iterable<keyType, valueType>. Zum Beispiel siehe FormData.
• Außerhalb des WebIDL-Dokuments, in der Begleitprosa. Eine solche Prosa ist typischerweise in der Spezifikation zu finden und beginnt normalerweise mit: "Die Wertepaare, die durchlaufen werden sollen…".

Set-ähnliche Methoden

Eine Schnittstelle kann als Set-ähnlich definiert werden, was bedeutet, dass sie eine geordnete Menge von Werten darstellt und die folgenden Methoden haben wird: entries(), keys(), values(), forEach(), has() (sie hat auch die size-Eigenschaft). Sie unterstützt auch den Einsatz von for...of auf einem Objekt, das diese Schnittstelle implementiert. Die Set-ähnliche kann mit readonly oder auch nicht versehen sein. Wenn nicht schreibgeschützt, werden die Methoden zum Ändern des Sets ebenfalls implementiert: add(), clear(), und delete().

setlike<valueType>

Die generierten Eigenschaften werden sein:

• entries(), das einen iterator auf die Indizes zurückgibt. Zum Beispiel siehe NodeList.entries().
• values(), das einen iterator auf die Werte zurückgibt. Zum Beispiel siehe NodeList.values().
• keys(), das einen iterator auf die Schlüssel zurückgibt. Zum Beispiel siehe NodeList.keys().
• forEach(), das eine gegebene Rückruffunktion einmal für jeden Eintrag in der Liste ausführt. Zum Beispiel siehe NodeList.forEach().

In Fällen, in denen die Set-ähnliche Deklaration nicht durch read-only vorangestellt ist, werden auch die folgenden Methoden generiert:

• add(), die einen Eintrag hinzufügt. Z.B. die .add()-Methode von FontFaceSet.
• clear(), die die Set-ähnliche Struktur leert. Z.B. die .clear()-Methode von FontFaceSet.
• delete(), die einen Eintrag entfernt. Z.B. die .delete()-Methode von FontFaceSet.

Eine solche Set-Schnittstelle erlaubt es auch, die Syntax for (const p in object) als Kurzform für for (const p in object.entries()) zu verwenden.

Besondere Verhaltensweisen

Einige IDL-Mitglieder weisen auf spezielle Verhaltensweisen hin, die auf den entsprechenden Seiten erwähnt werden sollten.

Stringifier

Zusätzlich zur Hinzufügung der toString()-Methode zu einer Schnittstelle, wie beschrieben in toString() und toJSON(), geben Stringifier auch an, dass eine Objektinstanz, wenn sie als String verwendet wird, einen anderen String als den Standard zurückgibt. (Der Standard ist normalerweise eine JSON-Darstellung des Objekts). Exakt wie dies geschieht, hängt davon ab, wie es im IDL spezifiziert wird. Unabhängig vom Wie sollte das nicht-Standardverhalten auf der Schnittstellenseite beschrieben werden.

Wenn das Schlüsselwort stringifier zusammen mit einem Attributnamen verwendet wird, hat das Referenzieren des Objektnamens die gleiche Auswirkung wie das Referenzieren des Attributnamens. Betrachten Sie das folgende IDL:

interface InterfaceIdentifier {
  stringifier attribute DOMString DOMString name;
};

Für eine Klasse basierend auf dieser Schnittstelle sind die folgenden Zeilen im Code äquivalent. Das Verhalten sollte auf der Eigenschaften-Seite und zusätzlich auf der Schnittstellenseite bemerkt werden.

console.log(interfaceIdentifier);
console.log(interfaceIdentifier.name);

Wenn das Schlüsselwort stringifier allein verwendet wird, kann ein Objekt der Schnittstelle wie oben verwendet werden, aber das Verhalten wird im Quellcode definiert.

interface InterfaceIdentifier {
  stringifier;
};

Um herauszufinden, was eine Schnittstellenreferenz tatsächlich tut, lesen Sie die Schnittstellenspezifikation oder experimentieren Sie mit der Schnittstelle, um ihre Ausgabe zu bestimmen.

Konstruktoren

Konstruktoren sind im WebIDL ein wenig versteckt: Sie werden als Annotationen der Hauptschnittstelle aufgeführt.

Unbenannte Konstruktoren

Dies ist der häufigste Fall für Konstruktoren. Der Konstruktor einer gegebenen Schnittstelle A kann als a = new A(parameters); verwendet werden.

[Constructor, Func="MessageChannel::Enabled",
  Exposed=(Window,Worker)]
    interface MessageChannel {…};

Ein Konstruktor mit der gleichen Schnittstelle wird durch die Constructor Annotation auf der Schnittstelle definiert. Es kann Klammern und eine Parameterliste geben oder nicht (wie im obigen Beispiel). Wir dokumentieren alle unbenannten Konstruktoren auf einer Unterseite – zum Beispiel wird das oben unter dem Slug Web/API/MessageChannel/MessageChannel und dem Titel MessageChannel() gegeben.

Ein weiteres Beispiel eines unbenannten Konstruktors, mit Parametern:

[Constructor(DOMString type, optional MessageEventInit eventInitDict),
 Exposed=(Window,Worker,System)]
   interface MessageEvent : Event {…};

Es kann auch mehrere unbenannte Konstruktoren geben, die sich durch ihre Parameterlisten unterscheiden. Die gesamte Syntax wird auf einer einzigen Unterseite dokumentiert.

[Constructor(DOMString url, URL base),
 Constructor(DOMString url, optional DOMString base),
 Exposed=(Window,Worker)]
    interface URL {};

Benannte Konstruktoren

[NamedConstructor=Image(optional unsigned long width, optional unsigned long height)]
    interface HTMLImageElement : HTMLElement {…

Ein benannter Konstruktor ist ein Konstruktor, der einen anderen Namen als seine Schnittstelle hat. Zum Beispiel erstellt new Image(…) ein neues HTMLImageElement-Objekt. Sie werden im WebIDL mittels der NamedConstructor-Annotation auf der Schnittstelle definiert, gefolgt vom Namen des Konstruktors nach dem Gleichheitszeichen ('=') und den Parametern innerhalb der Klammern, im gleichen Format, das Sie für Methoden sehen.

Es kann mehrere benannte Konstruktoren für eine bestimmte Schnittstelle geben, das ist jedoch extrem selten; in solch einem Fall beinhalten wir eine Unterseite pro Name.

Neue Konstruktorsyntax

Seit September 2019 wurde die WebIDL Konstruktorsyntax aktualisiert. Die Konstruktorsyntax beinhaltet keine erweiterte Attribut auf der Schnittstelle mehr:

[Constructor(DOMString str)]
    interface MyInterface {
      ...
};

Neue Spezifikationen verwenden stattdessen eine methodenähnliche Syntax mit dem Namen constructor ohne explizit definierten Rückgabewert, wie folgt geschrieben:

interface MyInterface {
  constructor(DOMString str);
};

Dies bedeutet, dass erweiterte Attribute nun auf den Konstruktor spezifiziert werden können, und es wird nicht mehr angenommen, dass alle Konstruktoren Ausnahmen auslösen. Wenn ein Konstruktor Ausnahmen auslöst, wird [Throws] verwendet, um dies anzuzeigen:

interface MyInterface {
  [Throws] constructor();
};

Es ist unwahrscheinlich, dass alle Spezifikationen aktualisiert werden, um die neue Syntax zu verwenden, sodass Sie wahrscheinlich beide Typen in freier Wildbahn antreffen werden. Wir werden daher weiterhin beide Arten von Syntax hier behandeln.

Verfügbarkeit in Workern

Konstruktoren haben die gleiche Verfügbarkeit wie die Schnittstelle oder die Teil-Schnittstelle, auf der sie definiert sind. Die Unterseite liefert diese Information auf die gleiche Weise wie für eine Methode.

Präferenzen

Konstruktoren werden durch die gleiche Präferenz gesteuert wie die Schnittstelle oder das Teil-Schnittstelle, auf der sie definiert sind. Die Unterseite liefert diese Information auf die gleiche Weise wie für eine Methode.