Skip to content

Commit cf8ce5a

Browse files
ktsnktsn
authored
docs: docs reorganization (#390)
* docs: wip docs reorganization * docs: update docs url
1 parent 6b1aef4 commit cf8ce5a

20 files changed

+4580
-413
lines changed

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
node_modules
22
example/build.js
33
example/build.js.map
4+
docs/.vuepress/dist
45
test/test.build.js
56
lib

‎README.md

+6-306
Original file line numberDiff line numberDiff line change
@@ -1,317 +1,17 @@
1-
# vue-class-component
1+
# Vue Class Component
22

3-
> ECMAScript / TypeScript decorator for class-style Vue components.
3+
ECMAScript / TypeScript decorator for class-style Vue components.
44

55
[![npm](https://img.shields.io/npm/v/vue-class-component.svg)](https://www.npmjs.com/package/vue-class-component)
66

7-
### Usage
7+
## Document
88

9-
**Required**: [ECMAScript stage 1 decorators](https://github.com/wycats/javascript-decorators/blob/master/README.md).
10-
If you use Babel, [babel-plugin-transform-decorators-legacy](https://github.com/loganfsmyth/babel-plugin-transform-decorators-legacy) is needed.
11-
If you use TypeScript, enable `--experimentalDecorators` flag.
9+
See [https://class-component.vuejs.org](https://class-component.vuejs.org)
1210

13-
> It does not support the stage 2 decorators yet since mainstream transpilers still transpile to the old decorators.
14-
15-
Note:
16-
17-
1. `methods` can be declared directly as class member methods.
18-
19-
2. Computed properties can be declared as class property accessors.
20-
21-
3. Initial `data` can be declared as class properties ([babel-plugin-transform-class-properties](https://babeljs.io/docs/plugins/transform-class-properties/) is required if you use Babel).
22-
23-
4. `data`, `render` and all Vue lifecycle hooks can be directly declared as class member methods as well, but you cannot invoke them on the instance itself. When declaring custom methods, you should avoid these reserved names.
24-
25-
5. For all other options, pass them to the decorator function.
26-
27-
### Example
28-
29-
Following is the example written in Babel. If you are looking for TypeScript version, [it's in the example directory](example/src/App.vue).
30-
31-
``` vue
32-
<template>
33-
<div>
34-
<input v-model="msg">
35-
<p>prop: {{propMessage}}</p>
36-
<p>msg: {{msg}}</p>
37-
<p>helloMsg: {{helloMsg}}</p>
38-
<p>computed msg: {{computedMsg}}</p>
39-
<button @click="greet">Greet</button>
40-
</div>
41-
</template>
42-
43-
<script>
44-
import Vue from 'vue'
45-
import Component from 'vue-class-component'
46-
47-
@Component({
48-
props: {
49-
propMessage: String
50-
}
51-
})
52-
export default class App extends Vue {
53-
// initial data
54-
msg = 123
55-
56-
// use prop values for initial data
57-
helloMsg = 'Hello, ' + this.propMessage
58-
59-
// lifecycle hook
60-
mounted () {
61-
this.greet()
62-
}
63-
64-
// computed
65-
get computedMsg () {
66-
return 'computed ' + this.msg
67-
}
68-
69-
// method
70-
greet () {
71-
alert('greeting: ' + this.msg)
72-
}
73-
}
74-
</script>
75-
```
76-
77-
You may also want to check out the `@prop` and `@watch` decorators provided by [vue-property-decorator](https://github.com/kaorun343/vue-property-decorator).
78-
79-
### Using Mixins
80-
81-
vue-class-component provides `mixins` helper function to use [mixins](https://vuejs.org/v2/guide/mixins.html) in class style manner. By using `mixins` helper, TypeScript can infer mixin types and inherit them on the component type.
82-
83-
Example of declaring a mixin:
84-
85-
``` js
86-
// mixin.js
87-
import Vue from 'vue'
88-
import Component from 'vue-class-component'
89-
90-
// You can declare a mixin as the same style as components.
91-
@Component
92-
export default class MyMixin extends Vue {
93-
mixinValue = 'Hello'
94-
}
95-
```
96-
97-
Example of using a mixin:
98-
99-
``` js
100-
import Component, { mixins } from 'vue-class-component'
101-
import MyMixin from './mixin.js'
102-
103-
// Use `mixins` helper function instead of `Vue`.
104-
// `mixins` can receive any number of arguments.
105-
@Component
106-
export class MyComp extends mixins(MyMixin) {
107-
created () {
108-
console.log(this.mixinValue) // -> Hello
109-
}
110-
}
111-
```
112-
113-
### Create Custom Decorators
114-
115-
You can extend the functionality of this library by creating your own decorators. vue-class-component provides `createDecorator` helper to create custom decorators. `createDecorator` expects a callback function as the 1st argument and the callback will receive following arguments:
116-
117-
- `options`: Vue component options object. Changes for this object will affect the provided component.
118-
- `key`: The property or method key that the decorator is applied.
119-
- `parameterIndex`: The index of a decorated argument if the custom decorator is used for an argument.
120-
121-
Example of creating `NoCache` decorator:
122-
123-
``` js
124-
// decorators.js
125-
import { createDecorator } from 'vue-class-component'
126-
127-
export const NoCache = createDecorator((options, key) => {
128-
// component options should be passed to the callback
129-
// and update for the options object affect the component
130-
options.computed[key].cache = false
131-
})
132-
```
133-
134-
``` js
135-
import { NoCache } from './decorators'
136-
137-
@Component
138-
class MyComp extends Vue {
139-
// the computed property will not be cached
140-
@NoCache
141-
get random () {
142-
return Math.random()
143-
}
144-
}
145-
```
146-
147-
### Adding Custom Hooks
148-
149-
If you use some Vue plugins like Vue Router, you may want class components to resolve hooks that they provide. For that case, `Component.registerHooks` allows you to register such hooks:
150-
151-
```js
152-
// class-component-hooks.js
153-
import Component from 'vue-class-component'
154-
155-
// Register the router hooks with their names
156-
Component.registerHooks([
157-
'beforeRouteEnter',
158-
'beforeRouteLeave',
159-
'beforeRouteUpdate' // for vue-router 2.2+
160-
])
161-
```
162-
163-
```js
164-
// MyComp.js
165-
import Vue from 'vue'
166-
import Component from 'vue-class-component'
167-
168-
@Component
169-
class MyComp extends Vue {
170-
// The class component now treats beforeRouteEnter
171-
// and beforeRouteLeave as Vue Router hooks
172-
beforeRouteEnter (to, from, next) {
173-
console.log('beforeRouteEnter')
174-
next() // needs to be called to confirm the navigation
175-
}
176-
177-
beforeRouteLeave (to, from, next) {
178-
console.log('beforeRouteLeave')
179-
next() // needs to be called to confirm the navigation
180-
}
181-
}
182-
```
183-
184-
Note that you have to register the hooks before component definition.
185-
186-
```js
187-
// main.js
188-
189-
// Make sure to register before importing any components
190-
import './class-component-hooks'
191-
192-
import Vue from 'vue'
193-
import MyComp from './MyComp'
194-
195-
new Vue({
196-
el: '#app',
197-
components: {
198-
MyComp
199-
}
200-
})
201-
```
202-
203-
### Enabling Custom Hooks Auto-complete in TypeScript
204-
205-
vue-class-component provides a built-in hooks type, which enables auto-complete for `data`, `render` and other lifecycle hooks in class component declarations, for TypeScript. To enable it, you need to import hooks type located at `vue-class-component/hooks`.
206-
207-
```ts
208-
// main.ts
209-
import 'vue-class-component/hooks' // import hooks type to enable auto-complete
210-
import Vue from 'vue'
211-
import App from './App.vue'
212-
213-
new Vue({
214-
render: h => h(App)
215-
}).$mount('#app')
216-
```
217-
218-
If you want to make it work with custom hooks, you can manually add it by yourself:
219-
220-
```ts
221-
import Vue from 'vue'
222-
import { Route, RawLocation } from 'vue-router'
223-
224-
declare module 'vue/types/vue' {
225-
// Augment component instance type
226-
interface Vue {
227-
beforeRouteEnter?(
228-
to: Route,
229-
from: Route,
230-
next: (to?: RawLocation | false | ((vm: Vue) => any) | void) => void
231-
): void
232-
233-
beforeRouteLeave?(
234-
to: Route,
235-
from: Route,
236-
next: (to?: RawLocation | false | ((vm: Vue) => any) | void) => void
237-
): void
238-
239-
beforeRouteUpdate?(
240-
to: Route,
241-
from: Route,
242-
next: (to?: RawLocation | false | ((vm: Vue) => any) | void) => void
243-
): void
244-
}
245-
}
246-
```
247-
248-
### Caveats of Class Properties
249-
250-
vue-class-component collects class properties as Vue instance data by instantiating the original constructor under the hood. While we can define instance data like native class manner, we sometimes need to know how it works.
251-
252-
#### `this` value in property
253-
254-
If you define an arrow function as a class property and access `this` in it, it will not work. This is because `this` is just a proxy object to Vue instance when initializing class properties:
255-
256-
```js
257-
@Component
258-
class MyComp extends Vue {
259-
foo = 123
260-
261-
bar = () => {
262-
// Does not update the expected property.
263-
// `this` value is not a Vue instance in fact.
264-
this.foo = 456
265-
}
266-
}
267-
```
268-
269-
You can simply define a method instead of a class property in that case because Vue will bind the instance automatically:
270-
271-
```js
272-
@Component
273-
class MyComp extends Vue {
274-
foo = 123
275-
276-
bar () {
277-
// Correctly update the expected property.
278-
this.foo = 456
279-
}
280-
}
281-
```
282-
283-
#### `undefined` will not be reactive
284-
285-
To take consistency between the decorator behavior of Babel and TypeScript, vue-class-component does not make a property reactive if it has `undefined` as initial value. You should use `null` as initial value or use `data` hook to initialize `undefined` property instead.
286-
287-
```js
288-
@Component
289-
class MyComp extends Vue {
290-
// Will not be reactive
291-
foo = undefined
292-
293-
// Will be reactive
294-
bar = null
295-
296-
data () {
297-
return {
298-
// Will be reactive
299-
baz: undefined
300-
}
301-
}
302-
}
303-
```
304-
305-
### Build the Example
306-
307-
``` bash
308-
$ npm install && npm run example
309-
```
310-
311-
### Questions
11+
## Questions
31212

31313
For questions and support please use the [the official forum](http://forum.vuejs.org) or [community chat](https://chat.vuejs.org/). The issue list of this repo is **exclusively** for bug reports and feature requests.
31414

315-
### License
15+
## License
31616

31717
[MIT](http://opensource.org/licenses/MIT)

‎docs/.vuepress/config.js

+53
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
module.exports = {
2+
title: 'Vue Class Component',
3+
description: 'ECMAScript / TypeScript decorator for class-style Vue components',
4+
5+
themeConfig: {
6+
repo: 'vuejs/vue-class-component',
7+
docsDir: 'docs',
8+
editLinks: true,
9+
10+
nav: [
11+
{
12+
text: 'Guide',
13+
link: '/'
14+
},
15+
{
16+
text: 'API Reference',
17+
link: '/api/'
18+
}
19+
],
20+
21+
sidebar: {
22+
'/api/': [
23+
''
24+
],
25+
26+
'/': [
27+
'',
28+
'guide/installation.md',
29+
{
30+
title: 'General Guide',
31+
collapsable: false,
32+
children: [
33+
'guide/class-component.md',
34+
'guide/additional-hooks.md',
35+
'guide/custom-decorators.md',
36+
'guide/extend-and-mixins.md',
37+
'guide/caveats.md'
38+
]
39+
},
40+
{
41+
title: 'TypeScript Guide',
42+
collapsable: false,
43+
children: [
44+
'guide/props-definition.md',
45+
'guide/property-type-declaration.md',
46+
'guide/refs-type-extension.md',
47+
'guide/hooks-auto-complete.md'
48+
]
49+
}
50+
]
51+
}
52+
}
53+
}

0 commit comments

Comments
 (0)