Typescript: Apa yang tidak Anda sukai dari Situs Web dan Dokumentasi TypeScript?

Halaman "Jenis Utilitas" tidak mutakhir

Jenis utilitas baru sering terlewatkan atau tidak ditambahkan ke halaman "Jenis Utilitas" di buku pegangan (misalnya Parameters<T> ). Saya sering harus menelusuri lib.es5.d.ts alih-alih buku pegangan.

Tag: docs

Taman Bermain TypeScript Resmi tidak sebagus alternatif sumber terbuka

https://typescript-play.js.org melakukan pekerjaan yang lebih baik daripada yang resmi: ini mencakup beberapa versi TypeScript, memungkinkan berbagi teks yang lebih besar, mendukung semua flag kompiler dan mode ketat diaktifkan secara default.

Tag: playground

Kurangnya halaman indeks untuk Catatan Rilis

Saya berharap akan ada halaman indeks untuk mencantumkan semua Catatan Rilis sebelumnya di bawah URL ini : https://www.typescriptlang.org/docs/handbook/release-notes . Dengan begitu, kami dapat melacak pembaruan rilis sebelumnya di TypeScript.

Tag: docs , release notes

Tidak ada glosarium nama tipe

Jika Anda melewati kode seseorang seperti const a: "foo" | "bar" Anda mungkin tidak tahu untuk menyebutnya sebagai Jenis Serikat.

Yang ini adalah bilah yang cukup rendah, tetapi ketika kita mulai berbicara tentang tipe eksistensial/kondisional/dipetakan/dll, senang bisa membuka halaman yang hanya mencoba mendefinisikannya, tetapi tidak mendokumentasikannya secara mendalam sehingga Anda bisa mendapatkan gambaran umum dari semua taksonomi untuk bahasa ini

Tag: types , handbook

Tidak ada halaman untuk dibagikan dengan orang non-teknis

Yang ini saya awalnya perlu membujuk orang di luar teknik (pikirkan PM, Manajer non-teknis) apa nilai dalam menggunakan TypeScript. Pada akhirnya saya menulis ini sendiri tetapi lebih memilih pejabat

Tag: guides

Dokumentasi yang pasti diketik berada di luar dokumen TypeScript dan sudah ketinggalan zaman

Proyek TypeScript harus memiliki dokumen tentang ini. Dokumentasi untuk Pasti Diketik tinggal di:

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

Dokumen TS dapat berisi ikhtisar tentang apa itu, mengapa digunakan, dan kami dapat menghentikan situs resmi

Tag: definitely-typed

tidak mengajarkan TS secara bertahap

(Diedit agar lebih mudah dibaca) Saya merasa bahwa dokumen paling efektif ketika mereka memiliki "persona" yang jelas untuk mereka. Ketika dokumen ini dibuat, ES6 belum menjadi apa-apa. Saat dokumen ini dibuat, Anda dapat mempelajari semua TS dalam satu sore.

Waktu telah berubah.

Saya membuat react-typescript-cheatsheet bc saya merasa dokumen TS secara khusus tidak melayani orang yang sudah tahu es6 dan juga tidak ingin belajar TS tingkat lanjut sekaligus. jadi secara khusus menargetkan pengembang JS berpengalaman yang mencoba TS untuk pertama kalinya. ada banyak dari kita. Dokumen saat ini adalah "hei inilah kelasnya" atau "inilah sekumpulan obat generik yang tampak menakutkan di halaman yang sama dengan dokumen operator tipe kami".

khususnya di sini adalah daftar persona yang tidak lengkap untuk dipertimbangkan yang dapat berfungsi sebagai guru progresif:

• orang yang hanya ingin menggunakan TS dengan JSdoc, tidak ada langkah pembuatan
• orang yang ingin menggunakan TS tanpa menulis obat generik sebanyak mungkin
• orang yang memigrasi basis kode dari JS/Flow ke TS
• orang yang baru mengenal TS, mengadopsi TS, tetapi melihat kesalahan verbose yang tidak dikenal untuk pertama kalinya dan tidak tahu bagaimana menanganinya (ini adalah audiens " pemecahan masalah ") atau memilih keluar darinya
• orang yang ingin menerbitkan perpustakaan TS vs aplikasi TS
• orang yang ingin belajar menggunakan operator tipe
• orang yang ingin belajar tentang jenis utilitas yang dapat membantu mereka
• orang-orang yang perlu mengetik perpustakaan yang tidak diketik (ini adalah efek jaringan dan minat TS untuk membuat .d.ts menulis semudah mungkin dan didokumentasikan dengan baik)
• dan aaaaaaallll pada akhirnya, orang-orang yang ingin belajar bagaimana menulis logika tipe generik mereka sendiri
• (mungkin) orang yang ingin menulis plugin yang perlu melintasi TS AST

Ini semua adalah tahapan dalam perjalanan adopsi TS, kita harus memetakannya dan memastikan bahwa tidak ada jurang di dokumen tempat orang jatuh karena mereka tidak tahu apa yang harus dilakukan dan oleh karena itu menganggapnya terlalu sulit.

Saya pikir para dokumen dapat melakukan banyak hal untuk membantu menghilangkan mitos bahwa:

