Repositori untuk definisi tipe TypeScript berkualitas tinggi .
Anda juga dapat membaca README ini dalam bahasa Español, 한국어, Русский, 简体中文, Português, Italiano, 日本語 dan Français!
Tautan ke panduan Admin
Pasti Diketik baru-baru ini diubah menjadi monorepo pnpm yang tepat; Anda mungkin ingin membaca ulang dokumen ini untuk mengetahui perubahan tata letak paket di repo ini.
Paling tidak, Anda mungkin ingin git clean -fdx repo (atau node ./scripts/clean-node-modules.js di Windows) untuk membersihkan node_modules dan menjalankan pnpm install --filter . untuk menginstal root ruang kerja. Lihat bagian selanjutnya untuk informasi lebih lanjut tentang pnpm install .
Bagian ini melacak kesehatan repositori dan proses penerbitan. Ini mungkin berguna bagi kontributor yang mengalami masalah apa pun dengan PR dan paket mereka.
Jika ada yang salah di sini atau salah satu cara di atas gagal, beri tahu kami di saluran Pasti Diketik di server TypeScript Community Discord.
Lihat buku pegangan TypeScript.
Ini adalah metode yang disukai. Misalnya:
npm install --save-dev @types/node Untuk menginstal pengetikan pada modul tercakup, hapus @ dan tambahkan garis bawah ganda setelah cakupan. Misalnya, untuk menginstal pengetikan untuk @babel/preset-env :
npm install --save-dev @types/babel__preset-env Tipe-tipe tersebut kemudian harus secara otomatis disertakan oleh kompiler. Anda mungkin perlu menambahkan referensi types jika Anda tidak menggunakan modul:
/// <reference types="node" />Lihat lebih lanjut di buku pegangan.
Untuk paket npm "foo", pengetikannya akan berada di "@types/foo".
Jika paket Anda memiliki pengetikan yang ditentukan menggunakan kunci types atau typings di package.json -nya, registri npm akan menampilkan bahwa paket tersebut memiliki ikatan yang tersedia seperti:
Anda dapat mengkloning seluruh repositori seperti biasa, tetapi repositori itu besar dan mencakup direktori paket tipe yang sangat besar. Ini akan memerlukan waktu untuk dikloning dan mungkin terlalu berat.
Untuk klon yang lebih mudah dikelola dan hanya menyertakan paket tipe yang relevan bagi Anda, Anda dapat menggunakan fitur sparse-checkout dan --filter git. Ini akan mengurangi waktu kloning dan meningkatkan kinerja git.
️ Ini memerlukan minimum git versi 2.27.0, yang mungkin lebih baru daripada default pada kebanyakan mesin. Prosedur yang lebih rumit tersedia di versi lama, namun tidak tercakup dalam panduan ini.
git clone --sparse --filter=blob:none <forkedUrl>--sparse menginisialisasi file sparse-checkout sehingga direktori kerja dimulai hanya dengan file di root repositori.--filter=blob:none akan menyertakan semua riwayat penerapan tetapi mengecualikan file, mengambilnya hanya jika diperlukan.git sparse-checkout add types/<type> types/<dependency-type> ...pnpm test <package to test> . Saat Anda membuat PR untuk mengedit paket yang ada, dt-bot harus @-menyebut pemilik paket. Jika tidak, Anda dapat melakukannya sendiri di komentar terkait PR.
Jika Anda adalah penulis perpustakaan dan paket Anda ditulis dalam TypeScript, gabungkan file deklarasi yang dihasilkan dalam paket Anda alih-alih menerbitkannya ke Diketik Pasti. Anda juga dapat membuat file deklarasi dari file JavaScript, menggunakan JSDoc untuk anotasi tipe.
Jika Anda menambahkan pengetikan untuk paket npm, buatlah direktori dengan nama yang sama. Jika paket yang Anda tambahkan pengetikannya tidak ada di npm, pastikan nama yang Anda pilih tidak bertentangan dengan nama paket di npm. (Anda dapat menggunakan npm info <my-package> untuk memeriksa keberadaan paket <my-package> .)
Paket Anda harus memiliki struktur ini:
| Mengajukan | Tujuan |
|---|---|
index.d.ts | Ini berisi pengetikan untuk paket tersebut. |
<my-package>-tests.ts | Ini berisi kode contoh yang menguji pengetikan. Kode ini tidak berjalan, tetapi dicentang jenisnya. |
tsconfig.json | Ini memungkinkan Anda menjalankan tsc di dalam paket. |
.eslintrc.json | (Jarang) Hanya diperlukan untuk menonaktifkan aturan lint yang ditulis untuk eslint. |
package.json | Berisi metadata untuk paket, termasuk nama, versi, dan dependensinya. |
.npmignore | Menentukan file mana yang dimaksudkan untuk disertakan dalam paket. |
Hasilkan ini dengan menjalankan npx dts-gen --dt --name <my-package> --template module . Lihat semua opsi di dts-gen.
Jika Anda memiliki file .d.ts selain index.d.ts , pastikan file tersebut direferensikan di index.d.ts atau pengujian.
Anggota Pasti Diketik secara rutin memantau PR baru, namun perlu diingat bahwa jumlah PR lain mungkin memperlambat segalanya.
Untuk contoh paket yang bagus, lihat base64-js.
Ketika sebuah paket menggabungkan tipenya sendiri, tipenya harus dihapus dari Diketik Pasti untuk menghindari kebingungan.
Anda dapat menghapusnya dengan menjalankan pnpm run not-needed <typingsPackageName> <asOfVersion> [<libraryName>] .
<typingsPackageName> : Ini adalah nama direktori yang akan dihapus.<asOfVersion> : Sebuah rintisan akan dipublikasikan ke @types/<typingsPackageName> dengan versi ini. Harus lebih tinggi dari versi apa pun yang diterbitkan saat ini dan harus berupa versi <libraryName> di npm.<libraryName> : Nama paket npm yang menggantikan tipe yang Diketik Pasti. Biasanya ini identik dengan <typingsPackageName> , dalam hal ini Anda dapat menghilangkannya. Jika sebuah paket belum pernah diketik Pasti, maka paket tersebut tidak perlu ditambahkan ke notNeededPackages.json .
Uji perubahan Anda dengan menjalankan pnpm test <package to test> dengan <package to test> adalah nama paket Anda. Anda perlu menjalankan ini dari direktori PastiTyped karena masing-masing package.jsons tidak menentukan skrip pengujian.
Skrip ini menggunakan dtslint untuk menjalankan kompiler TypeScript terhadap file dts Anda.
Setelah semua perubahan Anda siap, gunakan pnpm run test-all untuk melihat bagaimana perubahan Anda memengaruhi modul lainnya.
attw ) memeriksa dtslint menyertakan format modul dan pemeriksaan konfigurasi package.json dari @arethetypeswrong/cli. Pemeriksaan hanya dijalankan jika paket implementasi yang kompatibel dengan SemVer-mayor dapat ditemukan di npm untuk dibandingkan dengan paket PastiTyped. (Paket dengan tipe pasti yang ditandai sebagai nonNpm di package.json dilewati.)
Banyak paket saat ini gagal dalam pemeriksaan attw dan perlu diperbaiki. Untuk memungkinkan kita membuat kemajuan tambahan, pemeriksaan attw yang gagal tidak akan menggagalkan proses dtslint ketika paket terdaftar dalam failingPackages di attw.json , namun pemeriksaan tersebut masih akan dilaporkan dalam keluaran pnpm test my-package . Jika Anda memperbaiki paket, hapus paket tersebut dari failingPackages sehingga pemeriksaan attw dapat memulai kegagalan menjalankan dtslint .
Semua masalah yang dilaporkan oleh attw memiliki dokumentasi yang ditautkan dalam outputnya. Beberapa aturan praktis untuk membantu menghindari masalah:
package.json dalam paket PastiTyped harus memiliki bidang type dan exports yang cocok jika paket implementasi menggunakannya dalam package.json -nya. Misalnya, jika implementasi package.json terlihat seperti:
{
"name" : " my-package " ,
"version" : " 1.0.1 " ,
"type" : " module " ,
"main" : " dist/cjs/index.cjs " ,
"exports" : {
"." : {
"import" : " ./dist/esm/index.js " ,
"require" : " ./dist/cjs/index.cjs "
},
"./subpath" : {
"import" : " ./dist/esm/subpath.js " ,
"require" : " ./dist/cjs/subpath.cjs "
}
}
} maka package.json PastiTyped akan terlihat seperti:
{
"name" : "@types/my-package" ,
"version" : "1.0.9999" ,
"type" : "module" ,
"types" : "index.d.ts" ,
"exports" : {
"." : {
"import" : "./index.d.ts" ,
"require" : "./index.d.cts"
} ,
"./subpath" : {
"import" : "./subpath.d.ts" ,
"require" : "./subpath.d.cts"
}
}
} Perhatikan bahwa setiap subjalur exports tercermin, dan setiap file JavaScript memiliki file deklarasi yang sesuai dengan ekstensi file yang cocok—file .d.ts mengetikkan file .js , bukan file .mjs atau .cjs !
Ketika paket implementasi menggunakan module.exports = ... , paket PastiTyped harus menggunakan export = , bukan export default . (Atau, jika module.exports hanyalah sebuah objek dari properti bernama, paket PastiTyped dapat menggunakan serangkaian ekspor bernama.) Hambatan paling umum untuk memperbaiki masalah ini adalah kebingungan tentang cara mengekspor jenis selain ekspor utama. Misalnya, asumsikan jenis ini salah menggunakan export default :
export interface Options {
// ...
}
export default function doSomething ( options : Options ) : void ; Mengubah export default ke export = menghasilkan kesalahan:
export interface Options {
// ...
}
declare function doSomething ( options : Options ) : void ;
export = doSomething ;
// ^^^^^^^^^^^^^^^^^
// Error: An export assignment cannot be used in a module with other exported elements.Untuk memperbaikinya, pindahkan tipe ke dalam namespace dengan nama yang sama dengan fungsinya:
declare namespace doSomething {
export interface Options {
// ...
}
}
declare function doSomething ( options : doSomething . Options ) : void ;
export = doSomething ;Jika Anda memerlukan bantuan untuk memperbaiki masalah, silakan bertanya di saluran DefinateTyped di server TypeScript Community Discord.
Jika Anda menambahkan pengetikan untuk paket npm, buatlah direktori dengan nama yang sama. Jika paket yang Anda tambahkan pengetikannya tidak ada di npm, setel "nonNpm": true di package.json , dan pastikan nama yang Anda pilih tidak bertentangan dengan nama paket di npm. (Anda dapat menggunakan npm info <my-package> untuk memeriksa keberadaan paket <my-package> .)
Dalam kejadian yang jarang terjadi, nonNpm dapat disetel ke "conflict" , yang menunjukkan bahwa ada paket di npm dengan nama yang sama, tetapi tipenya sengaja bertentangan dengan paket tersebut. Hal ini berlaku untuk paket yang mendefinisikan lingkungan seperti @types/node atau untuk paket tiruan seperti aws-lambda . Hindari penggunaan "conflict" jika memungkinkan.
<my-package>-tests.ts Harus ada file <my-package>-tests.ts , yang dianggap sebagai file pengujian Anda, bersama dengan file *.ts apa pun yang diimpornya. Jika Anda tidak melihat file pengujian apa pun di folder modul, buatlah <my-package>-tests.ts . File-file ini digunakan untuk memvalidasi API yang diekspor dari file *.d.ts yang dikirimkan sebagai @types/<my-package> . Mereka tidak mengirim sendiri.
Perubahan pada file *.d.ts harus menyertakan perubahan file *.ts terkait yang menunjukkan API yang sedang digunakan, sehingga seseorang tidak secara tidak sengaja memecahkan kode yang Anda andalkan. Misalnya, perubahan pada fungsi dalam file .d.ts menambahkan parameter baru ke suatu fungsi:
index.d.ts :
- export function twoslash(body: string): string
+ export function twoslash(body: string, config?: { version: string }): string <my-package>-tests.ts :
import {twoslash} from "./"
// $ExpectType string
const result = twoslash("//")
+ // Handle options param
+ const resultWithOptions = twoslash("//", { version: "3.7" })
+ // When the param is incorrect
+ // @ts-expect-error
+ const resultWithOptions = twoslash("//", { })Jika Anda bertanya-tanya harus mulai dari mana dengan kode pengujian, contoh di README paket asli adalah awal yang baik.
Anda dapat memvalidasi perubahan Anda dengan npm test <package to test> dari root repo ini, yang memperhitungkan file yang diubah.
Gunakan $ExpectType untuk menegaskan bahwa ekspresi adalah tipe tertentu dan @ts-expect-error untuk menegaskan bahwa kesalahan kompilasi. Contoh:
// $ExpectType void
f ( 1 ) ;
// @ts-expect-error
f ( "one" ) ;Untuk lebih jelasnya, lihat dtslint readme.
.eslintrc.jsonJika karena alasan tertentu aturan lint perlu dinonaktifkan, nonaktifkan aturan tersebut untuk baris tertentu:
// eslint-disable-next-line no-const-enum
const enum Const {
One ,
}
const enum Enum { // eslint-disable-line no-const-enum
Two ,
}Anda masih dapat menonaktifkan aturan dengan .eslintrc.json, tetapi tidak boleh dalam paket baru. Menonaktifkan aturan untuk keseluruhan paket mempersulit peninjauan.
tsconfig.json tsconfig.json harus memiliki noImplicitAny , noImplicitThis , strictNullChecks dan strictFunctionTypes disetel ke true .
Anda dapat mengedit tsconfig.json untuk menambahkan file pengujian baru, untuk menambahkan "target": "es6" (diperlukan untuk fungsi async), untuk menambahkan ke "lib" atau untuk menambahkan opsi kompiler "jsx" .
esModuleInterop / allowSyntheticDefaultImports TL;DR: esModuleInterop allowSyntheticDefaultImports tidak diperbolehkan di tsconfig.json Anda.
Opsi ini memungkinkan penulisan impor default untuk ekspor CJS, memodelkan interoperabilitas bawaan antara modul CJS dan ES di Node dan di beberapa bundler JS:
// component.d.ts declare class Component { } // CJS export, modeling `module.exports = Component` in JS export = Component ; // index.d.ts // ESM default import, only allowed under 'esModuleInterop' or 'allowSyntheticDefaultExports' import Component from "./component" ;Karena validitas waktu kompilasi dari impor di
index.d.tsbergantung pada pengaturan kompilasi tertentu, yang tidak diwarisi oleh pengguna tipe Anda, menggunakan pola ini di PastiTyped akan memaksa pengguna untuk mengubah pengaturan kompilasi mereka sendiri, yang mungkin salah untuk waktu proses mereka. Sebagai gantinya, Anda harus menulis impor CJS untuk ekspor CJS guna memastikan kompatibilitas yang luas dan tidak bergantung pada konfigurasi:// index.d.ts // CJS import, modeling `const Component = require("./component")` in JS import Component = require ( "./component" ) ;
package.jsonFile ini diperlukan dan harus mengikuti templat ini:
{
"private" : true ,
"name" : "@types/PACKAGE-NAME" ,
"version" : "1.2.9999" ,
"projects" : [
"https://aframe.io/"
] ,
"dependencies" : {
"@types/DEPENDENCY-1" : "*" ,
"@types/DEPENDENCY-2" : "*"
} ,
"devDependencies" : {
"@types/PACKAGE-NAME" : "workspace:."
} ,
"owners" : [
{
"name" : "Your Name Here" ,
"githubUsername" : "ghost"
}
]
} package.json menentukan semua dependensi, termasuk paket @types lainnya.
Anda harus menambahkan dependensi non- @types ke daftar dependensi eksternal yang diizinkan. Pikaday adalah contoh yang bagus. Penambahan ini disetujui oleh pengelola, yang memberi kita kesempatan untuk memastikan bahwa paket @types tidak bergantung pada paket jahat.
Jika paket implementasi menggunakan ESM dan menentukan "type": "module" , maka Anda harus memodifikasi package.json agar sesuai:
{
"type" : " module "
} Hal ini juga berlaku jika paket implementasi memiliki exports di package.json-nya.
Diketik Pasti memungkinkan peerDependencies di package.json . Ketergantungan rekan dapat membantu mencegah situasi di mana manajer paket tiba-tiba menginstal versi yang terlalu baru atau lebih dari satu versi dari paket yang sama. Namun, ketergantungan terhadap rekan mempunyai kelemahan; manajer paket berbeda dalam menangani dependensi rekan (misalnya, yarn tidak menginstalnya secara otomatis, npm memerlukan --legacy-peer-deps jika ada ketidakcocokan). Oleh karena itu, PR yang memperkenalkan ketergantungan rekan baru memerlukan persetujuan pengelola dan harus dibatasi pada keadaan tertentu.
Secara umum, paket tipe hanya boleh memiliki ketergantungan peer jika paket upstream memiliki ketergantungan peer pada paket (atau tipenya) yang sama. Misalnya, paket DT untuk komponen React dapat menentukan ketergantungan peer pada @types/react@* , karena konsumen harus menginstal @types/react untuk menggunakan JSX terlebih dahulu. Jika konsumen menginstal @types/react@16 di proyek mereka, tetapi versi @types/react yang lebih baru tersedia di npm, ketergantungan rekan dapat membantu manajer paket memilih @types/react@16 daripada versi yang lebih baru tersebut. Demikian pula, chai-as-promised memiliki ketergantungan rekan pada chai , jadi @types/chai-as-promised harus memiliki ketergantungan rekan pada @types/chai .
Ada beberapa kasus di mana paket upstream tidak memiliki ketergantungan peer pada paket tipe, namun ketergantungan peer masih sesuai. Ini biasanya merupakan kasus di mana paket upstream memperluas paket lain dan menganggapnya ada, jadi seharusnya mendeklarasikan ketergantungan rekan saat paket tersebut memperluas paket lain, namun ternyata tidak. Misalnya, chai-match-pattern memperluas chai , tetapi tidak mendeklarasikan ketergantungan rekan pada chai , tetapi membutuhkannya agar berfungsi. @types/chai-match-pattern harus memiliki ketergantungan rekan pada @types/chai .
Jika sebuah paket hanya mengekspos tipe dari paket lain sebagai bagian dari API-nya karena ketergantungan reguler pada paket upstream, maka paket tersebut tidak boleh menggunakan ketergantungan rekan. Misalnya, express memiliki qs dalam "dependencies" -nya. Saat pengguna menginstal express , mereka tidak perlu menginstal qs secara manual. Demikian pula, @types/express memiliki @types/qs di "dependencies" -nya. Tidaklah benar jika mendeklarasikan @types/qs sebagai ketergantungan rekan dari @types/express , karena hal tersebut mengharuskan beberapa konsumen hilir untuk menginstal @types/qs secara manual.
.npmignore File ini menentukan file mana yang akan disertakan dalam setiap paket @types . Itu harus mengambil bentuk tertentu. Untuk paket dengan hanya satu versi di repo:
*
! ** / * .d.ts
! ** / * .d.cts
! ** / * .d.mts
! ** / * .d. * .tsArtinya "abaikan semua file, tapi jangan abaikan file deklarasi apa pun". Untuk paket yang memiliki lebih dari satu versi di repo, versi "terbaru" (di tingkat atas) harus berisi sesuatu seperti:
*
! ** / * .d.ts
! ** / * .d.cts
! ** / * .d.mts
! ** / * .d. * .ts
/ v15 /
/ v16 /
/ v17 / Yang sama dengan .npmignore sebelumnya tetapi mengabaikan setiap direktori anak yang berversi.
CI akan gagal jika file ini berisi konten yang salah dan memberikan nilai yang diinginkan. Apa pun isi file ini, penerbit hanya akan menerbitkan file deklarasi.
pnpm dprint fmt -- 'path/to/package/**/*.ts' ..vscode/settings.template.json (atau yang setara untuk editor lain) untuk memformat penyimpanan dengan ekstensi dprint VS Codefunction sum(nums: number[]): number : Gunakan ReadonlyArray jika suatu fungsi tidak menulis ke parameternya.interface Foo { new(): Foo; } : Ini mendefinisikan tipe objek yang bisa baru. Anda mungkin ingin declare class Foo { constructor(); } .const Class: { new(): IClass; } : Lebih suka menggunakan deklarasi kelas class Class { constructor(); } alih-alih konstanta baru.getMeAT<T>(): T : Jika parameter tipe tidak muncul di tipe parameter apa pun, Anda sebenarnya tidak memiliki fungsi generik, Anda hanya memiliki pernyataan tipe yang disamarkan. Lebih suka menggunakan pernyataan tipe nyata, misalnya getMeAT() as number . Contoh di mana parameter tipe dapat diterima: function id<T>(value: T): T; . Contoh yang tidak dapat diterima: function parseJson<T>(json: string): T; . Pengecualian: new Map<string, number>() tidak masalah.Function dan Object hampir tidak pernah merupakan ide bagus. Dalam 99% kasus, dimungkinkan untuk menentukan tipe yang lebih spesifik. Contohnya adalah (x: number) => number untuk fungsi dan { x: number, y: number } untuk objek. Jika tidak ada kepastian sama sekali mengenai jenisnya, any adalah pilihan yang tepat, bukan Object . Jika satu-satunya fakta yang diketahui tentang tipe tersebut adalah bahwa itu adalah suatu objek, gunakan tipe tersebut object , bukan Object atau { [key: string]: any } .var foo: string | any : Ketika any digunakan dalam tipe gabungan, tipe yang dihasilkan tetap any . Jadi, meskipun bagian string dari anotasi tipe ini mungkin terlihat berguna, sebenarnya bagian ini tidak menawarkan pemeriksaan tipe tambahan selain menggunakan any . Tergantung pada niatnya, alternatif yang dapat diterima dapat any , string , atau string | object .TL;DR: jangan ubah
.github/CODEOWNERS, selalu ubah daftar pemilik dipackage.json.
DT memiliki konsep “Definition Owners” yaitu orang-orang yang ingin menjaga kualitas suatu jenis modul tertentu.
Untuk menambahkan diri Anda sebagai Pemilik Definisi, ubah array owners di package.json :
"owners" : [
{
"name" : " Some Person " ,
"githubUsername" : " somebody "
},
{
"name" : " Some Corp " ,
"url" : " https://example.org "
}
]Perhatikan bahwa daftar ini tidak digunakan untuk memberikan kredit atas kontribusi; ini hanya digunakan untuk mengelola tinjauan PR.
Seminggu sekali Pemilik Definisi disinkronkan ke file .github/CODEOWNERS yang merupakan sumber kebenaran kami.
Pasti Diketik adalah salah satu repositori paling aktif di GitHub. Anda mungkin bertanya-tanya bagaimana proyek ini bisa terwujud. @johnnyreilly menulis sejarah Pasti Diketik. Ini menceritakan kisah hari-hari awal Pasti Diketik, dari repositori yang dibuat oleh @borisyankov, hingga menjadi bagian penting dari ekosistem TypeScript. Cerita Pasti Diketik bisa kamu baca di sini.
@types di npm? Cabang master secara otomatis dipublikasikan ke lingkup @types di npm berkat alat PastiTyped.
Tergantung, tetapi sebagian besar permintaan penarikan akan digabungkan dalam waktu seminggu. Beberapa PR dapat digabungkan oleh pemilik modul dan dapat digabungkan lebih cepat. Dengan kasar:
PR yang hanya mengubah jenis modul dan memiliki perubahan pengujian yang sesuai akan digabungkan lebih cepat
PR yang telah disetujui oleh pemilik yang tercantum dalam definisi package.json biasanya digabungkan lebih cepat; PR untuk definisi baru akan membutuhkan lebih banyak waktu karena memerlukan lebih banyak peninjauan dari pengelola. Setiap PR ditinjau oleh anggota tim TypeScript atau Pasti Diketik sebelum digabungkan, jadi harap bersabar karena faktor manusia dapat menyebabkan penundaan. Periksa Papan Status Permintaan Tarik Baru untuk melihat kemajuan saat pengelola bekerja melalui PR terbuka.
Untuk perubahan pada modul yang sangat populer, misalnya Node/Express/Jest yang memiliki jutaan unduhan setiap minggunya di npm, persyaratan kontribusinya sedikit lebih tinggi. Perubahan pada proyek-proyek ini dapat menimbulkan dampak ekosistem yang besar sehingga kami memperlakukan perubahan tersebut dengan sangat hati-hati. Modul-modul ini memerlukan persetujuan dari pengelola DT dan dukungan antusias dari pemilik modul. Batasan untuk melewati hal ini bisa sangat tinggi dan seringkali PR menjadi basi karena tidak memiliki juara. Jika Anda menemukan bahwa tidak ada seorang pun yang berkomitmen, cobalah untuk membuat PR Anda memiliki fokus yang lebih kecil.
@types npm akan diperbarui?Paket npm akan diperbarui dalam waktu satu jam. Jika sudah lebih dari satu jam, sebutkan nomor PR pada saluran Pasti Diketik di server TypeScript Community Discord dan pengelola saat ini akan meminta anggota tim yang tepat untuk menyelidikinya.
<reference types="" /> atau impor? Jika modul yang Anda referensikan adalah modul (menggunakan export ), gunakan impor. Jika modul yang Anda referensikan adalah modul ambien (menggunakan declare module ) atau hanya mendeklarasikan global, gunakan <reference types="" /> .
tsconfig.json yang tidak memiliki "noImplicitAny": true , "noImplicitThis": true atau "strictNullChecks": true .Maka mereka salah dan kita belum menyadarinya. Anda dapat membantu dengan mengirimkan permintaan penarikan untuk memperbaikinya.
Ya, menggunakan dprint. Kami merekomendasikan penggunaan ekstensi dprint untuk editor Anda.
Alternatifnya, Anda dapat mengaktifkan git hook yang akan memformat kode Anda secara otomatis. Jalankan pnpm run setup-hooks . Kemudian, ketika Anda melakukan, perintah dprint fmt akan dijalankan pada file yang diubah. Jika Anda memanfaatkan klon parsial, pastikan untuk memanggil git sparse-checkout add .husky untuk memeriksa git hooks sebelum menjalankan skrip setup-hooks .
Permintaan tarik tidak memerlukan pemformatan yang benar untuk digabungkan. Kode apa pun yang belum diformat akan diformat ulang secara otomatis setelah digabungkan.
Jika Anda pengguna VS Code, sebaiknya salin file
.vscode/settings.template.jsonke.vscode/settings.json. Templat itu menetapkan ekstensi dprint VS Code sebagai pemformat default di repo.
Berikut adalah definisi yang diminta saat ini.
Jika tipe merupakan bagian dari standar web, tipe tersebut harus dikontribusikan ke TypeScript-DOM-lib-generator sehingga dapat menjadi bagian dari lib.dom.d.ts default.
Jika tidak ada kode JavaScript sumber sama sekali, misalnya jika Anda menulis tipe pembantu atau tipe untuk suatu spesifikasi, Anda harus mempublikasikan tipe tersebut sendiri, bukan pada Diketik Pasti. Karena dimaksudkan untuk menyediakan tipe untuk kode JavaScript yang ada, paket @types tidak dimaksudkan untuk diimpor secara langsung. Artinya, Anda tidak boleh membuat paket Pasti Diketik yang dimaksudkan untuk digunakan seperti import type { ... } from "@types/foo" . Anda juga tidak boleh berharap untuk menulis import type { ... } from "foo" ketika tidak ada foo yang diinstal.
Ini berbeda dengan menyediakan tipe untuk pustaka JavaScript khusus browser atau tipe untuk seluruh lingkungan seperti node, bun, dkk. Di sana, tipe-tipe tersebut diselesaikan secara implisit atau menggunakan /// <references types="foo" /> .
Beberapa paket, seperti chai-http, mengekspor suatu fungsi.
Mengimpor modul ini dengan gaya ES6 import dalam bentuk import * as foo from "foo"; menyebabkan kesalahan:
kesalahan TS2497: Modul 'foo' ditetapkan menjadi entitas non-modul dan tidak dapat diimpor menggunakan konstruksi ini.
Kesalahan ini dapat diatasi dengan menggabungkan deklarasi fungsi dengan namespace kosong dengan nama yang sama, namun praktik ini tidak disarankan. Ini adalah jawaban Stack Overflow yang sering dikutip mengenai masalah ini.
Lebih tepat mengimpor modul menggunakan import foo = require("foo"); sintaksis. Namun demikian, jika Anda ingin menggunakan impor default seperti import foo from "foo"; Anda memiliki dua opsi:
--allowSyntheticDefaultImports jika runtime modul Anda mendukung skema interop untuk modul non-ECMAScript, yaitu jika impor default berfungsi di lingkungan Anda (misalnya Webpack, SystemJS, esm).--esModuleInterop jika Anda ingin TypeScript menangani interop non-ECMAScript (sejak TypeScript 2.7). export = , tapi saya lebih suka menggunakan impor default. Bisakah saya mengubah export = menjadi export default ? Seperti pada pertanyaan sebelumnya, lihat penggunaan opsi kompiler --allowSyntheticDefaultImports atau --esModuleInterop .
Jangan mengubah definisi tipe jika akurat. Untuk paket npm, export = akurat jika node -p 'require("foo")' berfungsi untuk mengimpor modul dan export default akurat jika node -p 'require("foo").default' berfungsi untuk mengimpor modul .
Kemudian Anda akan menyetel versi minimum yang didukung dengan menentukan "minimumTypeScriptVersion": "XY" di package.json .
Namun, jika proyek Anda perlu mempertahankan tipe yang kompatibel dengan, katakanlah, 3.7 dan yang lebih baru secara bersamaan dengan tipe yang kompatibel dengan 3.6 atau yang lebih rendah, Anda perlu menggunakan fitur typesVersions . Anda dapat menemukan penjelasan mendetail tentang fitur ini di dokumentasi resmi TypeScript.
Berikut ini contoh singkat untuk membantu Anda memulai:
Anda harus menambahkan typesVersions ke package.json :
{
"private" : true ,
"types" : " index " ,
"typesVersions" : {
"<=3.6" : { "*" : [ " ts3.6/* " ] }
}
} Buat subdirektori yang disebutkan di bidang typesVersions di dalam direktori Type Anda ( ts3.6/ dalam contoh ini). ts3.6/ akan mendukung TypeScript versi 3.6 dan di bawahnya, jadi salin tipe dan pengujian yang ada di sana.
Kembali ke root paket, tambahkan fitur TypeScript 3.7 yang ingin Anda gunakan. Saat orang menginstal paket, TypeScript 3.6 dan yang lebih lama akan dimulai dari ts3.6/index.d.ts , sedangkan TypeScript 3.7 dan yang lebih baru akan dimulai dari index.d.ts .
Anda dapat melihat bluebird sebagai contoh.
Ini mungkin termasuk dalam generator TypeScript-DOM-lib. Lihat pedomannya di sana. Kalau standarnya masih berupa rancangan, maka standarnya ada di sini. Gunakan nama yang diawali dengan dom- dan sertakan tautan ke standar sebagai tautan "Proyek" di package.json . Saat paket tersebut lulus mode draf, kami dapat menghapusnya dari Diketik Pasti dan menghentikan paket @types yang terkait.
CATATAN: Pembahasan di bagian ini mengasumsikan pemahaman tentang pembuatan versi Semantik
Setiap paket yang Diketik Pasti memiliki versi saat dipublikasikan ke npm. PastiTyped-tools (alat yang menerbitkan paket @types ke npm) akan mengatur versi paket deklarasi dengan menggunakan nomor versi major.minor.9999 yang tercantum dalam package.json . Misalnya, berikut adalah beberapa baris pertama deklarasi tipe Node untuk versi 20.8.x pada saat penulisan:
{
"private" : true ,
"name" : " @types/node " ,
"version" : " 20.8.9999 "
} Karena versinya terdaftar sebagai 20.8.9999 , versi npm paket @types/node juga akan menjadi 20.8.x . Perhatikan bahwa versi di package.json hanya boleh berisi versi major.minor (misalnya 10.12 ) diikuti oleh .9999 . Hal ini karena hanya nomor rilis mayor dan minor yang diselaraskan antara paket perpustakaan dan paket deklarasi tipe. (The .9999 adalah untuk memastikan bahwa paket @types lokal selalu terbaru selama pengembangan lokal.) Nomor rilis patch dari paket deklarasi tipe (misalnya .0 di 20.8.0 ) diinisialisasi ke nol dengan Pasti Diketik dan bertambah setiap kali paket @types/node baru diterbitkan ke npm untuk versi mayor/minor yang sama dari perpustakaan terkait.
Terkadang ketik versi paket deklarasi dan versi paket perpustakaan bisa tidak sinkron. Di bawah ini adalah beberapa alasan umum mengapa hal tersebut terjadi, berdasarkan urutan seberapa besar ketidaknyamanan tersebut bagi pengguna perpustakaan. Hanya kasus terakhir yang biasanya bermasalah.
@types masing-masing, maka npm update biasanya akan berfungsi. ❗ Jika Anda memperbarui deklarasi tipe untuk perpustakaan, selalu setel versi major.minor di package.json agar cocok dengan versi perpustakaan yang Anda dokumentasikan! ❗
Pembuatan versi semantik mengharuskan versi dengan perubahan yang dapat menyebabkan gangguan harus menambah nomor versi utama. Misalnya, perpustakaan yang menghapus fungsi yang diekspor secara publik setelah rilis 3.5.8 harus menaikkan versinya ke 4.0.0 pada rilis berikutnya. Selain itu, ketika rilis 4.0.0 perpustakaan keluar, paket deklarasi tipe Pasti Diketik juga harus diperbarui ke 4.0.0 , termasuk perubahan apa pun yang dapat menyebabkan gangguan pada API perpustakaan.
Banyak pustaka yang memiliki basis pengembang yang terinstal dalam jumlah besar (termasuk pengelola paket lain yang menggunakan pustaka tersebut sebagai dependensi) yang tidak akan langsung berpindah ke versi baru yang memiliki perubahan yang dapat menyebabkan gangguan, karena mungkin memerlukan waktu berbulan-bulan hingga pengelola memiliki waktu untuk menulis ulang kode untuk beradaptasi dengan versi baru. Sementara itu, pengguna perpustakaan versi lama mungkin masih ingin memperbarui deklarasi tipe untuk versi yang lebih lama.
Jika Anda ingin terus memperbarui versi deklarasi tipe perpustakaan yang lebih lama, Anda dapat membuat subfolder baru (misalnya /v2/ ) yang diberi nama untuk versi saat ini (segera menjadi "lama") dan menyalin file yang ada dari versi saat ini ke versi tersebut. .
Saat membuat folder versi baru, pastikan kolom version package.json telah diperbarui; pnpm akan secara otomatis menyelesaikan paket berversi ini kapan pun diperlukan. Jika paket lain di repo perlu bergantung pada versi baru ini, pastikan package.json juga diperbarui.
Misalnya, jika kita membuat types/history/v2 , package.json akan terlihat seperti:
{
"private" : true ,
"name" : " @types/history " ,
"version" : " 2.4.9999 "
}Paket lain dapat memilih versi ini dengan menentukan:
{
"private" : true ,
"name" : " @types/browser-sync " ,
"version" : " 2.26.9999 " ,
"dependencies" : {
"@types/history" : " ^2 "
}
} Selain itu, /// <reference types=".." /> tidak akan berfungsi dengan pemetaan jalur, jadi dependensi harus menggunakan import .
@types paket selalu mengetikkan paket dengan versi yang sama, jadi @types/[email protected] adalah untuk [email protected] . Sebagai konsekuensinya, semua perubahan, rusak atau tidak, dipublikasikan sebagai revisi patch, kecuali dipasangkan dengan perubahan besar/kecil untuk mengubah versi paket yang ditargetkan (secara kebetulan atau tidak).
Dalam hal perubahan yang dapat menyebabkan gangguan, pengelola DT mempertimbangkan popularitas paket, keuntungan dari perubahan yang dapat menyebabkan gangguan, upaya yang diperlukan pengguna untuk memperbaiki kode mereka, dan apakah perubahan tersebut dapat ditunda hingga dapat disinkronkan. dengan perubahan besar pada perpustakaan hulu.
Buku pegangan TypeScript berisi informasi umum yang sangat baik tentang penulisan definisi dan juga contoh file definisi yang menunjukkan cara membuat definisi menggunakan sintaks modul gaya ES6, sekaligus menentukan objek yang tersedia untuk cakupan global. Teknik ini ditunjukkan secara praktis dalam definisi big.js , yang merupakan perpustakaan yang dapat dimuat secara global melalui tag skrip pada halaman web atau diimpor melalui impor gaya require atau ES6.
Untuk menguji bagaimana definisi Anda dapat digunakan baik ketika direferensikan secara global atau sebagai modul yang diimpor, buat folder test dan tempatkan dua file pengujian di sana. Beri nama satu YourLibraryName-global.test.ts dan yang lainnya YourLibraryName-module.test.ts . File pengujian global harus menggunakan definisi sesuai dengan cara penggunaannya dalam skrip yang dimuat pada halaman web di mana perpustakaan tersedia dalam lingkup global - dalam skenario ini Anda tidak boleh menentukan pernyataan import. File pengujian modul harus menggunakan definisi sesuai dengan cara penggunaannya saat diimpor (termasuk pernyataan import ). Jika Anda menentukan properti files dalam file tsconfig.json Anda, pastikan untuk memasukkan kedua file uji. Contoh praktis dari ini juga tersedia pada definisi big.js
Harap dicatat bahwa tidak diperlukan untuk sepenuhnya menggunakan definisi dalam setiap file uji - cukup untuk menguji hanya elemen yang dapat diakses secara global pada file uji global dan sepenuhnya menggunakan definisi dalam file uji modul atau sebaliknya.
Jenis untuk paket scoped @foo/bar harus masuk dalam types/foo__bar . Perhatikan garis bawah ganda.
Proyek ini dilisensikan di bawah lisensi MIT.
Hak cipta pada file definisi masing -masing dari masing -masing kontributor yang terdaftar di awal setiap file definisi.
