Skip to content

Commit 80f3301

Browse files
committed
docs: Add type definition for globalProperties in TypeScript chapter
vuejs/docs@8c9ebf1#diff-c8904f42c96ea728eea302e9bc39484fbb58d2401b4017ad37ea848fc8f183e5
1 parent c56fc1a commit 80f3301

File tree

1 file changed

+49
-3
lines changed

1 file changed

+49
-3
lines changed

src/guide/typescript-support.md

Lines changed: 49 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,52 @@ const Component = defineComponent({
153153
})
154154
```
155155

156+
### Augmenting Types for `globalProperties`
157+
158+
Vue 3 provides a [`globalProperties` object](../api/application-config.html#globalproperties) that can be used to add a global property that can be accessed in any component instance. For example, a [plugin](./plugins.html#writing-a-plugin) might want to inject a shared global object or function.
159+
160+
```ts
161+
// User Definition
162+
import axios from 'axios'
163+
164+
const app = Vue.createApp({})
165+
app.config.globalProperties.$http = axios
166+
167+
// Plugin for validating some data
168+
export default {
169+
install(app, options) {
170+
app.config.globalProperties.$validate = (data: object, rule: object) => {
171+
// check whether the object meets certain rules
172+
}
173+
}
174+
}
175+
```
176+
177+
In order to tell TypeScript about these new properties, we can use [module augmentation](https://www.typescriptlang.org/docs/handbook/declaration-merging.html#module-augmentation).
178+
179+
In the above example, we could add the following type declaration:
180+
181+
```ts
182+
import axios from 'axios'
183+
184+
declare module '@vue/runtime-core' {
185+
export interface ComponentCustomProperties {
186+
$http: typeof axios
187+
$validate: (data: object, rule: object) => boolean
188+
}
189+
}
190+
```
191+
192+
We can put this type declaration in the same file, or in a project-wide `*.d.ts` file (for example, in the `src/typings` folder that is automatically loaded by TypeScript). For library/plugin authors, this file should be specified in the `types` property in `package.json`.
193+
194+
::: warning Make sure the declaration file is a TypeScript module
195+
In order to take advantage of module augmentation, you will need to ensure there is at least one top-level `import` or `export` in your file, even if it is just `export {}`.
196+
197+
[In TypeScript](https://www.typescriptlang.org/docs/handbook/modules.html), any file containing a top-level `import` or `export` is considered a 'module'. If type declaration is made outside of a module, it will overwrite the original types rather than augmenting them.
198+
:::
199+
200+
For more information about the `ComponentCustomProperties` type, see its [definition in `@vue/runtime-core`](https://github.com/vuejs/vue-next/blob/2587f36fe311359e2e34f40e8e47d2eebfab7f42/packages/runtime-core/src/componentOptions.ts#L64-L80) and [the TypeScript unit tests](https://github.com/vuejs/vue-next/blob/master/test-dts/componentTypeExtensions.test-d.tsx) to learn more.
201+
156202
### 戻り値の型にアノテーションをつける
157203

158204
Vue の型宣言ファイルの循環的な性質により、TypeScript は算出プロパティの型を推論することが困難な場合があります。この理由により、算出プロパティの戻り値の型にアノテーションをつける必要があります。
@@ -170,7 +216,7 @@ const Component = defineComponent({
170216
// アノテーションが必要です
171217
greeting(): string {
172218
return this.message + '!'
173-
}
219+
},
174220

175221
// セッターを持つ算出プロパティのでは、ゲッターにアノテーションが必要です
176222
greetingUppercased: {
@@ -179,8 +225,8 @@ const Component = defineComponent({
179225
},
180226
set(newValue: string) {
181227
this.message = newValue.toUpperCase();
182-
},
183-
},
228+
}
229+
}
184230
}
185231
})
186232
```

0 commit comments

Comments
 (0)