• Anda membutuhkan keamanan tipe maksimum setiap saat (tidak hanya di tsconfig, tetapi juga dalam pilihan yang kami buat dalam fungsi pengetikan)
• TS adalah untuk programmer OO (ya, saya telah melihat ini)
• TS hanya untuk pengembang C#/Java yang datang ke JS dan melewatkan tipe, tidak memiliki nilai nyata untuk pengembang JS
• Anda harus dapat mengetahui cara mengatasi kesalahan TS sendiri
• secara umum, TS memiliki kurva belajar yang tinggi untuk memulai

jika sumber daya tersedia, kita dapat dan harus menargetkan komunitas pengembang besar tertentu untuk membantu adopsi mereka, misalnya untuk React tetapi juga Vue dan juga Node dan sebagainya. Anda dapat melakukan ini di luar dokumen utama, misalnya Vue docs membuat perbedaan antara Buku Masak dan Panduan yang berfokus pada contoh praktis dalam konteks.

ini mungkin rintangan besar untuk adopsi TS tahap akhir (yaitu orang yang membutuhkan lebih banyak dokumen/alat/jaminan/pegangan untuk dijual di TS) seperti yang dapat saya bayangkan.

tag: docs

Spesifikasi Bahasa TypeScript Tertaut benar-benar ketinggalan zaman

Langsung di halaman utama yang Anda tautkan ke "Spesifikasi Bahasa TypeScript".

Baca spesifikasi di GitHub atau unduh sebagai docx atau pdf.

Namun, spesifikasi tersebut benar -

Tag: spec specification outdated

Widget seperti taman bermain untuk contoh kode

Sajikan semua contoh kode dalam dokumen di widget seperti taman bermain, dengan semua tooltip, sorotan, dll.

Idealnya dengan kemampuan untuk muncul ke taman bermain penuh, dengan mengedit dan melihat JS/pengetikan yang dipancarkan.

Ini tentu saja akan bergantung pada Official TypeScript Playground yang tidak sebaik saran

Dokumentasi API yang hanya ada di catatan rilis

Beberapa jenis, misalnya unknown , hanya didokumentasikan dalam catatan rilis , yang membuatnya sulit ditemukan.

Tag: docs

Taman bermain Fourslash

Ada banyak sekali file di /tests/cases/compiler yang, bersama dengan baseline, berperilaku seperti materi gelap samar. Megabita ini dapat digunakan kembali sebagai dokumen/demo.

• buat taman bermain TS memuat file apa pun dari repo TS melalui sesuatu seperti: https://www.typescriptlang.org/play/tests/cases/compiler/aliasAssignments.ts
• membuat taman bermain TS mengerti 'fourslash'
• tambahkan komentar deskriptif ke file-file itu

Itu akan memungkinkan seseorang untuk menautkan URL ke kasus sintaksis yang menarik, dan membantu orang mengotak-atik dan mengirimkan tes funky lainnya.

Taman bermain yang MENJELASKAN sintaks TS yang diberikan

Tidak sulit untuk menemukan sintaks TS yang berbelit-belit yang sangat sulit untuk dipahami. Obat generik rekursif, dikombinasikan melalui serikat pekerja dan tipe indeks yang funky... Salah satu sarang besar kelabang menakutkan seperti itu adalah mengetik, misalnya.

Bagaimana jika seseorang dapat menempelkan sepotong sintaks yang kaya sudut, dan mengamati tampilan atau diagram yang dapat dicerna manusia. Anda tahu, di mana Anda dapat dengan jelas melihat bahwa A adalah kelas, dan B adalah tipe gabungan, dan C adalah parameter umum untuk D dan seterusnya.

Dimulai sebagai 'cetakan cantik AST verbose' yang naif, seiring waktu dan kontribusi komunitas, ini dapat berkembang menjadi pengenalan pola yang lebih dalam dan ke visual interaktif yang lebih kaya dan diagram seperti UML.

tidak ada pencarian untuk dokumentasi

Saya sering harus menggunakan googling bagaimana melakukan sesuatu dengan TypeScript daripada memiliki dokumen utama sebagai sumber kebenaran, misalnya dengan DocSearch seperti pada React docs

Tag: search , exploration

Sorot proyek komunitas

Ini bisa berupa pertemuan, diskusi komunitas, atau buku.

Tetapi bisa juga proyek perangkat lunak yang lebih besar yang menggunakan TypeScript yang dapat dipelajari seseorang.

Tag: Community

Berikan panduan untuk mengaktifkan flag compiler tertentu

Misalnya jika saya mengaktifkan noImplicitReturns masalah seperti apa yang akan saya hadapi, dan bagaimana saya harus menanganinya? Kami mengirimkan rekomendasi semacam ini dengan catatan rilis versi untuk saat flag tersebut diperkenalkan, sehingga mencarinya sulit.

Tag: tsconfig

Buat halaman indeks kesalahan kompiler

Bahasa rust melakukan ini , cukup banyak upaya untuk memulai (TS memiliki lebih dari seribu kesalahan saat ini) tetapi pesan kesalahan di tsc singkat, memilikinya di situs membuatnya dapat diindeks oleh mesin pencari, dapat diperbaiki dan dengan kode contoh .

Tag: compiler

Bagaimana jika seseorang dapat menempelkan sepotong sintaks yang kaya sudut, dan mengamati tampilan atau diagram yang mudah dicerna manusia

Saya pikir ini akan keren, tetapi dalam beberapa kasus saya pikir penjelasan yang sangat terstruktur tentang bagaimana suatu tipe rusak (yang terdengar agak mungkin untuk dihasilkan secara otomatis) tidak berguna seperti mengenali beberapa kombinasi umum tipe dan pola yang menyelesaikan tujuan tertentu. Sebagai contoh, katakanlah saya ingin seseorang menjelaskan apa ini:

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

