Skip to content

Commit 7cac95a

Browse files
yyx990803yyx990803
committed
component: registration
1 parent 5000410 commit 7cac95a

File tree

2 files changed

+92
-119
lines changed

2 files changed

+92
-119
lines changed

‎src/guide/components/registration.md

Lines changed: 78 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -2,176 +2,138 @@
22

33
> This page assumes you've already read the [Components Basics](/guide/essentials/component-basics). Read that first if you are new to components.
44
5-
## Component Names
5+
A Vue component needs to be "registered" so that Vue knows where to locate its implementation when it is encountered in a template. There are two ways to register components: global and local.
66

7-
When registering a component, it will always be given a name. For example, in the global registration we've seen so far:
8-
9-
```js
10-
const app = Vue.createApp({...})
11-
12-
app.component('my-component-name', {
13-
/* ... */
14-
})
15-
```
16-
17-
The component's name is the first argument of `app.component`. In the example above, the component's name is "my-component-name".
18-
19-
The name you give a component may depend on where you intend to use it. When using a component directly in the DOM (as opposed to in a string template or Single File Component), we strongly recommend following the [W3C rules](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name) for custom tag names:
20-
21-
1. All lowercase
22-
2. Contains a hyphen (i.e., has multiple words connected with the hyphen symbol)
23-
24-
By doing so, this will help you avoid conflicts with current and future HTML elements.
25-
26-
You can see other recommendations for component names in the [Style Guide](/style-guide/#base-component-names-strongly-recommended).
27-
28-
### Name Casing
29-
30-
When defining components in a string template or a single-file component, you have two options when defining component names:
7+
## Global Registration
318

32-
#### With kebab-case
9+
We can make components available globally in the current [Vue application](/guide/essentials/application.html) using the `app.component()` method:
3310

3411
```js
35-
app.component('my-component-name', {
36-
/* ... */
37-
})
38-
```
39-
40-
When defining a component with kebab-case, you must also use kebab-case when referencing its custom element, such as in `<my-component-name>`.
12+
import { createApp } from 'vue'
4113

42-
#### With PascalCase
14+
const app = createApp({})
4315

44-
```js
45-
app.component('MyComponentName', {
46-
/* ... */
47-
})
16+
app.component(
17+
// the registered name
18+
'MyComponent',
19+
// the implementation
20+
{
21+
/* ... */
22+
}
23+
)
4824
```
4925

50-
When defining a component with PascalCase, you can use either case when referencing its custom element. That means both `<my-component-name>` and `<MyComponentName>` are acceptable. Note, however, that only kebab-case names are valid directly in the DOM (i.e. non-string templates).
51-
52-
## Global Registration
53-
54-
So far, we've only created components using `app.component`:
26+
If using SFCs, you will be registering the imported `.vue` files:
5527

5628
```js
57-
Vue.createApp({...}).component('my-component-name', {
58-
// ... options ...
59-
})
29+
import MyComponent from './App.vue`
30+
31+
app.component('MyComponent', MyComponent)
6032
```
6133
62-
These components are **globally registered** for the application. That means they can be used in the template of any component instance within this application:
34+
The `app.component()` method can be chained:
6335
6436
```js
65-
const app = Vue.createApp({})
66-
67-
app.component('component-a', {
68-
/* ... */
69-
})
70-
app.component('component-b', {
71-
/* ... */
72-
})
73-
app.component('component-c', {
74-
/* ... */
75-
})
76-
77-
app.mount('#app')
37+
app
38+
.component('ComponentA', ComponentA)
39+
.component('ComponentB', ComponentB)
40+
.component('ComponentC', ComponentC)
7841
```
7942
43+
Globally registered components can be used in the template of any component instance within this application:
44+
8045
```vue-html
81-
<div id="app">
82-
<component-a></component-a>
83-
<component-b></component-b>
84-
<component-c></component-c>
85-
</div>
46+
<!-- this will work in any component inside the app -->
47+
<ComponentA/>
48+
<ComponentB/>
49+
<ComponentC/>
8650
```
8751
8852
This even applies to all subcomponents, meaning all three of these components will also be available _inside each other_.
8953
9054
## Local Registration
9155
92-
Global registration often isn't ideal. For example, if you're using a build system like Webpack, globally registering all components means that even if you stop using a component, it could still be included in your final build. This unnecessarily increases the amount of JavaScript your users have to download.
56+
While convenient, global registration has a few drawbacks:
9357
94-
In these cases, you can define your components as plain JavaScript objects:
58+
1. Global registration prevents build systems from removing unused components (a.k.a "tree-shaking"). If you globally register a component but ends up not using it anywhere in your app, it will still be included in the final bundle.
9559
96-
```js
97-
const ComponentA = {
98-
/* ... */
99-
}
100-
const ComponentB = {
101-
/* ... */
102-
}
103-
const ComponentC = {
104-
/* ... */
105-
}
106-
```
60+
2. Global registration makes dependency relationships less explicit in large applications. It makes it difficult to locate a child component's implementation from a parent component using it. This can affect long term maintainability similar to using too many global variables.
10761

108-
Then define the components you'd like to use in a `components` option:
62+
Local registration scopes the availability of the registered components to the current component only. It makes the dependency relationship more explicit, and is more tree-shaking-friendly.
10963

110-
```js
111-
const app = Vue.createApp({
112-
components: {
113-
'component-a': ComponentA,
114-
'component-b': ComponentB
115-
}
116-
})
117-
```
64+
<div class="composition-api">
11865

119-
For each property in the `components` object, the key will be the name of the custom element, while the value will contain the options object for the component.
66+
When using SFC with `<script setup>`, imported components are automatically local-registered:
12067

121-
Note that **locally registered components are _not_ also available in subcomponents**. For example, if you wanted `ComponentA` to be available in `ComponentB`, you'd have to use:
122-
123-
```js
124-
const ComponentA = {
125-
/* ... */
126-
}
68+
```vue
69+
<script setup>
70+
import ComponentA from './ComponentA.vue'
71+
</script>
12772
128-
const ComponentB = {
129-
components: {
130-
'component-a': ComponentA
131-
}
132-
// ...
133-
}
73+
<template>
74+
<ComponentA />
75+
</template>
13476
```
13577

136-
Or if you're using ES2015 modules, such as through Babel and Webpack, that might look more like:
78+
If not using SFC, you will need to use the `components` option:
13779

13880
```js
139-
import ComponentA from './ComponentA.vue'
81+
import ComponentA from './ComponentA.js'
14082
14183
export default {
14284
components: {
14385
ComponentA
86+
},
87+
setup() {
88+
// ...
14489
}
145-
// ...
14690
}
14791
```
14892

149-
Note that in ES2015+, placing a variable name like `ComponentA` inside an object is shorthand for `ComponentA: ComponentA`, meaning the name of the variable is both:
93+
</div>
94+
<div class="options-api">
15095

151-
- the custom element name to use in the template, and
152-
- the name of the variable containing the component options
96+
Local registration are done using the `components` option:
15397

154-
## Module Systems
98+
```vue
99+
<script>
100+
import ComponentA from './ComponentA.vue'
155101
156-
If you're not using a module system with `import`/`require`, you can probably skip this section for now. If you are, we have some special instructions and tips just for you.
102+
export default {
103+
components: {
104+
ComponentA
105+
}
106+
}
107+
</script>
157108
158-
### Local Registration in a Module System
109+
<template>
110+
<ComponentA />
111+
</template>
112+
```
159113

160-
If you're still here, then it's likely you're using a module system, such as with Babel and Webpack. In these cases, we recommend creating a `components` directory, with each component in its own file.
114+
</div>
161115

162-
Then you'll need to import each component you'd like to use, before you locally register it. For example, in a hypothetical `ComponentB.js` or `ComponentB.vue` file:
116+
For each property in the `components` object, the key will be the registered name of the component, while the value will contain the implementation of the component. The above example is using the ES2015 property shorthand and is equivalent to:
163117

164118
```js
165-
import ComponentA from './ComponentA'
166-
import ComponentC from './ComponentC'
167-
168119
export default {
169120
components: {
170-
ComponentA,
171-
ComponentC
121+
ComponentA: ComponentA
172122
}
173123
// ...
174124
}
175125
```
176126

177-
Now both `ComponentA` and `ComponentC` can be used inside `ComponentB`'s template.
127+
Note that **locally registered components are _not_ also available in descendent components**. In this case, `ComponentA` will be made available to the current component only, not any of its child or descendent components.
128+
129+
## Component Name Casing
130+
131+
Throughout the guide, we are using PascalCase for component registration names. This is because:
132+
133+
1. PascalCase names are valid JavaScript identifiers. This makes it easier to import and register components in JavaScript.
134+
135+
2. `<PascalCase />` makes it more obvious that this is a Vue component instead of a native HTML element in templates.
136+
137+
This is the recommended style when working with SFC or string templates. However, as discussed in [DOM Template Parsing Caveats](/guide/essentials/component-basics.html#dom-template-parsing-caveats), PascalCase tags are not usable in DOM templates.
138+
139+
Luckily, Vue supports resolving kebab-case tags to components registered using PascalCase. This means a component registered as `MyComponent` can be referenced in the template via both `<MyComponent>` and `<my-component>`. This allows us to use the same JavaScript component registration code regardless of template source.

‎src/guide/essentials/component-basics.md

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,7 @@ With `<script setup>`, imported components are automatically made available to t
136136

137137
</div>
138138

139-
It's also possible to [globally register a component](/guide/components/registration.html#global-registration), making it available to all components in a given app without having to import it. However, global registration makes the dependency relationship less explicit, and can make it difficult to locate the implementation of a child component to understand its usage in large apps.
139+
It's also possible to globally register a component, making it available to all components in a given app without having to import it. The pros and cons of global vs. local registration is discussed in the dedicated [Component Registration](/guide/components/registration.html) section.
140140

141141
Components can be reused as many times as you want:
142142

@@ -160,7 +160,18 @@ Components can be reused as many times as you want:
160160

161161
Notice that when clicking on the buttons, each one maintains its own, separate `count`. That's because each time you use a component, a new **instance** of it is created.
162162

163-
In SFCs, it's recommended to use `PascalCase` tag names for child components to differentiate from native HTML elements. Although native HTML tag names are case-insensitive, Vue SFC is a compiled format so we are able to use case-sensitive tag names in it. However, you will need to use `kebab-case` component tags if you are authoring your template directly in the DOM (which makes it subject to native HTML parsing rules). See [DOM template parsing caveats](#dom-template-parsing-caveats) for more details.
163+
In SFCs, it's recommended to use `PascalCase` tag names for child components to differentiate from native HTML elements. Although native HTML tag names are case-insensitive, Vue SFC is a compiled format so we are able to use case-sensitive tag names in it. We are also able to use `/>` to close a tag.
164+
165+
If you are authoring your templates directly in a DOM (e.g. as the content of a native `<template>` element), the template will be subject to the browser's native HTML parsing behavior. In such cases, you will need to use `kebab-case` and explicit closing tags for components:
166+
167+
```vue-html
168+
<!-- if this template is written in the DOM -->
169+
<button-counter></button-counter>
170+
<button-counter></button-counter>
171+
<button-counter></button-counter>
172+
```
173+
174+
See [DOM template parsing caveats](#dom-template-parsing-caveats) for more details.
164175

165176
## Passing Data to Child Components with Props
166177

@@ -687,8 +698,8 @@ If you are writing your Vue templates directly in the DOM, Vue will have to retr
687698
:::tip
688699
It should be noted that the limitations discussed below only apply if you are writing your templates directly in the DOM. They do NOT apply if you are using string templates from the following sources:
689700

690-
- String templates (e.g. `template: '...'`)
691701
- Single File Components
702+
- Inlined template strings (e.g. `template: '...'`)
692703
- `<script type="text/x-template">`
693704
:::
694705

0 commit comments

Comments
 (0)