Informationen in einer WebIDL-Datei

WebIDL kann an mehreren Orten gefunden werden:

• Jede Spezifikation enthält WebIDL innerhalb des Textes: Es ist ein sehr praktischer Weg, um präzise Definitionen zu vermitteln. Diese beschreiben die Syntax der API. Obwohl die kanonische Referenz, müssen wir bedenken, dass sie sich von der tatsächlichen Implementierung unterscheiden kann. Auf MDN wollen wir praktisch sein und dokumentieren, was die Web-Plattform wirklich ist, nicht was sie idealerweise sein sollte. Überprüfen Sie also gründlich, was dort mit den Implementierungen vorhanden ist (und zögern Sie nicht, Bugs zu melden, wenn Sie Inkonsistenzen entdecken).

• Drei Browser-Engines verwenden (modifiziertes) WebIDL als Teil ihrer Toolchain: Gecko, Chromium/Blink und WebCore/WebKit. Vor-Chromium-Versionen von Edge benutzten es intern, aber diese sind leider nicht öffentlich.

  • Für Gecko sind alle WebIDL-Dateien in einem einzigen Verzeichnis zusammengefasst: https://searchfox.org/mozilla-central/source/dom/webidl/. Ihre Erweiterung ist .webidl. Es gibt andere *.idl Dateien im Gecko-Quellbaum, aber sie sind nicht WebIDL, daher können Sie sie ignorieren. Ältere Versionen von Gecko haben einige ihrer WebIDL-Dateien etwas verstreut und verwenden möglicherweise sogar Mozillas IDL anstelle von WebIDL, um einige Webschnittstellen zu beschreiben, aber dies wird in keinem aktuellen Gecko-Code ein Problem darstellen.
  • Für Chromium befinden sie sich an zwei Standorten, beide Unterverzeichnisse des Quellcodes im renderer/ Verzeichnis: core/ und modules/. Der Chromium-Quellcode hat IDL-Dateien an anderen Orten, aber diese sind Teil des Testsystems und nicht relevant für API-Implementierungen.
  • Für WebCore sind sie über den Quellcode verstreut, sodass Sie etwas mehr suchen müssen: Z.B. https://github.com/WebKit/webkit/blob/main/Source/WebCore/html/DOMTokenList.idl

WebIDL ist in seiner Spezifikation definiert. Es wurde jedoch so konzipiert, dass es erweitert werden kann, um mehr Informationen zu übermitteln, und Browseranbieter haben dies auch getan:

• Für Gecko hat Mozilla die Dokumentation seines dialektalen WebIDL 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 bereitgestellt.

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

Der Schnittstellenname ist die Zeichenkette, die nach dem Schlüsselwort interface und vor der nächsten öffnenden Klammer ('{') oder dem Doppelpunkt (':') erscheint.

interface URL {};

Jede WebIDL-Schnittstelle, sei es eine echte Schnittstelle oder ein Mixin, hat ihre eigene Seite in der Dokumentation, die jeden Konstruktor, jede Eigenschaft und jede Methode auflistet, die für sie definiert sind.

Das übergeordnete Element, falls vorhanden, einer gegebenen Schnittstelle wird nach dem Schnittstellennamen definiert, gefolgt von einem Doppelpunkt (':'). Es kann nur ein übergeordnetes Element pro Schnittstelle geben.

interface HTMLMediaElement : HTMLElement {…}

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

Einige Eigenschaften oder Methoden stehen mehreren Schnittstellen zur Verfügung. Um eine Neudefinition zu verhindern, werden sie in speziellen WebIDL-Schnittstellen definiert, die Mixins genannt werden.

Ab September 2019 wurde die Mixin-Syntax aktualisiert. In der neuen Syntax verwendet man interface mixin, um eine Mixin-Schnittstelle zu definieren, wie folgt:

interface MyInterface {};

interface mixin MyMixin {
  void somethingMixedIn();
}