Saya _bisa_ memberi tahu Anda bahwa

X adalah alias tipe dengan satu parameter tipe T yang dibatasi ke object . Ketika dipakai dengan T , itu menghasilkan tipe yang dipetakan, di mana untuk setiap konstituen K dari tipe keyof T , nilainya adalah tipe akses yang diindeks T[K] . X kemudian menghasilkan tipe akses yang diindeks pada tipe yang dipetakan dengan tipe keyof T .

tetapi akan jauh lebih membantu, namun sangat sulit untuk diproduksi oleh apa pun kecuali manusia yang memiliki pengetahuan tentang TypeScript, untuk memberi tahu Anda:

X mendapatkan gabungan dari tipe nilai anggota T .

Saya pikir mungkin memiliki kumpulan "resep" pola seperti ini bisa berguna.

Halaman Jenis Lanjutan hanyalah semacam tempat pembuangan untuk semua jenis yang tidak jelas (saya telah mencuri banyak ide TypeScript untuk alat analisis statis PHP , jadi saya sering menemukan diri saya di halaman itu).

Sekelompok ide di sana saling terkait, tetapi itu bisa dilakukan dengan hyperlink antar halaman.

Bagian Type Guard/Type Predicate secara khusus terasa seperti halamannya sendiri.

Panduan untuk menulis perpustakaan TypeScript

Saya telah menemukan bahwa mengirimkan perpustakaan yang ditulis dalam TypeScript tidak mudah. Banyak kasus tepi yang perlu dipertimbangkan tergantung pada target konsumen Anda. Saya memiliki pendapat saya sendiri tentang hal ini yang benar-benar dapat diperdebatkan, tetapi mendokumentasikan panduan resmi untuk penulis perpustakaan akan luar biasa.

Tag: libraries , guidance

Navigasi Seluler bisa jadi sulit

Saya tidak bisa membaca buku pegangan situs web dari ponsel yang cukup mengecewakan. Juga akan sangat bagus jika Anda dapat memiliki navigasi sebelumnya/berikutnya di bagian bawah halaman pada setiap halaman buku pegangan.

dari sebuah tweet

Tag: nav

Gunakan lebih banyak contoh dunia nyata

Beberapa contoh saat ini terlalu umum atau abstrak, menggunakan konvensi penamaan yang berbasis huruf (A, B, C) atau istilah yang tidak dapat dikaitkan (foo, bar, baz, args, obj, dll). Saya berharap dapat melihat lebih banyak contoh dunia nyata (bentuk, hewan, produk, pengguna) dan kasus penggunaan yang sah (panggilan API, pencatatan log, penanganan kesalahan, pemformatan data). Ini akan sangat membantu untuk konsep yang sudah abstrak, seperti Generik dan Tipe Lanjutan.

Catatan: Beberapa bagian dari dokumentasi sudah menangani masalah ini tapi itu hit and miss.

Tag: examples

Contoh Perpustakaan & Praktik Terbaik

Tunjukkan cara mengetik berbagai jenis fungsi. Seperti lodash memiliki semua jenis fungsi mewah seperti pick, extends, flatten dll. Jelaskan cara mengetiknya.

Sebuah perpustakaan yang secara bertahap membangun kompleksitas. Bahkan bisa membaca lebih banyak tautan ke komit yang menunjukkan bagaimana hal tertentu dalam TS digunakan dalam produksi.

Apa pun yang akhirnya dibangun, saya harap sangat mudah bagi seseorang untuk menambahkan contoh. Saya berasumsi itu akan menjadi buku pegangan TS seperti git repo.

Proyek open source terbaik biasanya memiliki dokumentasi terbaik dan pengalaman pengguna baru.

Mari buat TS lebih ramah untuk pengguna baru.

Deskripsi opsi tsconfig yang lebih baik

Deskripsi saat ini di halaman Opsi Kompilator

• Memberikan deskripsi yang sangat kabur dari setiap opsi dan bagaimana pengaruhnya terhadap kompilasi dan pengecekan tipe. Beberapa contoh bisa sangat berguna.
• Format tabel menyisakan sedikit ruang deskripsi
• Tidak ada info tentang versi TypeScript
• Urutan abjad tidak berguna, beberapa opsi terkait erat satu sama lain seperti target , module dan lib atau semua opsi serupa yang ketat. Sulit untuk memahaminya dengan baik ketika Anda melihatnya secara terpisah. Anda tidak akan memahami opsi lib tanpa memahami target terlebih dahulu.
• Sebagian besar waktu orang menggunakan opsi tersebut dalam file tsconfg, bukan sebagai opsi tsc sehingga format saat ini dapat membingungkan bagi pendatang baru.
• Deskripsi lebih rinci dari beberapa opsi tersebar di seluruh dokumentasi misalnya opsi @types , typeRoots dan types dijelaskan di halaman tsconfig.json dan baseUrl dan paths dalam Resolusi Modul

Itu terhubung dengan Memberikan panduan untuk mengaktifkan saran

edit:
Belum lagi opsi baru seperti yang terkait dengan membangun proyek komposit, yang tidak ada informasinya dalam dokumen dan Anda dipaksa untuk menyatukan keseluruhan gambar berdasarkan catatan rilis dan masalah GitHub.

Tag: tsconfig

Kumpulkan dokumentasi, blog, dan sumber daya resmi lainnya ke satu tempat

