Skip to main content

Projekt-Setup

Damit VS Code die Typings findet, braucht unser Workspace drei Dinge: eine jsconfig.json im Root, den Ordner typings/ mit den .d.ts-Dateien von otris und den Ordner typings_dexpro/ mit unseren eigenen Deklarationen. jsconfig.json und typings/ legt die DOCUMENTS-Extension (vscode-documentsos) beim Einrichten des Projekts an, typings_dexpro/ pflegen wir selbst.

jsconfig.json

Die jsconfig.json sagt VS Code, welche Dateien zum Projekt gehören und welche JavaScript-Version gilt. Unsere aktuelle Konfiguration:

{
  "compilerOptions": {
    "checkJs": true,
    "alwaysStrict": true,
    "target": "es2016",
    "lib": ["es2016", "scripthost"],
    "baseUrl": ".",
    "paths": {
      // ... weitere Bibliotheken
    },
    "typeRoots": ["./typings"]
  },
  "include": [
    "node_modules/@types/**/*.d.ts",
    "src/**/*.js",
    "src/**/*.mjs",
    "typings/**/*.d.ts",
    "typings_dexpro/**/*.d.ts"
  ]
}
  • include bindet unsere Skripte (.js und .mjs in src/), die otris-Typings (typings/) und unsere eigenen (typings_dexpro/) ein. Nur was hier steht, kennt IntelliSense.
  • lib lässt bewusst dom weg. Sonst kollidieren die Browser-Klassen File und Document mit den gleichnamigen DOCUMENTS-Klassen.
  • target: es2016 schaltet Autovervollständigung für ES6-Features wie Map oder for...of frei. Achtung: Nicht alles davon unterstützt der DOCUMENTS-Server.
  • checkJs: true prüft jede Datei aus include auf Typfehler, nicht nur für IntelliSense. Die Meldungen erscheinen in der Problems-Ansicht.
  • alwaysStrict: true prüft jede Datei so, als stünde "use strict" darüber. Das ist nur Linting: Auf dem Server läuft ein Skript erst strikt, wenn "use strict"; im Skript selbst steht.
  • baseUrl + paths ordnen Modulnamen Dateien zu: unsere Bibliotheken (DexRecordLib → src/…) und Typings, deren Dateiname vom Modulnamen abweicht (gadgetAPI → gadgetApi.d.ts).
  • typeRoots sorgt dafür, dass Typings mit gleichem Datei- und Modulnamen (otrAssert, util.otrLogger) auch ohne paths-Eintrag gefunden werden.

Der Ordner typings/

Datei

Inhalt

Woher

portalScripting.d.ts

Die komplette PortalScripting-API: context, util, DocFile, FileResultset, SystemUser, Folder usw.

Extension

scriptExtensions.d.ts

Erweiterungen im Namespace otris.*, z.B. otris.tools.ClientHeaderCode

Extension

gadgetApi.d.ts

Gadget-API im Namespace otris.gadget.*

Extension

documentsClientSdk.d.ts

Client-SDK documents.sdk.* für Code, der im Browser läuft

Extension

fileTypes.d.ts

Unsere Mappentypen, Felder, Register und Ordnernamen, erzeugt aus dem DOCUMENTS-Server

Generiert aus dem Server

otrUpgrade*.d.ts, otrAssert.d.ts, util.otrLogger.d.ts, otrPackageManager.d.ts

Typings der otris-Bibliotheken (mit deutscher Doku)

Mit den Bibliotheken ausgeliefert

Wichtig: Die Dateien in typings/ werden nicht von Hand bearbeitet, denn die Extension überschreibt sie beim nächsten Aktualisieren. Eigene Typen gehören in JSDoc-Kommentare im Skript oder in unseren Ordner typings_dexpro/ (siehe "Bibliotheken und eigene .d.ts-Dateien").

Aktualisiert werden die Typings über die Befehlspalette (Cmd/Strg+Shift+P) oder per Rechtsklick auf den Ordner typings/ im Explorer:

  • documentsOS: Install Typings installiert die Standard-Typings der API (Rechtsklick auf das Projekt-Root).
  • documentsOS: Get Typings lädt die API-Typings passend zur Serverversion.
  • documentsOS: Get File Type Typings erzeugt fileTypes.d.ts neu aus den Mappentypen des Servers. Nach jeder Änderung an Mappentypen oder Feldern ausführen.

Typprüfung

In unserem Workspace ist die Prüfung projektweit an: checkJs und alwaysStrict stehen auf true. Das empfehlen wir für jeden DOCUMENTS-Workspace. Ein // @ts-check am Dateianfang ist damit nicht nötig.

  • Einzelne Datei ausnehmen: // @ts-nocheck als erste Zeile. Nur als Übergang für Altskripte und mit Kommentar, warum.
  • Was alwaysStrict zusätzlich findet: Code, der im Strict Mode verboten ist, z.B. delete auf einer Variablen (4 Stellen in DEXPRO__DbLib.js), Oktal-Literale wie 010 oder doppelte Parameternamen.
  • Ausgangslage: TypeScript 6.0.3 meldet mit diesen Einstellungen rund 3.200 Fehler in unseren Skripten, ohne src/decrypted.cat gezählt. Die häufigsten Ursachen stehen unter "Stolperfallen".

Neue Skripte gehen nur ohne Meldungen in der Problems-Ansicht auf den Server.

Back to top