TypeScript/de

Dieser Artikel behandelt die Verwendung von TypeScript im MediaWiki-Ökosystem. Es gibt viele hervorragende Ressourcen zur allgemeinen TypeScript-Nutzung, einige davon werden unten aufgeführt.

TypeScript als JavaScript-Dokumentations-Linter

Die ausführbare TypeScript-Datei tsc kann zum Linten der Dokumentation in einfachen JavaScript-Dateien verwendet werden.

JSDoc-Typisierung

JSDoc ist die bevorzugte Methode zum Schreiben von JavaScript-Dokumentation in MediaWiki-Software. TypeScript kann JSDocs analysieren und verstehen. Ein typischer Typ würde wie folgt dokumentiert:

/**
 * Template properties for a portlet.
 * @typedef {Object} PortletContext
 * @prop {string} portal-id Identifier for wrapper.
 * @prop {string} html-tooltip Tooltip message.
 * @prop {string} msg-label-id Aria identifier for label text.
 * @prop {string} [html-userlangattributes] Additional Element attributes.
 * @prop {string} msg-label Aria label text.
 * @prop {string} html-portal-content
 * @prop {string} [html-after-portal] HTML to inject after the portal.
 * @prop {string} [html-hook-vector-after-toolbox] Deprecated and used by the toolbox portal.
 */

Und eine Funktion wäre:

/**
 * @param {PortletContext} data The properties to render the portlet template with.
 * @return {HTMLElement} The rendered portlet.
 */
function wrapPortlet( data ) {
    const node = document.createElement( 'div' );
    node.setAttribute( 'id', 'mw-panel' );
    node.innerHTML = mustache.render( portalTemplate, data );
    return node;
}

Die obigen Beispiele auf dem TypeScript-Spielplatz.

Gemeinsame Nutzung von Typen über mehrere Dateien hinweg

  • Typdefinitionen (*.d.ts) sind standardmäßig globale Skripte.
  • Typdefinitionen werden zu nicht-globalen Modulen, wenn die Datei import oder export enthält. Alle Typen, die global sein sollen, müssen explizit als solche gekennzeichnet werden. Z. B.:
declare global {
  interface XY {x: number, y: number}
}
  • require und import bringen ihre Typen mit.
  • Importtypen sehen aus wie /** @typedef {import('../../math/xy').XY} XY */.

TypeScript-Definitionen

TypeScript-Definitionen sind ein gängiges Mittel, um die Dokumentation und Typisierungsinformationen für eine ganze Bibliothek wie jQuery zu beschreiben und zu teilen. Sie sind auch allgemein nützlich, um Definitionen über Dateien und globale Variablen hinweg zu teilen.

Eine äquivalente TypeScript-Definition (oder TSD) des obigen Typs und der Funktion (ohne Dokumentation und Implementierung) ist:

interface PortletContext {
    'portal-id': string;
    'html-tooltip': string;
    'msg-label-id': string;
    'html-userlangattributes'?: string;
    'msg-label': string;
    'html-portal-content': string;
    'html-after-portal'?: string;
    'html-hook-vector-after-toolbox'?: string;
}

declare function wrapPortlet(data: PortletContext): HTMLElement;

Die obigen Beispiele auf dem TypeScript-Spielplatz.

Die Dokumentation in TSD besteht weiterhin aus JSDocs und könnte daher mit den vorhergehenden Beispielen identisch sein (oder die JSDoc-Typisierung weglassen). TSD können jedoch keine Implementierung enthalten, da sie nicht kompiliert werden und keine funktionalen Auswirkungen haben.

MediaWiki TypeScript-Definitionen

  • Eine offizielle Bibliothek existiert zur Dokumentation des MediaWiki-Kerns und anderer gängiger Bibliotheken. Sie enthält Stand Juli 2024 nur eine kleine Anzahl von Typdefinitionen.
  • Es gibt auch von der Community verwaltete Bibliotheken mit besserer Abdeckung:

Beachte, dass Typdefinitionen auch in reinen JavaScript-Projekten in gängigen IDEs eine Code-Vervollständigung bereitstellen können.

TypeScript als Compiler

TypeScript unterstützt auch direktere Methoden zur Beschreibung von Typisierungsinformationen, sogenannte Annotationen. Diese Syntax erfordert jedoch die Verwendung von TypeScript selbst und einen Kompilierungsschritt. Beispiele sind (in etwa umgekehrter chronologischer Reihenfolge):

Projektaufbau

Bei Projekten mit gemischten JavaScript- und TypeScript-Dateien oder nur einfachen JavaScript-Dateien möchtest du möglicherweise Dateien ein- oder ausschließen, bis ihre Typisierung im Hinblick auf die Dokumentation vollständig korrekt ist. Hierfür gibt es mehrere Möglichkeiten, darunter:

  • tsconfig.json: Dateien können über das Feld includes hinzugefügt oder über das Feld excludes entfernt werden. Weitere Details finden sich unter [$4 Compiler-Optionen]. More details can be found under compiler options.
  • @ts-check / @ts-nocheck: Ganze Dateien mit einem einzigen Kommentar hinzufügen oder entfernen.
  • @ts-ignore: Die Fehler in einer einzelnen Zeile ignorieren. Sollte im Allgemeinen als vorübergehende Lösung verwendet werden, die auf ein Phabricator-Ticket verweist, da dies zu Fehlern in der Produktion führen kann (und dies auch getan hat).

Beispielkonfiguration der JavaScript-Dokumentation

{
	"exclude": ["docs", "vendor"],
	"compilerOptions": {
		"resolveJsonModule": true,
		"esModuleInterop": true,
		"strict": true,
		"noUnusedLocals": true,
		"noUnusedParameters": true,
		"noImplicitReturns": true,
		"newLine": "lf",
		"forceConsistentCasingInFileNames": true,
		"pretty": true,
		"target": "es5",
		"lib": ["dom"],
		"allowJs": true,
		"checkJs": true,
		"noEmit": true
	}
}

Vollständiges Projektbeispiel.

Siehe auch