Typescript: Was gefällt Ihnen an der TypeScript-Website und -Dokumentation nicht?

Seite "Dienstprogrammtypen" nicht aktuell

Neue Dienstprogrammtypen werden oft übersehen oder nicht zur Seite "Dienstprogrammtypen" des Handbuchs hinzugefügt (zB Parameters<T> ). Ich muss oft auf lib.es5.d.ts zurückgreifen, anstatt das Handbuch zu durchsuchen.

Schlagworte: docs

Offizieller TypeScript Playground ist nicht so gut wie Open-Source-Alternativen

https://typescript-play.js.org macht einen besseren Job als die offizielle: Es deckt mehrere Versionen von TypeScript ab, ermöglicht das Teilen größerer Texte, unterstützt alle Compiler-Flags und der strikte Modus ist standardmäßig aktiviert.

Schlagworte: playground

Fehlende Indexseite für Versionshinweise

Ich wünschte, es würde eine Indexseite geben, auf der alle früheren Versionshinweise unter dieser URL aufgeführt sind : https://www.typescriptlang.org/docs/handbook/release-notes . Auf diese Weise können wir die letzten Release-Updates von TypeScript verfolgen.

Schlagworte: docs , release notes

Es gibt kein Glossar mit Typnamen

Wenn Sie jemandem einen Code wie const a: "foo" | "bar" , wissen Sie möglicherweise nicht, dass Sie dies als Unionstyp bezeichnen sollen.

Dies ist ein ziemlich niedriger Balken, aber wenn wir über existentielle / bedingte / zugeordnete / usw. Typen sprechen, ist es schön, auf eine Seite gehen zu können, die nur versucht, sie zu definieren, aber nicht tief zu dokumentieren, damit Sie sich einen Überblick verschaffen können aller Taxonomien für diese Sprache

Schlagworte: types , handbook

Es gibt keine Seite zum Teilen mit Nicht-Technikern

Diesen brauchte ich, um Leute außerhalb des Ingenieurwesens (denken Sie an PMs, nicht-technische Manager) zunächst davon zu überzeugen, welchen Wert die Verwendung von TypeScript hat. Am Ende habe ich das selbst geschrieben , wäre aber lieber ein Beamter

Schlagworte: guides

Definitiv typisierte Dokumentation lebt außerhalb der TypeScript-Dokumentation und ist veraltet

Das TypeScript-Projekt sollte dazu eigene Dokumente besitzen. Die Dokumentation zu Definitely Typed lebt in:

• https://definitelytyped.org
• https://github.com/DefinitelyTyped/DefinitelyTyped#how -can-i-contribute

Die TS-Dokumente könnten einen Überblick darüber enthalten, was es ist, warum es verwendet wird, und wir können die offizielle Website ablehnen

Schlagworte: definitely-typed

unterrichtet nicht nach und nach TS

(Zur besseren Lesbarkeit bearbeitet) Ich glaube, dass Dokumente am effektivsten sind, wenn sie eine klare "Persona" haben, für die sie bestimmt sind. Als diese Dokumente erstellt wurden, gab es ES6 noch nicht. Als diese Dokumente erstellt wurden, konnten Sie alle TS an einem Nachmittag lernen.

Die Zeiten haben sich geändert.

Ich habe Reaction-Typescript-Spickzettel erstellt, weil ich das Gefühl hatte, dass die TS-Dokumente speziell nicht für Leute geeignet sind, die es6 bereits kannten und auch nicht fortgeschrittene TS auf einmal lernen wollten. also speziell für erfahrene JS-Entwickler, die TS zum ersten Mal ausprobieren. es gibt viele von uns. Die aktuellen Dokumente sind entweder „Hey, das sind Klassen“ oder „Hier sind ein paar beängstigend aussehende Generika auf derselben Seite wie unsere Typ-Operator-Dokumente“.

Hier ist insbesondere eine nicht erschöpfende Liste von zu berücksichtigenden Persönlichkeiten, die als progressiver Lehrer dienen könnten:

• Leute, die nur TS mit JSDoc verwenden möchten, kein Build-Schritt
• Leute, die TS verwenden möchten, ohne so viel wie möglich Generika zu schreiben
• Personen, die Codebasen von JS/Flow zu TS migrieren
• Personen, die neu bei TS sind, TS übernommen haben, aber zum ersten Mal unbekannte, ausführliche Fehler sehen und keine Ahnung haben, wie sie damit umgehen sollen (dies ist die Zielgruppe " Fehlerbehebung ") oder sich abmelden
• Personen, die TS-Bibliotheken im Vergleich zu TS-Apps veröffentlichen möchten
• Leute, die lernen wollen, wie man Typoperatoren verwendet
• Leute, die etwas über Type Utilities erfahren möchten, die ihnen helfen können
• Leute, die untypisierte Bibliotheken eingeben müssen (es ist sehr ein Netzwerkeffekt und ein Interesse von TS, das Schreiben von .d.ts so lächerlich einfach und gut dokumentiert wie möglich zu machen)
• und aaaaaaal am Ende, Leute, die lernen wollen, ihre eigene generische Typenlogik zu schreiben
• (vielleicht) Leute, die Plugins schreiben möchten, die TS AST . durchlaufen müssen

Dies sind alles Phasen der Adoptionsreise von TS. Wir sollten sie aufzeigen und sicherstellen, dass es keine Klippe in den Dokumenten gibt, an der die Leute abstürzen, weil sie nicht wissen, was sie tun sollen und daher annehmen, dass es zu schwer ist.

Ich denke, die Dokumente können viel dazu beitragen, den Mythos zu zerstreuen, dass:

