TypeScript 支持 · VueJS官方離線文檔(搬運版)

在 Vue 2.5.0 中，我們大大改進了類型聲明以更好地使用默認的基于對象的 API。同時此版本也引入了一些其它變化，需要開發者作出相應的升級。閱讀[博客文章](https://medium.com/the-vue-point/upcoming-typescript-changes-in-vue-2-5-e9bd7e2ecf08)了解更多詳情。 ## 發布為 NPM 包的官方聲明文件靜態類型系統能幫助你有效防止許多潛在的運行時錯誤，而且隨著你的應用日漸豐滿會更加顯著。這就是為什么 Vue 不僅僅為 Vue core 提供了針對 [TypeScript](https://www.typescriptlang.org/) 的[官方類型聲明](https://github.com/vuejs/vue/tree/dev/types)，還為 [Vue Router](https://github.com/vuejs/vue-router/tree/dev/types) 和 [Vuex](https://github.com/vuejs/vuex/tree/dev/types) 也提供了相應的聲明文件。而且，我們已經把它們[發布到了 NPM](https://cdn.jsdelivr.net/npm/vue/types/)，最新版本的 TypeScript 也知道該如何自己從 NPM 包里解析類型聲明。這意味著只要你成功地通過 NPM 安裝了，就不再需要任何額外的工具輔助，即可在 Vue 中使用 TypeScript 了。 ## 推薦配置 ``` js // tsconfig.json { "compilerOptions": { // 與 Vue 的瀏覽器支持保持一致 "target": "es5", ? ?// 這可以對 `this` 上的數據屬性進行更嚴格的推斷 "strict": true, ? ?// 如果使用 webpack 2+ 或 rollup，可以利用 tree-shake: "module": "es2015", "moduleResolution": "node" } } ``` 注意你需要引入 `strict: true` (或者至少 `noImplicitThis: true`，這是 `strict` 模式的一部分) 以利用組件方法中 `this` 的類型檢查，否則它會始終被看作 `any` 類型。參閱 [TypeScript 編譯器選項文檔 (英)](https://www.typescriptlang.org/docs/handbook/compiler-options.html) 了解更多。 ## 開發工具鏈 ### 工程創建 [Vue CLI 3](https://github.com/vuejs/vue-cli) 可以使用 TypeScript 生成新工程。創建方式： ```bash # 1. 如果沒有安裝 Vue CLI 就先安裝 npm install --global @vue/cli # 2. 創建一個新工程，并選擇 "Manually select features (手動選擇特性)" 選項 vue create my-project-name ``` ### 編輯器支持要使用 TypeScript 開發 Vue 應用程序，我們強烈建議您使用 [Visual Studio Code](https://code.visualstudio.com/)，它為 TypeScript 提供了極好的“開箱即用”支持。如果你正在使用[單文件組件](./single-file-components.html) (SFC), 可以安裝提供 SFC 支持以及其他更多實用功能的 [Vetur 插件](https://github.com/vuejs/vetur)。 [WebStorm](https://www.jetbrains.com/webstorm/) 同樣為 TypeScript 和 Vue 提供了“開箱即用”的支持。 ## 基本用法要讓 TypeScript 正確推斷 Vue 組件選項中的類型，您需要使用 `Vue.component` 或 `Vue.extend` 定義組件： ``` ts import Vue from 'vue' const Component = Vue.extend({ // 類型推斷已啟用 }) const Component = { // 這里不會有類型推斷， // 因為TypeScript不能確認這是Vue組件的選項 } ``` ## 基于類的 Vue 組件如果您在聲明組件時更喜歡基于類的 API，則可以使用官方維護的 [vue-class-component](https://github.com/vuejs/vue-class-component) 裝飾器： ``` ts import Vue from 'vue' import Component from 'vue-class-component' // @Component 修飾符注明了此類為一個 Vue 組件 @Component({ // 所有的組件選項都可以放在這里 template: '<button @click="onClick">Click!</button>' }) export default class MyComponent extends Vue { // 初始數據可以直接聲明為實例的屬性 message: string = 'Hello!' // 組件方法也可以直接聲明為實例的方法 onClick (): void { window.alert(this.message) } } ``` ## 增強類型以配合插件使用插件可以增加 Vue 的全局/實例屬性和組件選項。在這些情況下，在 TypeScript 中制作插件需要類型聲明。慶幸的是，TypeScript 有一個特性來補充現有的類型，叫做[模塊補充 (module augmentation)](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation)。例如，聲明一個 `string` 類型的實例屬性 `$myProperty`： ``` ts // 1. 確保在聲明補充的類型之前導入 'vue' import Vue from 'vue' // 2. 定制一個文件，設置你想要補充的類型 // 在 types/vue.d.ts 里 Vue 有構造函數類型 declare module 'vue/types/vue' { // 3. 聲明為 Vue 補充的東西 interface Vue { $myProperty: string } } ``` 在你的項目中包含了上述作為聲明文件的代碼之后 (像 `my-property.d.ts`)，你就可以在 Vue 實例上使用 `$myProperty` 了。 ```ts var vm = new Vue() console.log(vm.$myProperty) // 將會順利編譯通過 ``` 你也可以聲明額外的屬性和組件選項： ```ts import Vue from 'vue' declare module 'vue/types/vue' { ?// 可以使用 `VueConstructor` 接口 ?// 來聲明全局屬性 interface VueConstructor { ? ?$myGlobal: string ?} } // ComponentOptions 聲明于 types/options.d.ts 之中 declare module 'vue/types/options' { interface ComponentOptions<V extends Vue> { myOption?: string } } ``` 上述的聲明允許下面的代碼順利編譯通過： ```ts // 全局屬性 console.log(Vue.$myGlobal) // 額外的組件選項 var vm = new Vue({ myOption: 'Hello' }) ``` ## 標注返回值因為 Vue 的聲明文件天生就具有循環性，TypeScript 可能在推斷某個方法的類型的時候存在困難。因此，你可能需要在 `render` 或 `computed` 里的方法上標注返回值。 ```ts import Vue, { VNode } from 'vue' const Component = Vue.extend({ data () { return { msg: 'Hello' } }, methods: { // 需要標注有 `this` 參與運算的返回值類型 greet (): string { return this.msg + ' world' } }, computed: { // 需要標注 greeting(): string { return this.greet() + '!' } }, // `createElement` 是可推導的，但是 `render` 需要返回值類型 render (createElement): VNode { return createElement('div', this.greeting) } }) ``` 如果你發現類型推導或成員補齊不工作了，標注某個方法也許可以幫助你解決這個問題。使用 `--noImplicitAny` 選項將會幫助你找到這些未標注的方法。