Jika kami dapat mengumpulkan semua sumber resmi tentang TypeScript ke satu tempat (misalnya www.typescriptlang.org ), itu akan luar biasa! 😊

Misalnya, posting blog tentang pengumuman v3.5 ada di tempat lain ( devblogs.microsoft.com ):
https://devblogs.microsoft.com/typescript/announcing-typescript-3-5/

Dan, catatan rilis v3.4 ada di tempat lain:
https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html

Saya merasa ini tidak terlalu berguna dan membingungkan bagi pengembang TypeScript. 😕

Tag: blog , resources

buat tsconfig.json dengan mengisi formulir UI dengan preferensi dan pengaturan proyek Anda

Alangkah baiknya, jika dokumentasi akan berisi formulir/wizard yang membantu menghasilkan tsconfig.json yang sesuai dengan lingkungan target (browser, nodeJS), preferensi pengguna (ketat atau lunak seperti yang diinginkan pengguna) dan struktur direktori proyek. Saat ini TS Compiler Options berisi beberapa opsi yang tidak digunakan lagi dan beberapa flag compiler, yang dari pandangan pertama terlihat seperti mereka mungkin melakukan hal yang hampir sama (apa perbedaan antara beberapa opsi, misalnya terkait dengan path/dirs/roots). Tsconfig yang dihasilkan harus mematuhi praktik terbaik dari tim inti Microsoft TypeScript. Pertanyaan panduan lainnya mungkin termasuk:

• apa pengalaman tim pengembangan proyek dengan TypeScript (mungkin menyarankan opsi kompiler terkait "JS ke TS migrasi" untuk pemula sambil menyarankan semua opsi ketat untuk "guru TS")
• adalah proyek perpustakaan atau aplikasi (dalam kasus perpustakaan dengan sedikit dependensi mungkin lebih mudah untuk menggunakan beberapa fitur ketat, seperti strictNullChecks , jadi mungkin disarankan tergantung pada pengalaman pengguna)
• adalah aplikasi yang menggunakan JSX/TSX (Bereaksi)
• apakah Anda menggunakan kerangka kerja/perpustakaan, yang menggunakan dekorator
  
  
  
  • haruskah metadata dekorator dipancarkan, sehingga dapat digunakan oleh kerangka kerja/perpustakaan saat runtime (sebutkan kerangka kerja dan pustaka, seperti Angular, Aurelia sebagai contoh)
  
  

Tag: tsconfig , examples , guides , wizard , exploration

@orta Saya pikir akan luar biasa untuk membuat taman bermain versi seluler, atau setidaknya mengadaptasi yang sekarang. Sampai sekarang, taman bermain terlihat mengerikan di ponsel (tangkapan layar dibuat di iPhone 7).

Saya berharap ada bagian di area "buku pegangan" situs web yang berbicara secara khusus tentang literal objek dan berbagai cara Anda dapat mengetiknya.

Misalnya, saya terus-menerus harus ke Google sesuatu seperti "literal objek TypeScript dengan properti apa pun" atau "literal objek TypeScript dengan satu properti yang diperlukan dan properti lainnya".

Dan saya selalu harus mencari tipe { [key: string]: any } , yang sebenarnya tidak dibahas di mana pun.

Beberapa hal ini dibicarakan di "Antarmuka" tetapi itu tidak segera terlihat.

Menambah jenis vendor

Terkadang ketika bekerja dengan tipe PastiTyped atau definisi modul vendor lainnya, saya menemukan bahwa saya perlu mengubah definisi menjadi:

1) Timpa / ubah definisi yang ada
2) Tambahkan metode/properti baru

Saya belum dapat menemukan dokumentasi tentang cara yang tepat untuk menyelesaikan tugas dalam skenario yang berbeda. Saya juga belum membuat catatan yang baik ketika saya harus melakukannya sendiri . https://www.typescriptlang.org/docs/handbook/declaration-merging.html menangani masalah untuk kode pihak pertama tetapi saya belum membuat saran itu berfungsi untuk jenis/ekspor modul pihak ketiga.

Jelas itu bagus untuk segera membuka PR untuk memperbaiki/memperbarui jenis pada repo yang sesuai, tetapi itu bisa memakan waktu cukup lama untuk digabungkan kembali ke cabang master yang dapat mengganggu alur kerja dan memaksa menambahkan konversi any dan tindak lanjut TODO.

Tag: vendor

Dokumentasi API kompiler