• Sie brauchen zu jeder Zeit maximale Typsicherheit (nicht nur in tsconfig, sondern auch in den Entscheidungen, die wir in den Eingabefunktionen treffen)
• TS ist für OO-Programmierer (ja, das habe ich gesehen)
• TS ist nur für C#/Java-Entwickler gedacht, die zu JS kommen und Typen vermissen, es hat keinen wirklichen Wert für JS-Entwickler
• Sie sollten in der Lage sein, selbst herauszufinden, wie Sie TS-Fehler beheben können
• Im Allgemeinen hat TS eine hohe Lernkurve, um loszulegen

Wenn Ressourcen verfügbar sind, können und sollten wir gezielt große Entwickler-Communitys ansprechen, um ihre Einführung zu unterstützen, zB für React, aber auch Vue und auch Node und so weiter. Sie können dies außerhalb der Hauptdokumentation tun, zum Beispiel unterscheiden Vue-Dokumente zwischen Cookbook und Guide, die sich auf praktische Beispiele im Kontext konzentrieren.

Dies ist wahrscheinlich eine so große Hürde für die Annahme von TS im Spätstadium (dh Leute, die mehr Dokumente / Tools / Sicherheiten / Handhaltung benötigen, um auf TS verkauft zu werden), wie ich es mir vorstellen kann.

Tags: docs

Linked TypeScript Language Specification ist komplett veraltet

Direkt auf der Hauptseite verlinken Sie auf die "TypeScript Language Specification".

Lesen Sie die Spezifikation auf GitHub oder laden Sie sie als docx oder pdf herunter.

Diese Spezifikation ist jedoch völlig veraltet (bei Version 1.8 hängen geblieben, letztes echtes Update im Januar 2016) und wird nicht gepflegt. Es wäre am besten, jede Erwähnung der Spezifikation zu streichen.

Schlagworte: spec specification outdated

Spielplatzähnliches Widget für Codebeispiele

Präsentieren Sie alle Codebeispiele in Dokumenten in einem Playground-ähnlichen Widget mit allen praktischen Tooltips, Hervorhebungen usw.

Idealerweise mit der Fähigkeit, in einen vollständigen Spielplatz zu gelangen, mit Bearbeitung und Anzeige von ausgegebenen JS/Eingaben.

Dies würde natürlich davon abhängen, dass Official TypeScript Playground nicht so gut ist wie der Vorschlag von

API-Dokumentation, die nur in den Versionshinweisen vorhanden ist

Einige Typen, zB unknown , sind nur in den Versionshinweisen dokumentiert, was das Auffinden erschwert.

Schlagworte: docs

Fourslash-Spielplatz

Es gibt eine Menge Dateien in /tests/cases/compiler , die sich zusammen mit Baselines wie kryptische dunkle Materie verhalten. Diese Megabyte könnten als Dokumente/Demos wiederverwendet werden.

• Lassen Sie TS Playground eine beliebige Datei aus dem TS-Repository laden, etwa über: https://www.typescriptlang.org/play/tests/cases/compiler/aliasAssignments.ts
• Lass TS Playground 'Fourslash' verstehen
• Fügen Sie diesen Dateien beschreibende Kommentare hinzu

Das würde es jemandem ermöglichen, URL-Links zu interessanten Syntaxfällen zu erstellen, und den Leuten helfen, andere witzige Tests zu basteln und einzureichen.

Spielplatz, der eine gegebene TS-Syntax ERKLÄRT

Es ist nicht schwer, über eine verworrene TS-Syntax zu stolpern, die wirklich schwer zu verstehen ist. Rekursive Generika, kombiniert über Unions und funky indizierte Typen... Ein großes Nest solcher unheimlichen Tausendfüßler sind zum Beispiel Typisierungen.

Was wäre, wenn man in der Lage wäre, ein Stück winkelreicher Syntax einzufügen und eine ausführliche, für den Menschen verdauliche Ansicht oder ein Diagramm zu beobachten. Wissen Sie, wo Sie zweifellos deutlich sehen können, dass A eine Klasse ist und B ein Unionstyp ist und C ein generischer Parameter für D und so weiter.

Angefangen als naiver 'verbose AST Pretty-Print' kann sich dies mit der Zeit und dem Beitrag der Community sowohl in tiefere Mustererkennung als auch in reichhaltigere interaktive Visuals und UML-ähnliche Diagramme ausdehnen.

es gibt keine Suche nach der Dokumentation

Ich muss oft googeln, wie man etwas mit Typoskript macht, anstatt das Hauptdokument als Quelle der Wahrheit zu haben, z. B. mit DocSearch wie bei den React-Dokumenten

Schlagworte: search , exploration

Gemeinschaftsprojekte hervorheben

Das können Dinge wie Meetups, Community Talks oder Bücher sein.

Könnten aber auch größere Softwareprojekte, die TypeScript verwenden, von denen jemand lernen könnte.

Schlagworte: Community

Bereitstellung von Anleitungen zum Aktivieren bestimmter Compiler-Flags

ZB wenn ich noImplicitReturns einschalten würde, welche Art von Problemen würde ich treffen und wie sollte ich damit umgehen? Wir liefern diese Art von Empfehlungen mit den Versionshinweisen für die Zeit, als diese Flags eingeführt wurden, und daher ist es schwierig, sie nachzuschlagen.

Schlagworte: tsconfig

Erstellen Sie eine Compiler-Fehlerindexseite

Die Sprache Rust

Schlagworte: compiler

Was wäre, wenn man in der Lage wäre, ein Stück winkelreicher Syntax einzufügen und eine ausführliche, für den Menschen verdauliche Ansicht oder ein Diagramm zu beobachten?

Ich denke, das wäre cool, aber in einigen Fällen denke ich, dass eine stark strukturierte Erklärung, wie ein Typ zusammenbricht (was irgendwie möglich klingt, automatisch zu generieren), nicht so nützlich ist wie das Erkennen einiger gängiger Kombinationen von Typen und Mustern, die eine besonderes Ziel. Nehmen wir als Beispiel an, ich möchte, dass jemand erklärt, was das ist:

