Skip to content

Commit 34ace5d

Browse files
NataliaTepluhinaJinjiangbencodezen
authored
Global config and Global API reference (#68)
* feat: started with Global Config API * feat: finished global config * feat: added component global api * feat: added directives API * feat: added mixin API * feat: add mount API * feat: added unmount and use * Update src/api/global-api.md Co-Authored-By: Jinjiang <zhaojinjiang@me.com> * Update src/api/global-config.md Co-Authored-By: Jinjiang <zhaojinjiang@me.com> * fixL changed global -> application * fix: fixed types for config * fix: fixed types for API * feat: added a note about native HTML tags * Update src/api/application-api.md Co-Authored-By: Ben Hong <ben@bencodezen.io> * Update src/api/application-api.md Co-Authored-By: Ben Hong <ben@bencodezen.io> Co-authored-by: Jinjiang <zhaojinjiang@me.com> Co-authored-by: Ben Hong <ben@bencodezen.io>
1 parent 70210b3 commit 34ace5d

File tree

6 files changed

+435
-8
lines changed

6 files changed

+435
-8
lines changed

‎src/.vuepress/config.js

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,8 @@ const sidebar = {
5353
collapsable: true,
5454
children: ['writing-guide']
5555
}
56-
]
56+
],
57+
api: ['/api/application-config', '/api/application-api']
5758
}
5859