Man verwendet dann das includes Schlüsselwort, um zu sagen, dass die innerhalb eines Mixins definierten Eigenschaften auf einer Schnittstelle verfügbar sind:

MyInterface includes MyMixin;

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

interface MyInterface {};
interface mixin MyMixin {};

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

MyInterface includes MyMixin;

Für Dokumentationszwecke verbirgt MDN Mixins. Sie sind abstrakt und spezifikationsbezogene Konstrukte. Man kann sie nicht in der Browserkonsole sehen, und es ist nützlicher zu wissen, auf welchen realen Schnittstellen Methoden und Eigenschaften implementiert sind.

Wenn Sie ein Mixin in der IDL wie HTMLHyperlinkElementUtils finden, 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 Dokumentationen zu den konkreten Schnittstellen hinzugefügt werden, wie HTMLAnchorElement und HTMLAreaElement.

Lesen Sie die folgenden zwei Seiten, die HTMLHyperlinkElementUtils.hash entsprechend dokumentieren:

• HTMLAnchorElement.hash
• HTMLAreaElement.hash

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

In der alten WebIDL-Mixin-Syntax, die Sie immer noch an einigen Stellen antreffen könnten, werden Mixins mit der [NoInterfaceObject] Anmerkung versehen:

[NoInterfaceObject]
   interface MyMixin {…}

In der alten Syntax werden Mixins, die auf einer Schnittstelle implementiert sind, mit dem Schlüsselwort implements definiert.

MyInterface implements MyMixin;

Verfügbarkeit in Web-Workern (jeglicher Art) und auf dem Window-Scope wird durch eine Anmerkung [Exposed=(Window,Worker)] definiert. Die Anmerkung gilt für das partielle 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() auf dem Window-Scope und für jeden Worker verfügbar, wohingegen Performance.timing, Performance.navigation und Performance.toJSON() nicht für Web-Worker verfügbar sind.

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

Window

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

Worker

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

DedicatedWorker

Das partielle Interface ist nur im DedicatedWorkerGlobalScope verfügbar.

SharedWorker

Das partielle Interface ist nur im SharedWorkerGlobalScope verfügbar.

ServiceWorker

Das partielle Interface ist nur im ServiceWorkerGlobalScope verfügbar.

Ein weiterer möglicher Wert ist System, aber dieser hat eine besondere Bedeutung und muss nicht dokumentiert werden.

Beachten Sie, dass diese möglichen Werte selbst in WebIDL-Dateien definiert sind. Schnittstellen können eine [Global=xyz] Anmerkung haben. Es bedeutet, dass, wenn ein Objekt dieses Typs als globaler Scope verwendet wird, jede Schnittstelle, Eigenschaft oder Methode, mit xyz als Wert von [Exposed], 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 uns in einem dedizierten Worker befinden, jede Schnittstelle, Eigenschaft oder Methode, die für Worker oder DedicatedWorker über die [Exposed] Anmerkung exponiert ist, verfügbar ist.

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

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

Hier kontrolliert media.webspeech.synth.enabled das SpeechSynthesis Interface und seine Eigenschaften (die vollständige Auflistung hat mehr als 3).

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 ist die Eigenschaft propName im folgenden Beispiel nur über Chrome-Code aufrufbar:

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

Sie können die Definition einer Eigenschaft am Vorhandensein des attribute Schlüsselworts erkennen.

readonly attribute MediaError? error;

Im obigen Beispiel ist der Name der Eigenschaft error; in den Dokumenten werden wir darauf als HTMLMediaElement.error verweisen, da es zur HTMLMediaElement Schnittstelle gehört. Eine Verlinkung zur Seite erfolgt entweder mit dem Schnittstellenpräfix unter Verwendung von {{domxref('HTMLMediaElement.error')}} oder ohne das Präfix unter Verwendung von {{domxref('HTMLMediaElement.error', 'error')}} wenn der Kontext klar und unmissverständlich ist.