type X<T extends object> = {
    [K in keyof T]: T[K]
}[keyof T]

Das _könnte_ ich dir sagen

X ist ein Typalias mit einem Typparameter T der auf object . Wenn mit T instanziiert wird, erzeugt es einen zugeordneten Typ, wobei für jeden Bestandteil K vom Typ keyof T der Wert der indizierte Zugriffstyp T[K] . X erzeugt dann einen indizierten Zugriffstyp für diesen zugeordneten Typ mit dem Typ keyof T .

aber es wäre viel hilfreicher und doch außerordentlich schwierig, von etwas anderem als einem Menschen mit praktischen Kenntnissen in TypeScript zu produzieren, Ihnen zu sagen:

X ruft die Vereinigung der Typen der Memberwerte von T .

Ich denke, vielleicht könnte es praktisch sein, eine Sammlung von "Rezepten" von Mustern wie diesem zu haben.

Die Seite " Erweiterte Typen " ist nur eine Art Müllhalde für jeden nicht offensichtlichen Typ (ich habe eine Reihe von TypeScript-Ideen für ein statisches PHP-Analysetool gestohlen, daher finde ich mich oft auf dieser Seite wieder).

Eine Reihe der Ideen darin sind miteinander verknüpft, aber das könnte durchaus mit Hyperlinks zwischen den Seiten geschehen.

Besonders der Abschnitt Type Guard/Type Predicate verdient eine eigene Seite.

Anleitung zum Schreiben von Typoskriptbibliotheken

Ich habe festgestellt, dass der Versand einer in Typescript geschriebenen Bibliothek nicht ganz einfach ist. Viele Grenzfälle, die Sie je nach Zielverbraucher berücksichtigen sollten. Ich habe meine eigenen Meinungen dazu, die völlig zur Debatte stehen, aber es wäre großartig, offizielle Leitlinien für Bibliotheksautoren zu dokumentieren.

Schlagworte: libraries , guidance

Mobile Navigation kann schwierig sein

Ich kann das Website-Handbuch nicht vom Handy aus lesen, was ziemlich enttäuschend ist. Es wäre auch großartig, wenn Sie auf jeder Seite des Handbuchs unten auf der Seite eine vorherige/nächste Navigation haben könnten.

aus einem Tweet

Schlagworte: nav

Verwenden Sie mehr Beispiele aus der Praxis

Einige der aktuellen Beispiele sind zu allgemein oder abstrakt und verwenden buchstabenbasierte Namenskonventionen (A, B, C) oder Begriffe, die nicht zuordenbar sind (foo, bar, baz, args, obj usw.). Ich hoffe, mehr reale Beispiele (Formen, Tiere, Produkte, Benutzer) und legitime Anwendungsfälle (API-Aufrufe, Protokollierung, Fehlerbehandlung, Datenformatierung) zu sehen. Dies wäre besonders hilfreich für Konzepte, die bereits Abstraktionen sind, wie Generics und Advanced Types.

Hinweis: Einige Bereiche der Dokumentation behandeln dieses Problem bereits 👌🏻 aber es ist ein Hit und Miss.

Schlagworte: examples

Beispielbibliothek & Best Practices

Zeigen Sie, wie Sie verschiedene Arten von Funktionen eingeben. Like lodash hat alle möglichen ausgefallenen Funktionen wie Pick, Extend, Flatten usw. Beschreibe, wie man sie eingibt.

Eine Bibliothek, die inkrementell komplexer wird. Es hätte sogar mehr Links zu Commits lesen können, die zeigen, wie eine bestimmte Sache in TS in der Produktion verwendet wird.

Was auch immer am Ende gebaut wird, ich hoffe, es ist für jemanden sehr einfach, Beispiele hinzuzufügen. Ich gehe davon aus, dass es ein TS-Handbuch wie git repo sein wird.

Die besten Open-Source-Projekte haben normalerweise die beste Dokumentation und neue Benutzererfahrung.

Lassen Sie uns TS für neue Benutzer noch einladender machen.

Bessere Beschreibung der tsconfig-Optionen

Aktuelle Beschreibung auf der Seite Compileroptionen

• Bietet eine sehr vage Beschreibung jeder Option und deren Auswirkungen auf die Kompilierung und Typprüfung. Einige Beispiele könnten wirklich nützlich sein.
• Das Tabellenformat lässt ein wenig Platz für die Beschreibung
• Es gibt keine Informationen über die TypeScript-Version
• Die alphabetische Reihenfolge ist nicht sinnvoll, einige Optionen sind eng miteinander verbunden, wie target , module und lib oder alle strikt ähnlichen Optionen. Wenn man sie einzeln betrachtet, ist es schwierig, sie richtig zu erfassen. Sie werden die Option lib nicht verstehen, ohne zuerst target .
• Meistens verwenden die Leute diese Optionen in tsconfg-Dateien, nicht als tsc Optionen, so dass das aktuelle Format für Neulinge verwirrend sein könnte.
• Detailliertere Beschreibungen einiger Optionen sind in der Dokumentation verstreut, zB @types , typeRoots und types Optionen werden auf der Seite tsconfig.json beschrieben und baseUrl und paths in Modulauflösung

Es ist mit Bereitstellung von Anleitungen zum Aktivieren bestimmter Compiler-Flags- Vorschläge verbunden, aber ich denke, der gesamte Abschnitt muss einer allgemeinen Überarbeitung unterzogen werden. Derzeit gibt es keine Anleitung zum Einrichten der Konfiguration von Anfang bis Ende und es gibt kein gutes Glossar, in dem Sie herausfinden könnten, was die jeweilige Option bewirkt.

bearbeiten:
Ganz zu schweigen von neuen Optionen wie die zum Erstellen von Verbundprojekten, für die es keine Informationen in den Dokumenten gibt und Sie gezwungen sind, das Gesamtbild basierend auf Versionshinweisen und GitHub-Problemen zusammenzustellen.