5960
module.exports = {
@@ -67,6 +68,7 @@ module.exports = {
6768
rel: 'stylesheet',
6869
},
6970
],
71+
['link', { rel: 'icon', href: '/logo.png' }],
7072
[
7173
'script',
7274
{
@@ -92,7 +94,7 @@ module.exports = {
9294
{ text: 'Tooling', link: '/tooling/' }
9395
]
9496
},
95-
{ text: 'API Reference', link: '/api/' },
97+
{ text: 'API Reference', link: '/api/application-config' },
9698
{
9799
text: 'Examples',
98100
ariaLabel: 'Examples Menu',
@@ -114,8 +116,10 @@ module.exports = {
114116
],
115117
sidebarDepth: 2,
116118
sidebar: {
119+
collapsable: false,
117120
'/guide/': sidebar.guide,
118-
'/community/': sidebar.guide
121+
'/community/': sidebar.guide,
122+
'/api/': sidebar.api
119123
},
120124
smoothScroll: false
121125
},

‎src/api/application-api.md

Lines changed: 274 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,274 @@
1+
# Application API
2+
3+
In Vue 3, APIs that globally mutate Vue's behavior are now moved to application instances created by the new `createApp` method. In addition, their effects are now scoped to that specific application's instance:
4+
5+
```js
6+
import { createApp } from 'vue'
7+
8+
const app = createApp({})
9+
```
10+
11+
Calling `createApp` returns an application instance. This instance provides an application context. The entire component tree mounted by the application instance share the same context, which provides the configurations that were previously "global" in Vue 2.x.
12+
13+
In addition, since the `createApp` method returns the application instance itself, you can chain other methods after it which can be found in the following sections.
14+
15+
## component
16+
17+
- **Arguments:**
18+
19+
- `{string} name`
20+
- `{Function | Object} [definition]`
21+
22+
- **Usage:**
23+
24+
Register or retrieve a global component. Registration also automatically sets the component's `name` with the given `name` parameter.
25+
26+
- **Example:**
27+
28+
```js
29+
import { createApp } from 'vue'
30+
31+
const app = createApp({})
32+
33+
// register an options object
34+
app.component('my-component', {
35+
/* ... */
36+
})
37+
38+
// retrieve a registered component (always return constructor)
39+
const MyComponent = app.component('my-component', {})
40+
```
41+
42+
- **See also:** [Components](../guide/component-basics.html)
43+
44+
## config
45+
46+
- **Usage:**
47+
48+
An object containing application configurations.
49+
50+
- **Example:**
51+
52+
```js
53+
import { createApp } from 'vue'
54+
const app = createApp({})
55+
56+
app.config = {...}
57+
```
58+
59+
- **See also:** [Global Config Properties](./global-config.html)
60+
61+
## directive
62+
63+
- **Arguments:**
64+
65+
- `{string} name`
66+
- `{Function | Object} [definition]`
67+
68+
- **Usage:**
69+
70+
Register or retrieve a global directive.
71+
72+
- **Example:**
73+
74+
```js
75+
import { createApp } from 'vue'
76+
const app = createApp({})
77+
78+
// register
79+
app.directive('my-directive', {
80+
// Directive has a set of lifecycle hooks:
81+
// called before bound element's parent component is mounted
82+
beforeMount() {},
83+
// called when bound element's parent component is mounted
84+
mounted() {},
85+
// called before the containing component's VNode is updated
86+
beforeUpdate() {},
87+
// called after the containing component's VNode and the VNodes of its children // have updated
88+
updated() {},
89+
// called before the bound element's parent component is unmounted
90+
beforeUnmount() {},
91+
// called when the bound element's parent component is unmounted
92+
unmounted() {}
93+
})
94+
95+
// register (function directive)
96+
app.directive('my-directive', () => {
97+
// this will be called as `mounted` and `updated`
98+
})
99+
100+
// getter, return the directive definition if registered
101+
const myDirective = app.directive('my-directive')
102+
```
103+
104+
Directive hooks are passed these arguments:
105+
106+
#### el
107+
108+
The element the directive is bound to. This can be used to directly manipulate the DOM.
109+
110+
#### binding
111+
112+
An object containing the following properties.
113+
114+
- `instance`: The instance of the component where directive is used.
115+
- `value`: The value passed to the directive. For example in `v-my-directive="1 + 1"`, the value would be `2`.
116+
- `oldValue`: The previous value, only available in `beforeUpdate` and `updated`. It is available whether or not the value has changed.
117+
- `arg`: The argument passed to the directive, if any. For example in `v-my-directive:foo`, the arg would be `"foo"`.
118+
- `modifiers`: An object containing modifiers, if any. For example in `v-my-directive.foo.bar`, the modifiers object would be `{ foo: true, bar: true }`.
119+
- `dir`: an object, passed as a parameter when directive is registered. For example, in the directive
120+
121+
```js
122+
app.directive('focus', {
123+
mounted(el) {
124+
el.focus()
125+
}
126+
})
127+
```
128+
129+
`dir` would be the following object:
130+
131+
```js
132+
{
133+
mounted(el) {
134+
el.focus()
135+
}
136+
}
137+
```
138+
139+
#### vnode
140+
141+
A blueprint of the real DOM element received as el argument above. See the [VNode API](TODO) for full details.
142+
143+
#### prevNode
144+
145+
The previous virtual node, only available in the `beforeUpdate` and `updated` hooks.
146+
147+
:::tip Note
148+
Apart from `el`, you should treat these arguments as read-only and never modify them. If you need to share information across hooks, it is recommended to do so through element's [dataset](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset).
149+
:::
150+
151+
- **See also:** [Custom Directives](../guide/custom-directive.html)
152+
153+
## mixin
154+
155+
- **Arguments:**
156+
157+
- `{Object} mixin`
158+
159+
- **Usage:**
160+
161+
Apply a mixin in the whole application scope, which will affect **every** Vue instance created afterwards in the given app (for example, child components). This can be used by plugin authors to inject custom behavior into components. **Not recommended in application code**.
162+
163+
- **See also:** [Global Mixin](../guide/mixins.html#global-mixin)
164+
165+
## mount
166+
167+
- **Arguments:**
168+
169+
- `{Element | string} rootContainer`
170+
- `{boolean} isHydrate`
171+
172+
- **Usage:**
173+
174+
Mounts a root component of the application instance on the provided DOM element.
175+
176+
- **Example:**
177+
178+
```html
179+
<body>
180+
<div id="my-app"></div>
181+
</body>
182+
```
183+
184+
```js
185+
import { createApp } from 'vue'
186+
187+
const app = createApp({})
188+
// do some necessary preparations
189+
app.mount('#my-app')
190+
```
191+
192+
- **See also:**
193+
- [Lifecycle Diagram](../guide/instance.html#lifecycle-diagram)
194+
195+
## provide
196+
197+
- **Type:**
198+
199+
- `Object | () => Object`
200+
201+
- **Details:**
202+
203+
This option is used together with [`inject`](TODO:inject) are used together to allow an ancestor component to serve as a dependency injector for all its descendants, regardless of how deep the component hierarchy is, as long as they are in the same parent chain.
204+
205+
The `provide` option should be an object or a function that returns an object. This object contains the properties that are available for injection into its descendants. You can use ES2015 Symbols as keys in this object, but only in environments that natively support `Symbol` and `Reflect.ownKeys`.
206+
207+
> Note: the `provide` and `inject` bindings are NOT reactive. This is intentional. However, if you pass down an observed object, properties on that object do remain reactive.
208+
209+
- **Example:**
210+
211+
```js
212+
import { createApp } from 'vue'
213+
214+
const app = createApp({
215+
provide: {
216+
user: 'John Doe'
217+
}
218+
})
219+
220+
app.component('user-card', {
221+
inject: ['user'],
222+
template: `
223+
<div>
224+
{{ user }}
225+
</div>
226+
`
227+
})
228+
```
229+
230+
- **See also:**
231+
- [Provide / Inject](../guide/component-provide-inject.md)
232+
233+
## unmount
234+
235+
- **Arguments:**
236+
237+
- `{Element | string} rootContainer`
238+
239+
- **Usage:**
240+
241+
Unmounts a root component of the application instance on the provided DOM element.
242+
243+
- **Example:**
244+
245+
```html
246+
<body>
247+
<div id="my-app"></div>
248+
</body>
249+
```
250+
251+
```js
252+
import { createApp } from 'vue'
253+
254+
const app = createApp({})
255+
// do some necessary preparations
256+
app.mount('#my-app')
257+
258+
// Application will be unmounted 5 seconds after mount
259+
setTimeout(() => app.unmount('#my-app'), 5000)
260+
```
261+
262+
## use
263+
264+
- **Arguments:**
265+
266+
- `{Object | Function} plugin`
267+
268+
- **Usage:**
269+
270+
Install a Vue.js plugin. If the plugin is an Object, it must expose an `install` method. If it is a function itself, it will be treated as the install method. The install method will be called with Vue as the argument.
271+
272+
When this method is called on the same plugin multiple times, the plugin will be installed only once.
273+
274+
- **See also:** [Plugins](TODO)

0 commit comments

Comments
 (0)