readonly attribute MediaError? error;

Der Eigenschaftswert ist ein Objekt des Typs MediaError. Das Fragezeichen ('?') zeigt an, dass es den Wert null annehmen 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 versehen werden, einer Zeichenfolge in eckigen Klammern (wie [LegacyNullToEmptyString]). Solche erweiterten Attribute zeigen spezielle Verhaltensweisen an, die im Verlauf beschrieben werden müssen. Hier ist eine Liste von Standard-Erweiterungsattributen von Typen und der Ergänzung, die gemacht werden muss:

[LegacyNullToEmptyString]

Der null Wert wird in nicht standardisierter Weise in eine Zeichenfolge umgewandelt. Der Standardweg ist ihn in die Zeichenfolge "null" zu verwandeln, aber in diesem Fall wird er in "" umgewandelt.

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

When set to the null value, that null value is converted to the empty string (""), so elt.innerHTML = null is equivalent to elt.innerHTML = "".

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

readonly attribute MediaError? error;

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

• In der Schnittstelle, indem das {{ReadOnlyInline}} Makro neben seinem Definitionstext hinzugefügt wird.
• Im ersten Satz seiner eigenen Seite, indem die Beschreibung beginnt mit: The read-only HTMLMediaElement.error property…
• Indem man die Beschreibung in der Schnittstellenseite beginnt mit Returns…

[SetterThrows]
            attribute DOMString src;

In einigen Fällen, wie wenn einige Werte illegal sind, kann das Festlegen eines neuen Wertes dazu führen, dass eine Ausnahme ausgelöst wird. Dies wird mit der [SetterThrows] Anmerkung markiert. Wenn dies geschieht, muss der Syntaxabschnitt auf der Eigenschaften-Seite einen Abschnitt Ausnahmen haben. Die Liste der Ausnahmen und die Bedingungen, unter denen sie ausgelöst werden, sind als Textinformationen in der Spezifikation dieser API aufgelistet.

Beachten Sie, dass einige Ausnahmen nicht explizit markiert sind, sondern durch die JavaScript-Bindungen definiert werden. Der Versuch, einen illegalen aufgezählten Wert (zu einer JavaScript String) als Parameter festzulegen, führt zu einer TypeError Ausnahme. Dies muss dokumentiert werden, ist jedoch nur implizit in der WebIDL-Dokumentation markiert.

Es ist ungewöhnlich, dass Getter Ausnahmen auslösen, obwohl es in einigen Fällen geschieht. In diesem Fall wird die [GetterThrows] Anmerkung verwendet. Auch hier muss der Syntaxabschnitt der Eigenschaften-Seite einen Abschnitt über Ausnahmen haben.

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

Wenn die Semantik von WebIDL nicht befolgt wird, wird oft selbst ohne [SetterThrows] oder [GetterThrows] eine Ausnahme ausgelöst. Zum Beispiel, wenn wir versuchen, in einem Read-Only Modus eine schreibgeschützte Eigenschaft auf einen neuen Wert zu setzen, das heißt, ihren impliziten Setter aufzurufen, wird eine schreibgeschützte Eigenschaft im Strict Mode eine Ausnahme auslösen.

Meist aus Kompatibilitätsgründen ist dieses Verhalten manchmal ärgerlich. Um dem vorzubeugen, indem man einen No-Op Setter erstellt (das heißt, indem man stillschweigend versucht, die Eigenschaft auf einen neuen Wert zu setzen), kann die [LenientSetter] Anmerkung 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.

Although this property is read-only, it will not throw if it is modified (even in strict mode); the setter is a no-operation and it will be ignored.

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.