Schlagworte: tsconfig

Sammeln Sie Dokumentation, Blog und andere offizielle Ressourcen an einem Ort

Wenn wir alle offiziellen Ressourcen über TypeScript an einem Ort sammeln könnten (zB www.typescriptlang.org ), wäre das großartig! 😊

Zum Beispiel befindet sich der Blogbeitrag zur Ankündigung von v3.5 an einer anderen Stelle ( devblogs.microsoft.com ):
https://devblogs.microsoft.com/typescript/announcing-typescript-3-5/

Und die Versionshinweise zu Version 3.4 befinden sich an einer anderen Stelle:
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html

Ich denke, dies ist für TypeScript-Entwickler nicht sehr nützlich und verwirrend. 😕

Schlagworte: blog , resources

Erstellen Sie tsconfig.json, indem Sie das UI-Formular mit Ihren Einstellungen und der Projekteinrichtung ausfüllen

Es wäre schön, wenn die Dokumentation ein Formular/einen Assistenten enthalten würde, der hilft, tsconfig.json zu generieren, das der Zielumgebung (Browser, nodeJS), den Benutzereinstellungen (so streng oder nachsichtig wie der Benutzer es wünscht) und der Projektverzeichnisstruktur entspricht. Derzeit enthalten TS-Compiler-Optionen mehrere veraltete Optionen und einige Compiler-Flags, die auf den ersten Blick so aussehen, als würden sie ziemlich dasselbe tun (was sind die Unterschiede zwischen einigen Optionen, z. B. in Bezug auf Pfade/Verzeichnisse/Stammverzeichnisse). Die generierte tsconfig sollte den Best Practices des Microsoft TypeScript-Kernteams entsprechen. Andere Leitfragen könnten sein:

• Wie ist die Erfahrung des Projektentwicklungsteams mit TypeScript (kann Anfängern Compileroptionen für "JS zu TS-Migrationspfad" vorschlagen, während für "TS-Gurus" alle strengen Optionen vorgeschlagen werden)
• ist das Projekt eine Bibliothek oder Anwendung (im Falle einer Bibliothek mit wenigen Abhängigkeiten kann es einfacher sein, einige strikte Funktionen wie strictNullChecks , daher kann dies je nach Benutzererfahrung empfohlen werden)
• ist die Anwendung, die JSX/TSX (React) verwendet
• Verwenden Sie ein Framework/eine Bibliothek, die Dekorateure verwendet?
  
  
  
  • sollten Dekoratoren-Metadaten ausgegeben werden, damit sie von Framework/Bibliothek zur Laufzeit verwendet werden können (erwähnen Sie Frameworks und Bibliotheken wie Angular, Aurelia als Beispiel)
  
  

Tags: tsconfig , examples , guides , wizard , exploration

@orta Ich denke, es wäre großartig, eine mobile Version des Spielplatzes zu erstellen oder zumindest die aktuelle anzupassen. Ab sofort sieht der Spielplatz auf dem Handy schrecklich aus (der Screenshot wurde auf dem iPhone 7 erstellt).

Ich wünschte, es gäbe einen Abschnitt im "Handbuch"-Bereich der Website, der sich speziell mit Objektliteralen und den verschiedenen Möglichkeiten, wie Sie sie eingeben können, befasst.

Zum Beispiel muss ich ständig so etwas wie "Typoskript-Objektliteral mit beliebigen Eigenschaften" oder "Typoskript-Objektliteral mit einer erforderlichen Eigenschaft und anderen Eigenschaften" googeln.

Und ich muss immer den Typ { [key: string]: any } nachschlagen, der nirgendwo wirklich diskutiert wird.

Einiges von diesem Zeug wird auf den "Schnittstellen" gesprochen, aber das ist nicht sofort offensichtlich.

Anbietertypen erweitern

Wenn ich mit DefinitelyTyped-Typen oder Moduldefinitionen anderer Anbieter arbeite, stelle ich manchmal fest, dass ich die Definitionen anpassen muss:

1) Überschreiben / ändern Sie die vorhandene Definition
2) Fügen Sie eine neue Methode / Eigenschaften hinzu

Ich konnte keine Dokumentation finden, um die Aufgabe in verschiedenen Szenarien richtig zu erledigen. Ich habe mir auch keine guten Notizen gemacht, wenn ich es selbst machen musste 🐙. https://www.typescriptlang.org/docs/handbook/declaration-merging.html befasst sich mit dem Problem für Erstanbietercode, aber ich habe diesen Rat nicht für Modultypen/Exporte von Drittanbietern zum Laufen gebracht.

Natürlich ist es großartig, PRs sofort zu öffnen, um die Typen im entsprechenden Repository zu korrigieren / zu aktualisieren, aber es kann eine Weile dauern, bis sie wieder in den Master-Zweig zusammengeführt werden, was den Workflow stören und das Hinzufügen vorübergehender any Konvertierungen und a . erzwingen kann Folge-TODO.

Schlagworte: vendor

Compiler-API-Dokumentation

Das Wiki enthält einige Informationen zur Verwendung der Compiler-API (https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API), zeigt jedoch nur Beispiele, wie Sie damit bestimmte Ziele erreichen. Es wäre toll, mehr Informationen im JSDoc-Stil zu haben, um die spezifischen Objekte und Methoden aufzulisten, die existieren und zu erfahren, was sie tun. Im Moment versuche ich, die API zu lernen und muss mir die Typoskript-Quelle ansehen, um herauszufinden, was vor sich geht.

(Bitte ignorieren, wenn dies nicht getan wurde, nur weil die API noch nicht stabil ist, wie im Wiki erwähnt)

Schlagworte: compiler