Wiki memiliki beberapa info seputar penggunaan Compiler API (https://github.com/microsoft/TypeScript/wiki/Using-the-Compiler-API) tetapi hanya menunjukkan contoh cara menggunakannya untuk mencapai tujuan tertentu. Akan sangat bagus untuk memiliki lebih banyak info gaya JSDoc untuk membuat daftar objek & metode spesifik yang ada dan mempelajari tentang apa yang mereka lakukan. Saat ini saya sedang mencoba mempelajari API dan perlu melihat sumber TypeScript untuk mencari tahu apa yang sedang terjadi.

(harap abaikan jika ini belum dilakukan hanya karena API belum stabil seperti yang disebutkan di wiki)

Tag: compiler

Tutorial yang fokus pada TS dibandingkan dengan bahasa yang ada

Banyak orang datang ke TypeScript sebagai bahasa kedua (atau lebih). Salah satu cara untuk menyederhanakan pembelajaran TypeScript adalah dengan membandingkannya dengan bahasa yang sudah Anda ketahui. Kita bisa mengambil bahasa pemrograman teratas dengan popularitas misalnya JS, Java, C#, PHP, C (+ CPP) dan Ruby - kemudian mengarahkan tutorial yang menganggap Anda memiliki pengetahuan tentang cara kerja bahasa itu.

Saat ini kami hanya berasumsi bahwa Anda tahu JS.

Tag: tutorials

Pastikan itu dapat diakses secara default

Pastikan linter seperti aksesibilitasinsights.io lulus

Tag: infra

URL singkat yang dapat dibagikan untuk taman bermain

Akan sangat bagus jika tombol "Bagikan" di taman bermain TypeScript menghasilkan URL pendek, daripada membuang seluruh kode sumber ke dalam URL.

Atau, izinkan URL berisi ID inti github yang mengisi taman bermain. misalnya: https://www.typescriptlang.org/play?gist=eb25a1f350e50d6ed3561a777fbfe424

Tag: playground

Contoh dengan pengaturan yang berbeda (untuk kasus/skenario penggunaan yang berbeda)

Saya merasa sulit untuk mengetahui bagaimana saya dapat mengonfigurasi basis kode TS saya dan contoh apa yang dapat saya ikuti untuk berbagai basis kode sehingga akan sangat bagus jika daftar contoh seperti https://github.com/microsoft/TypeScriptSamples/ akan ditampilkan di situs web untuk menunjukkan bagaimana seseorang akan mengonfigurasi tsconfig.json dan bagaimana dia harus menyusun file TS agar berfungsi sebagaimana dimaksud.

Tag: docs , examples

Tidak ada alasan yang jelas mengapa dokumen ada di wiki vs buku pegangan

Halaman di this di wiki adalah_awesome_ dan saya berharap saya menemukannya lebih cepat. Kita harus mencari tahu hal-hal seperti apa yang harus hidup di wiki (terutama karena tidak mudah diedit oleh orang lain (orang luar harus mengirim PR ) ) dan memindahkan hal-hal lain ke dalam situs.

Buat navigasi yang lebih baik antara topik dan judul

Topik besar seperti Buku Pegangan Jenis Lanjutan memiliki navigasi yang buruk antara judul yang terpisah, tidak ada tombol naik juga. Akan sangat menyenangkan untuk menambahkan menu navigasi mengambang. Saat ini sulit untuk melompat dari satu judul ke judul lain atau mencari tahu yang diinginkan dengan cepat.

Berikut adalah contoh navigasi yang baik yang diberikan dalam buku git Assembly Script ini: https://docs.assemblyscript.org/basics/environment

Tag: website , handbook , navigation

Pengeditan Kode Taman Bermain Ramah Seluler

Seperti yang saya pahami, pengeditan kode ramah seluler dengan penyorotan sintaksis dan semua fitur IDE lainnya sangat merepotkan.

Namun, saya mendapati diri saya ingin bermain dengan cuplikan kode saat berada di ponsel saya, jauh dari desktop/laptop, cukup sering.

Saya tidak keberatan bidang <textarea> , alih-alih editor yang disorot sintaks untuk penggunaan seluler.

Kesalahan mungkin ada di halaman lain atau munculan atau elemen html lainnya.

Tags: taman bermain, ponsel, editor kode

Dokumen menambahkan ekstensi .js untuk modul es6 yang kompatibel dengan browser

Tidak disebutkan di mana pun bahwa TypeScript dapat digunakan dengan sangat baik untuk menghasilkan modul es6 yang berfungsi di browser hanya dengan menambahkan ekstensi .js ke nama impor! Satu-satunya tempat info ini tampaknya ada adalah di utas ini:
https://github.com/Microsoft/TypeScript/issues/16577#issuecomment -343610106

Tidak yakin versi TS mana yang menambahkannya, tetapi impor seperti './file.js' sekarang berfungsi (bahkan jika file tersebut sebenarnya adalah file.ts).

Bagi saya ini adalah fitur besar... tapi secara resmi itu tidak ada?!

Halaman Jenis Lanjutan tidak menyertakan jenis Omit<T, K> .

Omit<T, K> baru - Jenis Lanjutan masih memiliki penafian berikut:

Catatan: Jenis Kecualikan adalah implementasi yang tepat dari jenis Diff yang disarankan di sini. Kami telah menggunakan nama Kecualikan untuk menghindari pemecahan kode yang ada yang mendefinisikan Diff, ditambah lagi kami merasa nama itu menyampaikan semantik jenisnya dengan lebih baik. Kami tidak menyertakan Omitketik karena sepele ditulis sebagai Pick>.

Berikan dokumentasi penyiapan proyek untuk Linters

Sebagai bagian dari pengaturan proyek, sertakan cara mengatur dengan Linter, kemungkinan besar hanya TypeScript-eslint yang seharusnya digunakan oleh proyek itu sendiri.

Tag: linter

Tidak ada yang mencakup kesalahan yang paling sering terjadi atau batasan TypeScript.

Saat Anda pertama kali mempelajari TypeScript, ada pola tertentu yang tidak + tidak akan pernah didukung di TypeScript. Salah satu yang paling sederhana:

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

Saya sudah mulai memperkenalkan TypeScript ke perusahaan saya, dan kasus seperti ini sering muncul, jadi saya mulai mendokumentasikannya dalam panduan gaya FAQ/pemecahan masalah. Ini tumbuh dengan cepat (perhatikan bahwa ini dalam keadaan kasar):

Membangun objek satu properti pada satu waktu
Mengapa Anda tidak mendapatkan kesalahan saat Anda menginginkannya: pemeriksaan properti berlebih
Cara mengakses properti opsional, termasuk dari serikat pekerja
Mengapa Object.keys dan Object.entries tidak melakukan apa yang Anda inginkan
Membuat filter filter, mengurangi pekerjaan tanpa kesalahan
Penyempurnaan tipe hilang

Jika ada informasi ini dalam dokumen, saya belum dapat menemukannya. Saya hanya memahami ini melalui percobaan/kesalahan bertahun-tahun, dan membaca masalah yang paling banyak ditautkan di Github.

Tag: errors , troubleshooting , limitations

Berikan dokumentasi yang jelas tentang cara menambahkan definisi tipe khusus

Ada sejumlah perpustakaan yang tidak menyertakan tipe, dan yang tidak memiliki paket @types/* yang tersedia. Saya ingin dapat menulis file deklarasi saya sendiri untuk ini di dalam proyek saya, tetapi sepertinya tidak ada dokumentasi tentang cara 'benar' untuk menulisnya dan membuat TypeScript untuk mengenalinya. Katakanlah saya mengimpor modul dari npm. Apakah saya perlu menggunakan declare module x ? atau declare module "x" ? atau menggunakan namespace? atau hanya mengekspor jenisnya? Apakah ada tempat khusus yang saya perlukan untuk meletakkan file-file ini? Opsi konfigurasi apa yang perlu saya atur? typeRoots ? types ? paths ? include ? atau apa? - semua yang saya temukan sejauh ini adalah pesan kesalahan yang membingungkan, opsi konfigurasi yang dijelaskan dengan buruk, dan pertanyaan SO yang sudah ketinggalan zaman.

Tag: docs

Kurangnya dokumentasi offline

Alat dev dasar modern seperti git atau npm memiliki subset perintahnya sendiri yang memungkinkan kita mengakses dokumentasi/referensi offline, misalnya:

$ git help ls-remote
$ npm help search 

Saya pikir akan menyenangkan memiliki fitur seperti itu (walaupun TS-nya sedikit berbeda).
Itu akan memungkinkan kita untuk menjelajahi dokumen secara lokal melalui perintah seperti help tanpa perlu merujuk ke situs/github dll:

$ 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

Tag: offline , search , cli , local

Contoh membutuhkan beberapa warna pembeda yang lebih baik!

Bagaimana seharusnya:

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

Bagaimana keadaannya saat ini:

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

Ada sedikit warna biru, tapi itu saja.

Hai teman-teman, saya telah mengawasi masalah ini sambil memikirkan struktur situs umum dan dokumentasi keseluruhan selama sebulan terakhir. Sekarang setelah masalah ini teratasi, dan saya memiliki sedikit lebih banyak pemahaman tentang seperti apa tampilan dokumen yang saya inginkan.

Mari kita coba melihat semua poin ini berdasarkan reaksi, dengan sedikit mengacak agar mudah dibaca.

Dokumen API terkadang hanya ada di catatan rilis

Yang ini akan rumit, sebagian karena saat ini saya tidak yakin apa yang hanya ada di catatan rilis.

Sehubungan dengan bahasa dan sintaks, saya berharap ini diperbaiki dan ditingkatkan dengan buku pegangan baru yang akan datang yang mengambil tampilan baru di seluruh bahasa. Untuk sisa dokumentasi, saya pikir beberapa peta situs baru harus mencakup sebagian besar kasus - tetapi masih WIP

Tidak ada pencarian di situs web

Ya, saya setuju, yang satu ini sangat penting untuk situs baru.

Situs web adalah sumber tertutup

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

Pekerjaan baru akan keluar dari cabang master, tetapi untuk saat ini situs lama dapat diakses di atas dan mengambil PR. Saya telah memindahkan masalah dari repo TypeScript ke sini juga, jadi lebih mudah untuk melacak semuanya.

Halaman Utilitas tidak mutakhir

Tetap! Sebagian saya menggabungkan banyak PR, dan mendapatkan buku pegangan terkini dari komunitas. Serta memastikan bahwa itu akan muncul di nav (bukan hanya dari pencarian web)

Deskripsi opsi TS Config yang ditingkatkan

Saya mulai menjelajahi ini selama akhir pekan (bagaimana kami dapat memastikan bahwa kompiler dan situs web berbagi sumber data awal yang sama untuk dokumen ini, dan apa yang dapat dibangun situs web di atasnya untuk memberikan lebih banyak konteks)

Beberapa contoh arah sejauh ini:

• catatan saya sendiri dari 2017
• Saya telah mengobrol dengan Ethan Arrowood @matterhorndev yang tsconfig-ui-nya dapat menjadi dasar untuk membuat penjelajah TSConfig

Taman bermain tidak sebagus alternatif

Tetap! Saya menganggap ini sebagai batu loncatan positif ke arah umum yang saya inginkan sebagai taman bermain. Saya punya beberapa contoh maket yang memberikan perspektif jangka panjang tentang seperti apa tampilan dan nuansa Playground untuk membuatnya benar-benar berkembang biak.

( klik untuk eksplorasi figma )

URL singkat yang dapat dibagikan untuk taman bermain

Tetap, lihat di bawah

Tidak ada glosarium nama jenis

Saya sudah mulai menulis sendiri , saat saya mempelajari kompiler - saya berharap untuk melihat umpan ini ke dalam buku pegangan baru. Ini juga memengaruhi contoh taman bermain, yang berfungsi sebagai glosarium contoh untuk beberapa jenis yang lebih maju

[taman bermain ex1, taman bermain ex2]

Tidak mengajarkan TS secara bertahap

Ini ditujukan untuk dibahas dalam buku pegangan baru, untuk mengutip beberapa #29288 (gulir ke New handbook )

Menulis dokumen umum untuk semua pengguna sulit karena audiens TypeScript luas, dan salah satu kekuatan (dan kelemahan) dari buku pegangan saat ini adalah mencoba melayani semua orang sekaligus. Kami memiliki beberapa kelompok pengembang berbeda yang memiliki harapan berbeda saat mempelajari TypeScript, dan kami perlu menyesuaikan tingkat pemaparan konsep yang berbeda. Mengingat itu, tujuan kami adalah untuk mengatur buku pegangan menjadi tiga bagian yang berbeda:

1. Perkenalan yang disesuaikan (pengaturan untuk buku pegangan inti)
   
   
   
   1. Buku pegangan inti (semua orang membaca ini)
   
   
   2. Halaman referensi (seperti deep-dives/appendices)
   
   

Secara efektif ia memiliki beberapa titik awal yang berbeda dan kemudian mencoba untuk mengajarkan bahasa tersebut setelah Anda terbiasa dengan ekosistem di sekitarnya.

Apakah itu membahas semua yang ada di komentar? Tidak, hanya permulaan. Peta situs yang saya miliki saat ini cukup luas, dan ini adalah jenis masalah yang saya minati

Saya telah meninggalkan beberapa ruang gerak di buku masak dan panduan peta situs saya saat ini, dengan buku masak menjadi sesuatu yang dapat mendorong lebih banyak dukungan komunitas.

Berikan Panduan

Saya telah meluangkan waktu untuk mulai memilah dan memperbarui contoh kode saat ini yang saat ini ada di situs web TypeScript. Saya masih mencari tahu sampel mana yang lebih baik dibiarkan di pihak kita vs mengarahkan ulang ke dokumentasi resmi (misalnya jika sebuah proyek sekarang secara native mendukung TypeScript, dan mereka memiliki dokumen sendiri)

Seperti di atas, saya pikir bagian buku masak dan panduan sebenarnya dari situs harus cukup untuk membahas ini

Spesifikasi Bahasa sudah kedaluwarsa

Ya, saya tidak tahu apakah saya dapat menghapusnya langsung dari repo utama - tetapi itu tidak akan disebutkan di situs baru.

Berikan pengalaman seperti IDE yang lebih baik untuk contoh kode

Saat ini ada di situs buku pegangan baru , meskipun kita juga harus memindahkannya ke situs baru. Ini juga menyediakan penyorotan dan pesan kesalahan sebaris, yang saya sukai.

Halaman indeks kesalahan kompiler

Tidak yakin apakah ini akan terjadi, sebagian TypeScript memiliki banyak kode kesalahan dan mereka berubah cukup teratur. Layak untuk kembali setelah ada situs dan dokumen yang berfungsi penuh, tetapi untuk saat ini masih ada di belakang.

Tampilkan lebih banyak contoh dunia nyata

Buku pegangan baru sejauh ini melakukan pekerjaan dengan baik dalam hal ini 👍🏾 - kita dapat bertujuan untuk tetap seperti itu. Dengan sisa dokumen, saya akan mencoba mengubah apa pun yang saya lihat menjadi seperti itu.

Dukungan seluler di situs lemah

Saya sedang melihat penggunaan sistem desain Microsoft (cair) untuk situs baru, yang berarti bahwa dukungan seluler (dengan aksesibilitas) harus datang "sebagian besar gratis"

Dengan sesuatu yang serumit taman bermain yang sedikit lebih rumit, saya pikir untuk ponsel berukuran ponsel, pola pikir penjelajahan/eksplorasi sangat cocok. Jadi, saya memiliki mockup yang sedikit lebih dekat dengan pengalaman hanya-baca:

Jelajahi peningkatan bantuan tsc

Saya terbuka untuk ini, tetapi TypeScript CLI benar-benar hanya satu perintah, kompilasi (itulah sebabnya tidak perlu bantuan pada sub-perintah (meskipun --init agak merusaknya))

Berikan saran untuk meningkatkan DTS

Ya, saya berencana menggabungkan situs web yang pasti diketik ke dalam situs web TypeScript dan menggabungkan dokumen-dokumen itu. Apakah _semua_ dari mereka akan hidup di situs masih diperdebatkan. Ada beberapa alasan bagus untuk menjaga detail implementasi aktual untuk berkontribusi dalam repo yang diketik dengan pasti, sementara ikhtisar tingkat tinggi dapat hidup di situs.

Konsolidasi dokumen/blog/catatan rilis

Yang rumit, saya tidak punya jawaban untuk blog/catatan rilis. Kami menggunakan sistem blog produk Microsoft dengan orang lain, dan saya tidak yakin apakah itu ide yang baik untuk memindahkan semua itu ke situs web itu sendiri. Kita bisa mengetahui yang satu itu lebih dekat dengan waktu.

Di sisi yang lebih mudah, saya pasti ingin menghapus informasi semacam ini dari wiki dan membiarkannya hanya di dalam situs web (di mana ia dapat diindeks oleh pencarian situs) - Saya ingin meninggalkan wiki TypeScript khusus untuk berkontribusi pada TypeScript dan bekerja dengan API kompiler TypeScript (misalnya ketika Anda import * as ts from “typescript” , atau membuat plugin server bahasa)

Tutupi kesalahan yang paling sering terjadi

Ini berkaitan dengan hal di atas - ada halaman FAQ yang sangat luas untuk masalah semacam ini, yang baru saja saya temukan di wiki (3 tahun penggunaan TS saya).

Kami dapat mengambil ini sebagai dasar dan mulai menarik mereka ke situs web utama dengan tanggapan Anda juga

Tambahkan penyorotan sintaks

Ya setuju, terima kasih!

Secara keseluruhan, saya pikir kami memiliki banyak dari ini yang sedang dieksplorasi atau dikerjakan secara aktif, dan saya terbuka untuk lebih banyak umpan balik saat kami terus mengerjakan dokumen!

Kerja yang luar biasa, terima kasih banyak @orta !

Bagaimana dengan meminjam/meningkatkan/berkolaborasi dengan pengalaman tsconfig VSCode di editor Playground, alih-alih membuat yang terpisah?

Membuat Playground lebih baik, dan pengalaman yang ada di VSCode sudah setengah layak.

Saya tidak begitu yakin apa yang Anda maksud. Suka fitur skema JSON pelengkapan otomatis di VS Code? Saya berencana memilikinya di bagian editor JSON, tetapi gambaran umum dari setiap opsi sebagai GUI dengan label adalah cara yang berguna untuk melihat semua opsi dan memilih.

@orta Ketika buku pegangan baru menjadi buku pegangan resmi, apakah URL yang menunjuk ke bagian dari buku pegangan saat ini akan rusak? Atau akankah buku pegangan baru berada di URL yang berbeda? Saya hanya ingin tahu karena saya telah menaruh banyak tautan buku pegangan dalam jawaban SO selama beberapa tahun terakhir (saya yakin orang lain juga melakukan ini) dan akan sangat disayangkan jika semuanya rusak. (Apakah ada masalah atau lokasi yang lebih baik untuk dibicarakan tentang rencana migrasi dokumentasi umum?)

@orta @jcalz Bertanya-tanya hal yang sama, saya memiliki lebih dari 2.5K SO jawaban, menemukan semua jawaban dengan tautan dan memperbarui semuanya tidak layak. Idealnya tautan dengan fragmen akan tetap berfungsi dan dialihkan ke lokasi baru. Saya bersedia membantu pemetaan jika diperlukan.

Ya, saya tidak percaya pada pemecahan URI - ada beberapa opsi untuk dijelajahi.

Saya pikir kemungkinan akan menggunakan root URL baru untuk buku pegangan (misalnya bukan docs/handbook/x.html tapi mungkin /handbook/x.html ), dan membuat halaman yang lebih lama mengarahkan ulang ke padanan terdekatnya melalui peta sejenis.

Saya ingin tahu apa arti semua label github untuk repositori ini. Beberapa dari mereka cukup jelas, tetapi yang lain tidak.

Misalnya, "Memerlukan Proposal" tidak jelas bagi saya. Ini akan membantu semua label untuk memiliki deskripsi yang lebih panjang seperti yang sudah dilakukan beberapa orang.

Tidak dapat menautkan ke dokumen untuk opsi kompiler _spesifik_

Tim saya relatif baru dalam TypeScript, dan karena itu, tsconfig.json sering berubah, dan seringkali saya ingin mengarahkan orang ke dokumentasi untuk opsi kompiler tertentu, yaitu dalam bentuk:

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

Tautan seperti ini tidak berfungsi, tetapi saya ingin mereka melakukannya.

Saat ini satu-satunya id HTML yang dapat saya lihat di halaman itu adalah #compiler-options, yang tidak begitu berguna karena pada dasarnya berada di bagian paling atas - memiliki id untuk setiap opsi, bagaimanapun, akan sangat membantu untuk membuat orang bagian halaman yang diinginkan.

Tag: compiler

@Tyler-Murphy kami telah memperbaikinya sekarang

@ssalka - ya, panggilan bagus yang akan ada di dokumen tsconfig baru

--

Saya akan menutup masalah ini, saya akan membuka kembali yang baru di masa depan dengan premis yang sama setelah kita masuk lebih jauh ke dalam buku pegangan dan situs baru 👍

Taman Bermain TypeScript:
Saya merasa seperti menjadi gila tetapi saya tidak dapat menemukan opsi 'Bagikan' sederhana untuk menyimpan dan membagikan proyek saya (mis. untuk menambah masalah github).
Saya melihat semua tautan di bawah 'Ekspor' tetapi tidak ada 'Bagikan'.

Taman Bermain TypeScript:
Saya merasa seperti menjadi gila tetapi saya tidak dapat menemukan opsi 'Bagikan' sederhana untuk menyimpan dan membagikan proyek saya (mis. untuk menambah masalah github).
Saya melihat semua tautan di bawah 'Ekspor' tetapi tidak ada 'Bagikan'.

Contoh: Tautan Taman Bermain

Situs baru terlihat sangat bagus! Namun saya perhatikan permintaan ini (tautan jangkar untuk opsi kompiler) tidak berhasil di

Sepertinya itu akan menjadi permintaan yang sangat mudah untuk diakomodasi dan akan sangat membantu bagi pendatang baru. Berharap untuk melihatnya di pembaruan mendatang!