Grundlegende Objekte mit Typen wie String (ein IDL DOMString oder anderes), Number (ein IDL byte, octet, unsigned int oder anderes) und Boolean werden immer kopiert und über sie muss nichts Besonderes notiert werden (es ist ein natürliches 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 erwähnt werden.

Manchmal muss eine API ein neues Objekt oder eine Kopie eines internen Objekts zurückgeben. Dieser Fall wird in der WebIDL mit der [NewObject] Anmerkung angezeigt.

[NewObject]
   readonly attribute TimeRanges buffered;

In diesem Fall gibt jeder Aufruf von buffered ein anderes Objekt zurück: dessen Änderung ändert nicht den internen Wert und eine Änderung des internen Werts wirkt sich nicht auf jede Objektinstanz aus. In der Dokumentation werden wir es markieren, indem wir das Adjektiv neu neben Objekt verwenden:

The HTMLMediaElement.buffered read-only property returns a new {{domxref("TimeRanges")}} object that…

und

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

Returns a new {{domxref("TimeRanges")}} object that …

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

Z.B.

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

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

Die Verfügbarkeit einzelner Eigenschaften in Workern ist ebenfalls in der WebIDL zu finden. Für eine Eigenschaft ist die Standardverfügbarkeit dieselbe wie die der interface (das heißt nur im Window Kontext verfügbar, wenn nichts Spezielles markiert ist) oder wie die der partial interface, in der sie definiert ist.

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

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

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

Hier kontrolliert media.webvtt.enabled die textTracks Eigenschaft.

Sie können die Definition einer Methode am Vorhandensein von Klammern nach dem Namen erkennen.

DOMString canPlayType(DOMString type);

Der Name der Methode ist canPlayType, und wir werden darauf als HTMLMediaElement.canPlayType() (mit den Klammern, die anzeigen, dass es sich um eine Methode handelt) in den Dokumenten verweisen, da es zur Schnittstelle HTMLMediaElement gehört. Eine Verlinkung zur Seite erfolgt entweder mit dem Schnittstellenpräfix unter Verwendung von {{domxref('HTMLMediaElement.canPlayType()')}}, oder ohne das Präfix unter Verwendung von {{domxref('HTMLMediaElement.canPlayType', 'canPlayType()')}} wenn der Kontext klar und unmissverständlich ist. Die Klammern sollten immer einbezogen werden.

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

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

Parametertypen können spezielle Verhaltensweisen haben, die mit erweiterten Attributen beschrieben werden (wie [LegacyNullToEmptyString]). Hier ist die Liste solcher Attribute und die Ergänzung, die Sie im Text vornehmen müssen:

[LegacyNullToEmptyString]

Fügen Sie den folgenden Satz am Ende der Parameterbeschreibung hinzu: A null value is treated the same as the empty string ("").

DOMString canPlayType(DOMString type);

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

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

[Throws]
   void fastSeek(double time);

Einige Methoden können Ausnahmen auslösen. Dies wird mit der [Throws] Anmerkung markiert. Wenn dies geschieht, muss der Syntaxabschnitt der Methoden-Seite einen Abschnitt über Ausnahmen haben. Die Liste der Ausnahmen und die Bedingungen, unter denen sie ausgelöst werden, sind als Textinformationen in der Spezifikation von API aufgeführt.

Beachten Sie, dass einige Ausnahmen nicht explizit markiert sind, sondern durch die JavaScript-Bindungen definiert werden. Der Versuch, einen illegalen aufgezählten Wert (gemappt auf ein JavaScript String) als Parameter festzulegen, führt zu einer TypeError Ausnahme. Dies muss dokumentiert werden, aber es ist nur implizit in der WebIDL-Dokumentation markiert.

Sehen Sie sich einen der diesen Ausnahme-Sektionen an.

Die Verfügbarkeit einzelner Methoden in Workern ist ebenfalls in der WebIDL zu finden. Für eine Methode ist die Standardverfügbarkeit dieselbe wie die der interface (das heißt nur im Window Kontext verfügbar, wenn nichts Spezielles markiert ist) oder wie die der partial interface, in der sie definiert ist.

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

In Gecko kann die Verfügbarkeit einiger Methoden durch eine Präferenz gesteuert werden. Dies wird ebenfalls in der WebIDL markiert.

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

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

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

Ein Stringifier gibt an, wie ein Objekt, das auf einer Schnittstelle basiert, in Kontexten aufgelöst wird, die eine Zeichenfolge erwarten. (Siehe den Abschnitt Stringifiers.) Zusätzlich wird das Schlüsselwort auf toString() abgebildet und wie folgt definiert:

stringifier;

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

Ein Jsonifier wird auf toJSON() abgebildet und wie folgt definiert:

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

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

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

Es sind zwei Arten der Iteration möglich: der Wert-Iterator und der Paar-Iterator.

Wert-Iterator

iterable<valueType>

Der Iterator iteriert über Werte des Typs valueType. Die generierten Methoden werden sein:

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

Ein solcher Iterator erlaubt die Verwendung der Syntax for (const p in object) als Kurzform von for (const p in object.entries()). Wir fügen einen Satz dazu in die Schnittstellenbeschreibung ein.

Die Werte, die über iteriert werden soll, können auf eine der folgenden Arten definiert werden:

• In der WebIDL-Datei, wobei die iterable<valueType> Notation verwendet wird. Beispielsweise siehe DOMTokenList.
• Implizit in der WebIDL-Datei, falls 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 der WebIDL-Datei, im begleitenden Text. Ein solcher Text ist typischerweise in der Spezifikation zu finden und beginnt gewöhnlich mit: "The values to iterate over…".

Paar-Iterator

iterable<keyType, valueType>

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

• entries(), welche einen iterator über die Wertpaare zurückgibt. Beispielsweise siehe FormData.entries().
• values(), welche einen iterator über die Werte zurückgibt. Beispielsweise siehe FormData.values().
• keys(), welche einen iterator über die Schlüssel zurückgibt. Beispielsweise siehe FormData.keys().
• forEach(), welche eine gegebene Rückruffunktion einmal für jeden Eintrag in der Liste ausführt. Beispielsweise siehe Headers.forEach().

Ein solcher Iterator erlaubt die Verwendung der Syntax for (const p in object) als Kurzform von for (const p in object.entries()). Wir fügen einen Satz dazu in die Schnittstellenbeschreibung ein. Z.B. FormData.

Die Wertpaare, die über iteriert werden soll, können auf eine der folgenden Arten definiert werden:

• In der WebIDL-Datei, wobei die iterable<keyType, valueType> Notation verwendet wird. Beispielsweise siehe FormData.
• Außerhalb der WebIDL-Datei, im begleitenden Text. Ein solcher Text ist typischerweise in der Spezifikation zu finden und beginnt gewöhnlich mit: "The value pairs to iterate over…".

Eine Schnittstelle kann als set-like definiert werden, was bedeutet, dass sie eine geordneten Menge von Werten darstellt, die folgende Methoden haben wird: entries(), keys(), values(), forEach() und has() (sie hat auch die size Eigenschaft). Sie unterstützt ebenfalls die Verwendung von for...of auf einem Objekt, das diese Schnittstelle implementiert. Der Set-ähnliche kann nicht "readonly" oder nicht sein. Wenn nicht schreibgeschützt, sind die Methoden zur Modifikation der Menge ebenfalls implementiert: add(), clear() und delete().

setlike<valueType>

Die generierten Eigenschaften werden sein:

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

In Fällen, in denen die set-like Erklärung nicht durch schreibgeschützt vorhergeht, werden die folgenden Methoden ebenfalls generiert:

• add() fügt einen Eintrag hinzu. Zum Beispiel die .add() Methode von FontFaceSet.
• clear() leert die set-like Struktur. Zum Beispiel die .clear() Methode von FontFaceSet.
• delete() entfernt einen Eintrag. Zum Beispiel die .delete() Methode von FontFaceSet.

Eine solche Set-Schnittstelle kann auch die Syntax for (const p in object) als Kurzform von for (const p in object.entries()) verwenden.

Einige IDL-Mitglieder zeigen spezielle Verhaltensweisen an, die auf geeigneten Seiten vermerkt werden sollten.

Zusätzlich zur Bereitstellung der toString() Methode für eine Schnittstelle, wie in toString() und toJSON() beschrieben, geben Stringifiers auch an, dass eine Objektinstanz, wenn sie als Zeichenfolge verwendet wird, eine andere Zeichenfolge zurückgibt als die Standardzeichenfolge. (Der Standard ist typischerweise eine JSON-Darstellung des Objekts). Genau wie das geschieht, hängt davon ab, wie es in der IDL spezifiziert ist. Unabhängig davon, wie, sollte das nicht standardmäßige Verhalten auf der Schnittstellenseite beschrieben werden.

Wenn das stringifier Schlüsselwort eine Attributname begleitet, hat die Referenzierung des Objektnamens dasselbe Ergebnis wie die Referenzierung des Attributnamens. Betrachten Sie die folgende IDL:

interface InterfaceIdentifier {
  stringifier attribute DOMString DOMString name;
};

Für eine Klasse, die auf dieser Schnittstelle basiert, sind die folgenden Codezeilen gleichwertig. Das Verhalten sollte auf der Eigenschaftenseite zusätzlich zur Schnittstellenseite vermerkt werden.

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

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

interface InterfaceIdentifier {
  stringifier;
};

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

Konstruktoren sind in der WebIDL ein wenig versteckt: Sie sind als Anmerkungen der Hauptschnittstelle aufgelistet.

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

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

Ein Konstruktor mit derselben Schnittstelle wird durch das Constructor Attribut an der Schnittstelle definiert. Es können Klammern und eine Liste von Parameter oder nicht vorhanden sein (wie im obigen Beispiel). Wir dokumentieren alle unbenannten Konstruktoren auf einer Unterseite — zum Beispiel wird das obige mit dem Slug Web/API/MessageChannel/MessageChannel und dem Titel MessageChannel() versehen.

Ein weiteres Beispiel für einen unbenannten Konstruktor, 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. Alle Syntax wird in einer einzigen Unterseite dokumentiert.

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

[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 new Image(…) erstellt ein neues HTMLImageElement-Objekt. Sie sind in der WebIDL unter Verwendung des NamedConstructor Attributs an der Schnittstelle definiert, gefolgt vom Namen des Konstruktors nach dem Gleichheitszeichen ('=') und dem Parameter innerhalb der Klammern im gleichen Format, wie Sie es bei Methoden sehen werden.

Es kann mehrere benannte Konstruktoren für eine spezifische Schnittstelle geben, aber dies ist extrem selten; in einem solchen Fall fügen wir eine Unterseite pro Name hinzu.

Ab 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 namens constructor ohne explizit definierten Rückgabetyp, der wie folgt geschrieben wird:

interface MyInterface {
  constructor(DOMString str);
};

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

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

Es ist unwahrscheinlich, dass alle Spezifikationen aktualisiert werden, um die neue Syntax zu verwenden, also werden Sie wahrscheinlich beide draußen in der Wildnis antreffen. Daher werden wir weiterhin beide Arten von Syntax hier abdecken.

Konstruktoren haben die gleiche Verfügbarkeit wie die Schnittstelle oder partielle Schnittstelle, auf der sie definiert sind. Die Unterseite liefert diese Informationen auf die gleiche Weise wie bei einer Methode.

Konstruktoren werden durch dieselbe Präferenz wie die Schnittstelle oder partielle Schnittstelle, auf der sie definiert sind, gesteuert. Die Unterseite liefert diese Informationen auf die gleiche Weise wie bei einer Methode.