Tutorials, die sich auf TS im Vergleich zu bestehenden Sprachen konzentrieren

Viele Leute kommen zu TypeScript als ihre zweite (oder mehr) Sprache. Eine Möglichkeit, das Erlernen von TypeScript zu vereinfachen, besteht darin, es mit einer vorhandenen Sprache zu vergleichen, die Sie bereits kennen. Wir könnten Top-Programmiersprachen nach Popularität nehmen, zB JS, Java, C#, PHP, C (+ CPP) und Ruby - dann haben Sie Tutorials, die davon ausgehen, dass Sie wissen, wie diese Sprache funktioniert.

Im Moment gehen wir nur davon aus, dass Sie JS kennen.

Schlagworte: tutorials

Stellen Sie sicher, dass es standardmäßig zugänglich ist

Stellen Sie sicher, dass Linters wie Accessibilityinsights.io bestehen

Schlagworte: infra

Kurze, teilbare URLs für den Playground

Es wäre großartig, wenn die Schaltfläche "Teilen" des TypeScript-Spielplatzes kurze URLs erzeugen würde, anstatt den gesamten Quellcode in die URL zu kopieren.

Erlauben Sie alternativ, dass die URL eine Github-Gist-ID enthält, die den Playground füllt. zB: https://www.typescriptlang.org/play?gist=eb25a1f350e50d6ed3561a777fbfe424

Schlagworte: playground

Beispiele mit unterschiedlichen Einstellungen (für unterschiedliche Anwendungsfälle / Szenarien)

Ich fand es schwierig kennen zu lernen , wie ich meine TS Codebasis konfiguriert werden konnte und welche Beispiele , die ich für verschiedene Codebases folgen konnte , so dass es toll wäre , wenn eine Liste von Beispielen wie https://github.com/microsoft/TypeScriptSamples/ auf der Website verfügen würde um zu zeigen, wie man die tsconfig.json konfigurieren würde und wie man TS-Dateien strukturieren sollte, damit sie wie beabsichtigt funktionieren.

Schlagworte: docs , examples

Kein offensichtlicher Grund, warum Dokumente im Wiki vs. Handbuch stehen würden

Die Seite zu this im Wiki ist_awesome_ und ich wünschte, ich hätte sie früher gefunden. Wir sollten herausfinden, was für Dinge im Wiki enthalten sein sollen (vor allem, da es von niemandem leicht bearbeitet werden kann (externe Leute müssen eine PR senden) ) und die anderen Dinge in die Site verschieben.

Machen Sie eine bessere Navigation zwischen Themen und Titeln

Riesige Themen wie Handbuch § Fortgeschrittene Typen haben eine schlechte Navigation zwischen einzelnen Titeln, auch keine Schaltfläche zum Aufwärtsgehen . Es wäre wirklich schön, ein schwebendes Navigationsmenü hinzuzufügen. Derzeit ist es schwierig, von einem Titel zum anderen zu springen oder schnell einen gesuchten Titel zu finden.

Hier ist ein gutes Beispiel für die Navigation in diesem Git-Buch zu Assembly Script: https://docs.assemblyscript.org/basics/environment

Schlagworte: website , handbook , navigation

Code-Bearbeitung für Mobilgeräte

So wie ich es verstehe, ist die mobilfreundliche Codebearbeitung mit Syntaxhervorhebung und all den anderen IDE-Features mühsam.

Ich habe jedoch festgestellt, dass ich ziemlich oft mit Code-Snippets spielen möchte, während ich auf meinem Telefon bin, weg von einem Desktop/Laptop.

Ich hätte nichts gegen ein einfaches <textarea> Feld anstelle eines Syntax-hervorgehobenen Editors für den mobilen Gebrauch.

Die Fehler können möglicherweise auf einer anderen Seite oder einem Popup oder einem anderen HTML-Element liegen.

Tags: Spielplatz, Handy, Code-Editor

Dokument zum Hinzufügen der Erweiterung .js für browserkompatible es6-Module

Es wird nirgendwo erwähnt, dass TypeScript sehr gut verwendet werden kann, um es6-Module zu generieren, die im Browser funktionieren, indem einfach die Erweiterung .js an den Namen des Imports angehängt wird! Der einzige Ort, an dem diese Informationen zu existieren scheinen, ist in diesem Thread:
https://github.com/Microsoft/TypeScript/issues/16577#issuecomment -343610106

Ich bin mir nicht sicher, welche Version von TS es hinzugefügt hat, aber Importe wie './file.js' funktionieren jetzt (auch wenn die Datei tatsächlich file.ts ist).

Für mich war das ein riesiges Feature... aber offiziell existiert es nicht?!

Die Seite "Erweiterte Typen" enthält den Typ Omit<T, K> .

Omit<T, K> wurde kürzlich in TypeScript 3.5 hinzugefügt , aber die Seite " Erweiterte Typen " hat immer noch den folgenden Haftungsausschluss:

Hinweis: Der Exclude-Typ ist eine geeignete Implementierung des hier vorgeschlagenen Diff-Typs. Wir haben den Namen Exclude verwendet, um zu vermeiden, dass bestehenden Code, der ein Diff definiert, beschädigt wird, und wir sind der Meinung, dass der Name die Semantik des Typs besser vermittelt. Wir haben das Omit nicht eingeschlossenTyp, weil es trivial als Pick . geschrieben wird>.

Bereitstellung der Dokumentation zur Projekteinrichtung für Linters

Fügen Sie als Teil der Einrichtung eines Projekts hinzu, wie Sie mit einem Linter einrichten, höchstwahrscheinlich nur typescript-eslint, das das Projekt selbst verwenden soll.

Schlagworte: linter

Es gibt nichts, was die am häufigsten auftretenden Fehler oder TypeScript-Einschränkungen abdeckt.

Wenn Sie TypeScript zum ersten Mal lernen, gibt es bestimmte Muster, die + nicht in TypeScript unterstützt werden. Einer der einfachsten:

const buildResult = (name?: string) => {
  const result = {};
  if (name) {
    result.name = name; // error, this property doesn't exist on {}
  }
  return result;
};

Ich habe damit begonnen, TypeScript in meinem Unternehmen einzuführen, und Fälle wie dieser tauchen häufig auf, also habe ich begonnen, sie in einem FAQ-/Fehlerbehebungs-Stil zu dokumentieren. Es wächst schnell (beachten Sie, dass dies in einem rauen Zustand ist):

Ein Objekt nacheinander aufbauen
Warum Sie keine Fehler erhalten, wenn Sie sie wollen: übermäßige Eigenschaftsprüfung
So greifen Sie auf optionale Eigenschaften zu, auch von Unions
Warum Object.keys und Object.entries nicht das tun, was Sie wollen
Filterfilter machen, die Arbeit ohne Fehler reduzieren
Typverfeinerung geht verloren

Wenn eine dieser Informationen in den Dokumenten enthalten ist, konnte ich sie nicht finden. Ich habe diese nur durch jahrelanges Trial/Error und das Durchlesen der am häufigsten verlinkten Ausgaben auf Github verstanden.

Schlagwörter: errors , troubleshooting , limitations

Stellen Sie eine klare Dokumentation zum Hinzufügen benutzerdefinierter Typdefinitionen bereit

Es gibt eine Reihe von Bibliotheken, die keine Typen enthalten und für die kein @types/* Paket verfügbar ist. Ich würde gerne meine eigenen Deklarationsdateien für diese in meinem Projekt schreiben, aber es scheint keine Dokumentation zu geben, wie man sie "richtig" schreibt und Typoskript erkennt, um sie zu erkennen. Angenommen, ich importiere ein Modul von npm. Muss ich declare module x ? oder declare module "x" ? oder einen Namensraum verwenden? oder einfach die Typen exportieren? Gibt es einen bestimmten Ort, an dem ich diese Dateien ablegen muss? Welche Konfigurationsoptionen muss ich einstellen? typeRoots ? types ? paths ? include ? oder was? - Alles, was ich bisher gefunden habe, sind verwirrende Fehlermeldungen, schlecht erklärte Konfigurationsoptionen und veraltete SO-Fragen.

Schlagworte: docs

Fehlende Offline-Dokumentation

Moderne grundlegende Entwicklungstools wie git oder npm haben ihre eigene Untermenge von Befehlen, die es uns ermöglichen, auf Offline-Dokumentation/Referenz zuzugreifen, z.

$ git help ls-remote
$ npm help search 

Ich denke, es wäre schön, eine solche Funktion zu haben (auch wenn der TS ein bisschen anders ist).
Es würde uns ermöglichen, Dokumente lokal über den Befehl help zu durchsuchen, ohne auf die Site / Github usw. verweisen zu müssen:

$ tsc help tsc # basic CLI arguments desc
$ tsc help config # opens up html page of the tsconfig.json docs
$ tsc help v3.5 # opens up html page changelog
$ tsc help enum # finds pages containing `enum` type and hints their names/opens them up

Tags: offline , search , cli , local

Die Beispiele brauchen einige bessere Unterscheidungsfarben!

Wie es sein sollte:

const whomstve = (name: string) => name + 'is life'

So ist es aktuell:

const whomstve = (name: string) => name + 'is life'

Es ist ein bisschen blau, aber das war's.

Hallo Leute, ich habe dieses Problem im Auge behalten, während ich über die allgemeine Site-Struktur und die allgemeine Dokumentation im letzten Monat nachgedacht habe. Jetzt, da sich dieses Problem beruhigt hat, habe ich ein bisschen mehr Verständnis dafür, wie die Dokumente aussehen sollen.

Lassen Sie uns versuchen, alle diese Punkte basierend auf den Reaktionen durchzusehen, mit ein wenig Mischen für die Lesbarkeit.

API-Dokumente können manchmal nur in Versionshinweisen vorhanden sein

Dies wird schwierig sein, zum Teil, weil ich im Moment nicht sicher bin, was nur in den Release Notes steht.

In Bezug auf Sprache und Syntax würde ich erwarten, dass dies mit dem neuen Handbuch behoben und verbessert wird, das einen neuen Blick auf die gesamte Sprache wirft. Für den Rest der Dokumentation denke ich, dass ein Teil der neuen Sitemap die meisten Fälle abdecken sollte - aber es ist immer noch ein WIP

Keine Suche auf der Website

Ja, ich stimme zu, dieser ist definitiv entscheidend für die neue Site.

Die Website ist Closed Source

Fest! https://github.com/microsoft/TypeScript-website

Die neue Arbeit wird vom Master-Zweig gehen, aber im Moment ist die alte Site oben zugänglich und nimmt PRs entgegen. Ich habe auch Probleme aus dem TypeScript-Repository hierher verschoben, damit es einfacher ist, den Überblick zu behalten.

Utility-Seiten nicht aktuell

Fest! Teilweise habe ich viele PRs zusammengeführt und das aktuelle Handbuch von der Community auf den neuesten Stand gebracht. Sowie sicherzustellen, dass es im Navi angezeigt wird (statt nur bei einer Websuche)

Verbesserte Beschreibungen der TS Config-Optionen

Ich habe am Wochenende damit begonnen, dies zu untersuchen (wie können wir sicherstellen, dass der Compiler und die Website dieselbe ursprüngliche Datenquelle für diese Dokumente verwenden, und was kann die Website darauf aufbauen, um mehr Kontext bereitzustellen)

Einige Beispiele für die bisherige Richtung:

• meine eigenen Notizen von 2017
• Ich habe mit Ethan Arrowood @matterhorndev gechattet, dessen tsconfig-ui die Grundlage für die Erstellung eines TSConfig-Explorers sein könnte

Spielplatz ist nicht so gut wie Alternativen

Fest! Ich halte dies für ein positives Sprungbrett in die allgemeine Richtung, die ich mir für den Spielplatz wünsche. Ich habe einige Beispielmodelle, die eine langfristige Perspektive darauf bieten, wie der Spielplatz aussehen und sich anfühlen sollte, um ihn wirklich zum besten seiner Art zu machen.

( Klicken Sie für figma-Erkundungen )

Kurze gemeinsam nutzbare URLs für Playground

Behoben, siehe unten

Kein Glossar der Typennamen

Ich habe angefangen , meine eigenen zu schreiben , während ich den Compiler lerne - ich würde erwarten, dass dieser Feed in das neue Handbuch aufgenommen wird. Es betrifft auch die Spielplatzbeispiele, die als Glossar mit Beispielen für einige der fortgeschritteneren Typen dienen

[Spielplatz Ex1, Spielplatz Ex2]

Lehrt nicht nach und nach TS

Dies soll im neuen Handbuch angesprochen werden, um einige von #29288 zu zitieren (scrollen Sie zu New handbook )

Ein allgemeines Dokument für alle Benutzer zu schreiben ist schwierig, weil das Publikum für TypeScript breit ist und eine der Stärken (und Schwächen) des aktuellen Handbuchs darin besteht, dass es versucht, allen gleichzeitig zu dienen. Wir haben mehrere verschiedene Gruppen von Entwicklern, die unterschiedliche Erwartungen an das Erlernen von TypeScript haben, und wir müssen den Bekanntheitsgrad verschiedener Konzepte anpassen. Vor diesem Hintergrund ist es unser Ziel, das Handbuch in drei verschiedene Teile zu gliedern:

1. Maßgeschneiderte Einführungen (Setup für das Basishandbuch)
   
   
   
   1. Das Kernhandbuch (jeder liest das)
   
   
   2. Referenzseiten (ähnlich wie Deep-Dives/Anhänge)
   
   

Effektiv hat es ein paar verschiedene Ausgangspunkte und versucht dann, die Sprache zu lehren, sobald Sie sich mit dem umgebenden Ökosystem vertraut gemacht haben.

Behandelt das alles im Kommentar? Nein, nur der Anfang. Die aktuelle Sitemap, die ich habe, ist ziemlich umfangreich und diese Art von Problemen interessiert mich

Ich habe in meinen aktuellen Site-Map-Kochbüchern und -Anleitungen etwas Spielraum gelassen, da Kochbücher etwas sind, mit dem wir mehr Community-Unterstützung fördern können.

Anleitungen bereitstellen

Ich habe mir die Zeit genommen, die aktuellen Codebeispiele, die sich derzeit auf der TypeScript-Website befinden, auszusortieren und zu aktualisieren. Ich überlege immer noch, welche Beispiele besser auf unserer Seite bleiben, anstatt auf die offizielle Dokumentation umzuleiten (zum Beispiel, wenn ein Projekt jetzt nativ TypeScript unterstützt und sie ihre eigenen Dokumente haben).

Wie oben denke ich, dass der Abschnitt mit Kochbüchern und tatsächlichen Anleitungen auf der Website ausreichen sollte, um dies abzudecken

Sprachspezifikation ist veraltet

Ja, ich weiß nicht, ob ich es direkt aus dem Hauptrepo entfernen kann - aber es wird auf der neuen Site nicht erwähnt.

Bieten Sie bessere IDE-ähnliche Erfahrungen für Codebeispiele

Dies ist derzeit in der neuen Handbuch-Site enthalten , obwohl wir es auch auf die neue Site übertragen müssen. Es bietet auch Hervorhebungen und Inline-Fehlermeldungen, worüber ich aufgeregt bin.

Compilerfehler-Indexseite

Ich bin mir nicht sicher, ob dies passieren wird, zum Teil hat TypeScript viele Fehlercodes und sie ändern sich ziemlich regelmäßig. Es lohnt sich, darauf zurückzukommen, sobald es eine voll funktionsfähige Website und Dokumente gibt, aber im Moment ist es auf Eis gelegt.

Weitere Beispiele aus der Praxis anzeigen

Das neue Handbuch leistet hier bisher gute Dienste 👍🏾 - wir können uns bemühen, dass es so bleibt. Mit dem Rest der Dokumente werde ich versuchen, alles zu ändern, was ich so sehe.

Der mobile Support vor Ort ist schwach

Ich überlege, das Microsoft-Designsystem (fluid) für die neue Site zu verwenden, was bedeuten sollte, dass der mobile Support (mit Barrierefreiheit) „größtenteils kostenlos“ kommen sollte.

Bei etwas so Komplexem wie dem Spielplatz, der ein bisschen kniffliger ist, denke ich, dass für Handys in Telefongröße eine Denkweise zum Surfen / Erkunden gut geeignet ist. Ich habe also ein Modell davon, das einem schreibgeschützten Erlebnis etwas näher kommt:

Entdecken Sie die Verbesserungen der tsc-Hilfe

Ich bin offen dafür, aber die Typoskript-CLI ist wirklich nur ein Befehl, kompilieren (weshalb keine Hilfe bei Unterbefehlen erforderlich ist (obwohl --init das irgendwie unterbricht))

Ratschläge zur Verbesserung von DTS geben

Ja, ich plane, die definitiv getippte Website mit der Typoskript-Website zusammenzuführen und diese Dokumente zu konsolidieren. Ob _alle_ von ihnen auf der Site leben werden, steht noch zur Debatte. Es gibt gute Gründe, die tatsächlichen Implementierungsdetails des Beitrags im definitiv typisierten Repo zu behalten, während die Übersichten auf hoher Ebene in der Site leben können.

Dokumente/Blogs/Releasenotes konsolidieren

Eine knifflige Sache, ich habe nicht ganz eine Antwort auf die Blog- / Versionshinweise. Wir verwenden das Microsoft-Produkt-Blogging-System mit allen anderen, und ich bin mir nicht sicher, ob es eine gute Idee ist, all das in die Website selbst zu verschieben. Das können wir uns zeitlich näher vorstellen.

Auf der einfacheren Seite möchte ich diese Art von Informationen auf jeden Fall aus dem Wiki entfernen und sie nur innerhalb der Website belassen (wo sie von der Site-Suche indiziert werden kann) - ich möchte das TypeScript-Wiki speziell verlassen, um dazu beizutragen TypeScript und Arbeiten mit den TypeScript-Compiler-APIs (z. B. wenn Sie import * as ts from “typescript” oder ein Sprachserver-Plugin erstellen)

Decken Sie die am häufigsten auftretenden Fehler ab

Dies bezieht sich auf das obige - es gibt eine wirklich umfangreiche FAQ- Seite für diese Art von Problemen, die ich gerade erst im Wiki entdeckt habe (3 Jahre nach meiner Nutzung von TS).

Wir können dies als Grundlage nehmen und beginnen, sie mit Ihren Antworten auch auf die Hauptseite zu ziehen

Syntaxhervorhebung hinzufügen

Ja, stimme zu, danke!

Alles in allem denke ich, dass viele davon aktiv erforscht oder bearbeitet werden, und ich bin offen für mehr Feedback, während wir weiter an Dokumenten arbeiten!

Super Arbeit vielen Dank

Wie wäre es mit VSCode tsconfig-Erfahrung im Playground-Editor auszuleihen/verbessern/zusammenzuarbeiten, anstatt einen separaten zu erstellen?

Macht den Playground besser und die vorhandene Erfahrung in VSCode ist bereits halbwegs anständig.

Ich bin mir nicht ganz sicher, was du meinst. Gefällt Ihnen die automatische Vervollständigung von JSON-Schemafunktionen in VS Code? Ich hatte geplant, dies im JSON-Editor-Teil zu haben, aber eine Übersicht über jede Option als GUI mit Labels ist eine nützliche Möglichkeit, alle Optionen anzuzeigen und auszuwählen.

@orta Wenn das neue Handbuch zum offiziellen Handbuch wird, werden URLs, die auf Abschnitte des aktuellen Handbuchs verweisen,

@orta @jcalz Ich habe mich das gleiche gefragt, ich habe über 2,5K SO-Antworten, alle Antworten mit Links zu finden und sie alle zu aktualisieren, ist einfach nicht machbar. Im Idealfall funktionieren Links mit Fragmenten immer noch und leiten sie an neue Speicherorte weiter. Bei Bedarf helfe ich gerne beim Mapping.

Ja, ich glaube nicht an das Brechen von URIs - es gibt ein paar Möglichkeiten, die es zu erkunden gilt.

Ich denke, es wird wahrscheinlich ein neues URL-Root für das Handbuch verwenden (z. B. nicht docs/handbook/x.html sondern vielleicht /handbook/x.html ) und die älteren Seiten über eine Karte von so eine Art.

Ich würde gerne wissen, was alle Github-Labels für dieses Repository bedeuten. Einige von ihnen sind selbsterklärend, andere nicht.

"Needs Proposal" ist mir zum Beispiel unklar. Es wäre hilfreich, wenn alle Labels längere Beschreibungen haben, wie es einige bereits tun.

Kann für _spezifische_ Compiler-Optionen nicht auf Dokumente verlinken

Mein Team ist relativ neu bei TypeScript, und daher ändert sich unser tsconfig.json häufig, und oft möchte ich die Leute auf die Dokumentation für bestimmte Compiler-Optionen hinweisen, dh in Form von:

https://www.typescriptlang.org/docs/handbook/compiler-options.html#strict-null-checks
(or)
https://www.typescriptlang.org/docs/handbook/compiler-options.html#strictNullChecks

Links wie diese funktionieren nicht, aber ich möchte sie.

Derzeit ist die einzige HTML-ID, die ich auf dieser Seite sehen kann, #compiler-options, was nicht so nützlich ist, da es im Grunde ganz oben steht - eine ID für jede der Optionen zu haben wäre jedoch sehr hilfreich, um die Leute dazu zu bringen den gewünschten Teil der Seite.

Schlagworte: compiler

@Tyler-Murphy das haben wir jetzt behoben

@ssalka - ja, guter Aufruf, der in den neuen tsconfig-Dokumenten sein wird

--

Ich werde diese Ausgabe schließen, ich werde in Zukunft eine neue mit der gleichen Prämisse wieder eröffnen, sobald wir weiter in das Handbuch und die neue Website eingetaucht sind 👍

Typoskript-Spielplatz:
Ich habe das Gefühl, dass ich verrückt werde, aber ich kann keine einfache 'Teilen'-Option finden, um mein Projekt zu speichern und zu teilen (z. B. um es zu einem Github-Problem hinzuzufügen).
Ich sehe alle Links unter 'Export', aber kein 'Teilen'.

Typoskript-Spielplatz:
Ich habe das Gefühl, dass ich verrückt werde, aber ich kann keine einfache 'Teilen'-Option finden, um mein Projekt zu speichern und zu teilen (z. B. um es zu einem Github-Problem hinzuzufügen).
Ich sehe alle Links unter 'Export', aber kein 'Teilen'.

Beispiel: Spielplatz-Link

Die neue Seite sieht wirklich gut aus! Ich habe jedoch bemerkt, dass diese Anfrage (Ankerlinks für Compileroptionen) es nicht in 😕 . geschafft hat

Scheint eine wirklich einfache Anfrage zu sein und wäre für Neuankömmlinge sehr hilfreich. Ich hoffe, es in einem zukünftigen Update zu sehen!