From 728e5a70a36ab5f3b0bd6be1700aba7dd314b0d3 Mon Sep 17 00:00:00 2001 From: ntepluhina Date: Mon, 20 Jan 2020 18:54:48 +0200 Subject: [PATCH 01/24] feat: started component basics --- .prettierrc | 4 + src/.vuepress/config.js | 22 +- src/guide/component-basics.md | 621 ++++++++++++++++++++++++++++++++++ 3 files changed, 645 insertions(+), 2 deletions(-) create mode 100644 .prettierrc create mode 100644 src/guide/component-basics.md diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000000..b2095be81e --- /dev/null +++ b/.prettierrc @@ -0,0 +1,4 @@ +{ + "semi": false, + "singleQuote": true +} diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index e6feb5592e..30920b34e4 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -25,7 +25,25 @@ module.exports = { ], sidebarDepth: 2, sidebar: { - '/guide/': ['installation', 'introduction', 'instance', 'template-syntax'] + '/guide/': [ + { + title: 'Essentials', + collapsable: true, + children: [ + 'installation', + 'introduction', + 'instance', + 'template-syntax', + // 'computed', + // 'class-and-style', + // 'conditional', + // 'list', + // 'events', + // 'forms', + 'component-basics' + ] + } + ] } }, plugins: { @@ -39,4 +57,4 @@ module.exports = { } } } -}; +} diff --git a/src/guide/component-basics.md b/src/guide/component-basics.md new file mode 100644 index 0000000000..7a6ccdeee6 --- /dev/null +++ b/src/guide/component-basics.md @@ -0,0 +1,621 @@ +# Components Basics + +
Watch a free video course on Vue School
+ +## Base Example + +Here's an example of a Vue component: + +```js +// Create a Vue application +const app = Vue.createApp() + +// Define a new global component called button-counter +app.component('button-counter', { + data() { + return { + count: 0 + } + }, + template: `` +}) +``` + +Components are reusable Vue instances with a name: in this case, ``. We can use this component as a custom element inside a root Vue instance created with `new Vue`: + +```html +
+ +
+``` + +```js +app.mount({}, '#components-demo') +``` + +// Component goes here + +Since components are reusable Vue instances, they accept the same options as `new Vue`, such as `data`, `computed`, `watch`, `methods`, and lifecycle hooks. The only exceptions are a few root-specific options like `el`. + +## Reusing Components + +Components can be reused as many times as you want: + +```html +
+ + + +
+``` + +{% raw %} + +
+ + + +
+ +{% endraw %} + +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. + +### `data` Must Be a Function + +When we defined the `` component, you may have noticed that `data` wasn't directly provided an object, like this: + +```js +data: { + count: 0 +} +``` + +Instead, **a component's `data` option must be a function**, so that each instance can maintain an independent copy of the returned data object: + +```js +data: function () { + return { + count: 0 + } +} +``` + +If Vue didn't have this rule, clicking on one button would affect the data of _all other instances_, like below: + +{% raw %} + +
+ + + +
+ +{% endraw %} + +## Organizing Components + +It's common for an app to be organized into a tree of nested components: + +![Component Tree](/images/components.png) + +For example, you might have components for a header, sidebar, and content area, each typically containing other components for navigation links, blog posts, etc. + +To use these components in templates, they must be registered so that Vue knows about them. There are two types of component registration: **global** and **local**. So far, we've only registered components globally, using `Vue.component`: + +```js +Vue.component('my-component-name', { + // ... options ... +}) +``` + +Globally registered components can be used in the template of any root Vue instance (`new Vue`) created afterwards -- and even inside all subcomponents of that Vue instance's component tree. + +That's all you need to know about registration for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Component Registration](components-registration.html). + +## Passing Data to Child Components with Props + +Earlier, we mentioned creating a component for blog posts. The problem is, that component won't be useful unless you can pass data to it, such as the title and content of the specific post we want to display. That's where props come in. + +Props are custom attributes you can register on a component. When a value is passed to a prop attribute, it becomes a property on that component instance. To pass a title to our blog post component, we can include it in the list of props this component accepts, using a `props` option: + +```js +Vue.component('blog-post', { + props: ['title'], + template: '

{{ title }}

' +}) +``` + +A component can have as many props as you'd like and by default, any value can be passed to any prop. In the template above, you'll see that we can access this value on the component instance, just like with `data`. + +Once a prop is registered, you can pass data to it as a custom attribute, like this: + +```html + + + +``` + +{% raw %} + +
+ + + +
+ +{% endraw %} + +In a typical app, however, you'll likely have an array of posts in `data`: + +```js +new Vue({ + el: '#blog-post-demo', + data: { + posts: [ + { id: 1, title: 'My journey with Vue' }, + { id: 2, title: 'Blogging with Vue' }, + { id: 3, title: 'Why Vue is so fun' } + ] + } +}) +``` + +Then want to render a component for each one: + +```html + +``` + +Above, you'll see that we can use `v-bind` to dynamically pass props. This is especially useful when you don't know the exact content you're going to render ahead of time, like when [fetching posts from an API](https://jsfiddle.net/chrisvfritz/sbLgr0ad). + +That's all you need to know about props for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Props](components-props.html). + +## A Single Root Element + +When building out a `` component, your template will eventually contain more than just the title: + +```html +

{{ title }}

+``` + +At the very least, you'll want to include the post's content: + +```html +

{{ title }}

+
+``` + +If you try this in your template however, Vue will show an error, explaining that **every component must have a single root element**. You can fix this error by wrapping the template in a parent element, such as: + +```html +
+

{{ title }}

+
+
+``` + +As our component grows, it's likely we'll not only need the title and content of a post, but also the published date, comments, and more. Defining a prop for each related piece of information could become very annoying: + +```html + +``` + +So this might be a good time to refactor the `` component to accept a single `post` prop instead: + +```html + +``` + +```js +Vue.component('blog-post', { + props: ['post'], + template: ` +
+

{{ post.title }}

+
+
+ ` +}) +``` + +

The above example and some future ones use JavaScript's [template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) to make multi-line templates more readable. These are not supported by Internet Explorer (IE), so if you must support IE and are not transpiling (e.g. with Babel or TypeScript), use [newline escapes](https://css-tricks.com/snippets/javascript/multiline-string-variables-in-javascript/) instead.

+ +Now, whenever a new property is added to `post` objects, it will automatically be available inside ``. + +## Listening to Child Components Events + +As we develop our `` component, some features may require communicating back up to the parent. For example, we may decide to include an accessibility feature to enlarge the text of blog posts, while leaving the rest of the page its default size: + +In the parent, we can support this feature by adding a `postFontSize` data property: + +```js +new Vue({ + el: '#blog-posts-events-demo', + data: { + posts: [ + /* ... */ + ], + postFontSize: 1 + } +}) +``` + +Which can be used in the template to control the font size of all blog posts: + +```html +
+
+ +
+
+``` + +Now let's add a button to enlarge the text right before the content of every post: + +```js +Vue.component('blog-post', { + props: ['post'], + template: ` +
+

{{ post.title }}

+ +
+
+ ` +}) +``` + +The problem is, this button doesn't do anything: + +```html + +``` + +When we click on the button, we need to communicate to the parent that it should enlarge the text of all posts. Fortunately, Vue instances provide a custom events system to solve this problem. The parent can choose to listen to any event on the child component instance with `v-on`, just as we would with a native DOM event: + +```html + +``` + +Then the child component can emit an event on itself by calling the built-in [**`$emit`** method](../api/#vm-emit), passing the name of the event: + +```html + +``` + +Thanks to the `v-on:enlarge-text="postFontSize += 0.1"` listener, the parent will receive the event and update `postFontSize` value. + +{% raw %} + +
+
+ +
+
+ +{% endraw %} + +### Emitting a Value With an Event + +It's sometimes useful to emit a specific value with an event. For example, we may want the `` component to be in charge of how much to enlarge the text by. In those cases, we can use `$emit`'s 2nd parameter to provide this value: + +```html + +``` + +Then when we listen to the event in the parent, we can access the emitted event's value with `$event`: + +```html + +``` + +Or, if the event handler is a method: + +```html + +``` + +Then the value will be passed as the first parameter of that method: + +```js +methods: { + onEnlargeText: function (enlargeAmount) { + this.postFontSize += enlargeAmount + } +} +``` + +### Using `v-model` on Components + +Custom events can also be used to create custom inputs that work with `v-model`. Remember that: + +```html + +``` + +does the same thing as: + +```html + +``` + +When used on a component, `v-model` instead does this: + +```html + +``` + +For this to actually work though, the `` inside the component must: + +- Bind the `value` attribute to a `value` prop +- On `input`, emit its own custom `input` event with the new value + +Here's that in action: + +```js +Vue.component('custom-input', { + props: ['value'], + template: ` + + ` +}) +``` + +Now `v-model` should work perfectly with this component: + +```html + +``` + +That's all you need to know about custom component events for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Custom Events](components-custom-events.html). + +## Content Distribution with Slots + +Just like with HTML elements, it's often useful to be able to pass content to a component, like this: + +```html + + Something bad happened. + +``` + +Which might render something like: + +{% raw %} + +
+ + Something bad happened. + +
+ + +{% endraw %} + +Fortunately, this task is made very simple by Vue's custom `` element: + +```js +Vue.component('alert-box', { + template: ` +
+ Error! + +
+ ` +}) +``` + +As you'll see above, we just add the slot where we want it to go -- and that's it. We're done! + +That's all you need to know about slots for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Slots](components-slots.html). + +## Dynamic Components + +Sometimes, it's useful to dynamically switch between components, like in a tabbed interface: + +{% raw %} + +
+ + +
+ + +{% endraw %} + +The above is made possible by Vue's `` element with the `is` special attribute: + +```html + + +``` + +In the example above, `currentTabComponent` can contain either: + +- the name of a registered component, or +- a component's options object + +See [this fiddle](https://jsfiddle.net/chrisvfritz/o3nycadu/) to experiment with the full code, or [this version](https://jsfiddle.net/chrisvfritz/b2qj69o1/) for an example binding to a component's options object, instead of its registered name. + +Keep in mind that this attribute can be used with regular HTML elements, however they will be treated as components, which means all attributes **will be bound as DOM attributes**. For some properties such as `value` to work as you would expect, you will need to bind them using the [`.prop` modifier](../api/#v-bind). + +That's all you need to know about dynamic components for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Dynamic & Async Components](components-dynamic-async.html). + +## DOM Template Parsing Caveats + +Some HTML elements, such as `
    `, `
      `, `` and ``, and `
      + +
      +``` + +The custom component `` will be hoisted out as invalid content, causing errors in the eventual rendered output. Fortunately, the `is` special attribute offers a workaround: + +```html + + +
      +``` + +It should be noted that **this limitation does _not_ apply if you are using string templates from one of the following sources**: + +- String templates (e.g. `template: '...'`) +- [Single-file (`.vue`) components](single-file-components.html) +- [` + + diff --git a/src/.vuepress/components/components-1.vue b/src/.vuepress/components/components-1.vue new file mode 100644 index 0000000000..6d3591f80e --- /dev/null +++ b/src/.vuepress/components/components-1.vue @@ -0,0 +1,11 @@ + + + + + diff --git a/src/guide/component-basics.md b/src/guide/component-basics.md index 7a6ccdeee6..6782a82ccd 100644 --- a/src/guide/component-basics.md +++ b/src/guide/component-basics.md @@ -33,7 +33,7 @@ Components are reusable Vue instances with a name: in this case, ` Since components are reusable Vue instances, they accept the same options as `new Vue`, such as `data`, `computed`, `watch`, `methods`, and lifecycle hooks. The only exceptions are a few root-specific options like `el`. From 89774c76439ec9c02300a099026d3b560f824e1b Mon Sep 17 00:00:00 2001 From: ntepluhina Date: Mon, 20 Jan 2020 19:27:15 +0200 Subject: [PATCH 03/24] feat: moved component props --- src/.vuepress/components/blog-post1.vue | 9 ++ src/.vuepress/components/components-1.vue | 6 -- src/.vuepress/components/components-2.vue | 7 ++ src/.vuepress/components/components-3.vue | 7 ++ src/guide/component-basics.md | 108 +++++----------------- 5 files changed, 46 insertions(+), 91 deletions(-) create mode 100644 src/.vuepress/components/blog-post1.vue create mode 100644 src/.vuepress/components/components-2.vue create mode 100644 src/.vuepress/components/components-3.vue diff --git a/src/.vuepress/components/blog-post1.vue b/src/.vuepress/components/blog-post1.vue new file mode 100644 index 0000000000..3c7a63fd9a --- /dev/null +++ b/src/.vuepress/components/blog-post1.vue @@ -0,0 +1,9 @@ + + + diff --git a/src/.vuepress/components/components-1.vue b/src/.vuepress/components/components-1.vue index 6d3591f80e..1059054ed2 100644 --- a/src/.vuepress/components/components-1.vue +++ b/src/.vuepress/components/components-1.vue @@ -3,9 +3,3 @@ - - - - diff --git a/src/.vuepress/components/components-2.vue b/src/.vuepress/components/components-2.vue new file mode 100644 index 0000000000..4e2141b12b --- /dev/null +++ b/src/.vuepress/components/components-2.vue @@ -0,0 +1,7 @@ + diff --git a/src/.vuepress/components/components-3.vue b/src/.vuepress/components/components-3.vue new file mode 100644 index 0000000000..977572ebb2 --- /dev/null +++ b/src/.vuepress/components/components-3.vue @@ -0,0 +1,7 @@ + diff --git a/src/guide/component-basics.md b/src/guide/component-basics.md index 6782a82ccd..ca294a2570 100644 --- a/src/guide/component-basics.md +++ b/src/guide/component-basics.md @@ -49,63 +49,10 @@ Components can be reused as many times as you want: ``` -{% raw %} - -
      - - - -
      - -{% endraw %} + 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. -### `data` Must Be a Function - -When we defined the `` component, you may have noticed that `data` wasn't directly provided an object, like this: - -```js -data: { - count: 0 -} -``` - -Instead, **a component's `data` option must be a function**, so that each instance can maintain an independent copy of the returned data object: - -```js -data: function () { - return { - count: 0 - } -} -``` - -If Vue didn't have this rule, clicking on one button would affect the data of _all other instances_, like below: - -{% raw %} - -
      - - - -
      - -{% endraw %} - ## Organizing Components It's common for an app to be organized into a tree of nested components: @@ -114,17 +61,19 @@ It's common for an app to be organized into a tree of nested components: For example, you might have components for a header, sidebar, and content area, each typically containing other components for navigation links, blog posts, etc. -To use these components in templates, they must be registered so that Vue knows about them. There are two types of component registration: **global** and **local**. So far, we've only registered components globally, using `Vue.component`: +To use these components in templates, they must be registered so that Vue knows about them. There are two types of component registration: **global** and **local**. So far, we've only registered components globally, using `component` method of created app: ```js -Vue.component('my-component-name', { +const app = Vue.createApp() + +app.component('my-component-name', { // ... options ... }) ``` -Globally registered components can be used in the template of any root Vue instance (`new Vue`) created afterwards -- and even inside all subcomponents of that Vue instance's component tree. +Globally registered components can be used in the template of `app` instance created afterwards - and even inside all subcomponents of that Vue instance's component tree. -That's all you need to know about registration for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Component Registration](components-registration.html). +That's all you need to know about registration for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Component Registration](TODO:components-registration.html). ## Passing Data to Child Components with Props @@ -133,9 +82,11 @@ Earlier, we mentioned creating a component for blog posts. The problem is, that Props are custom attributes you can register on a component. When a value is passed to a prop attribute, it becomes a property on that component instance. To pass a title to our blog post component, we can include it in the list of props this component accepts, using a `props` option: ```js -Vue.component('blog-post', { +const app = Vue.createApp() + +app.component('blog-post', { props: ['title'], - template: '

      {{ title }}

      ' + template: `

      {{ title }}

      ` }) ``` @@ -149,35 +100,22 @@ Once a prop is registered, you can pass data to it as a custom attribute, like t ``` -{% raw %} - -
      - - - -
      - -{% endraw %} + In a typical app, however, you'll likely have an array of posts in `data`: ```js -new Vue({ - el: '#blog-post-demo', - data: { - posts: [ - { id: 1, title: 'My journey with Vue' }, - { id: 2, title: 'Blogging with Vue' }, - { id: 3, title: 'Why Vue is so fun' } - ] +const App = { + data() { + return { + posts: [ + { id: 1, title: 'My journey with Vue' }, + { id: 2, title: 'Blogging with Vue' }, + { id: 3, title: 'Why Vue is so fun' } + ] + } } -}) +} ``` Then want to render a component for each one: @@ -190,7 +128,7 @@ Then want to render a component for each one: > ``` -Above, you'll see that we can use `v-bind` to dynamically pass props. This is especially useful when you don't know the exact content you're going to render ahead of time, like when [fetching posts from an API](https://jsfiddle.net/chrisvfritz/sbLgr0ad). +Above, you'll see that we can use `v-bind` to dynamically pass props. This is especially useful when you don't know the exact content you're going to render ahead of time. That's all you need to know about props for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Props](components-props.html). From 64847f5e80a27daf10985de11e52baaf56569b0e Mon Sep 17 00:00:00 2001 From: ntepluhina Date: Mon, 20 Jan 2020 21:31:26 +0200 Subject: [PATCH 04/24] feat: reworked events on components --- src/.vuepress/components/blog-post2.vue | 14 + src/.vuepress/components/components-4.vue | 27 ++ src/guide/component-basics.md | 369 ++-------------------- 3 files changed, 68 insertions(+), 342 deletions(-) create mode 100644 src/.vuepress/components/blog-post2.vue create mode 100644 src/.vuepress/components/components-4.vue diff --git a/src/.vuepress/components/blog-post2.vue b/src/.vuepress/components/blog-post2.vue new file mode 100644 index 0000000000..b3d6edcdca --- /dev/null +++ b/src/.vuepress/components/blog-post2.vue @@ -0,0 +1,14 @@ + + + diff --git a/src/.vuepress/components/components-4.vue b/src/.vuepress/components/components-4.vue new file mode 100644 index 0000000000..7a4845e163 --- /dev/null +++ b/src/.vuepress/components/components-4.vue @@ -0,0 +1,27 @@ + + + diff --git a/src/guide/component-basics.md b/src/guide/component-basics.md index ca294a2570..9c78393c35 100644 --- a/src/guide/component-basics.md +++ b/src/guide/component-basics.md @@ -86,7 +86,7 @@ const app = Vue.createApp() app.component('blog-post', { props: ['title'], - template: `

      {{ title }}

      ` + template: `

      {{ title }}

      ` }) ``` @@ -116,101 +116,43 @@ const App = { } } } + +app.mount(App, '#blog-posts-demo') ``` Then want to render a component for each one: ```html - +
      + +
      ``` Above, you'll see that we can use `v-bind` to dynamically pass props. This is especially useful when you don't know the exact content you're going to render ahead of time. That's all you need to know about props for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Props](components-props.html). -## A Single Root Element - -When building out a `` component, your template will eventually contain more than just the title: - -```html -

      {{ title }}

      -``` - -At the very least, you'll want to include the post's content: - -```html -

      {{ title }}

      -
      -``` - -If you try this in your template however, Vue will show an error, explaining that **every component must have a single root element**. You can fix this error by wrapping the template in a parent element, such as: - -```html -
      -

      {{ title }}

      -
      -
      -``` - -As our component grows, it's likely we'll not only need the title and content of a post, but also the published date, comments, and more. Defining a prop for each related piece of information could become very annoying: - -```html - -``` - -So this might be a good time to refactor the `` component to accept a single `post` prop instead: - -```html - -``` - -```js -Vue.component('blog-post', { - props: ['post'], - template: ` -
      -

      {{ post.title }}

      -
      -
      - ` -}) -``` - -

      The above example and some future ones use JavaScript's [template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) to make multi-line templates more readable. These are not supported by Internet Explorer (IE), so if you must support IE and are not transpiling (e.g. with Babel or TypeScript), use [newline escapes](https://css-tricks.com/snippets/javascript/multiline-string-variables-in-javascript/) instead.

      - -Now, whenever a new property is added to `post` objects, it will automatically be available inside ``. - ## Listening to Child Components Events -As we develop our `` component, some features may require communicating back up to the parent. For example, we may decide to include an accessibility feature to enlarge the text of blog posts, while leaving the rest of the page its default size: +As we develop our `` component, some features may require communicating back up to the parent. For example, we may decide to include an accessibility feature to enlarge the text of blog posts, while leaving the rest of the page its default size. In the parent, we can support this feature by adding a `postFontSize` data property: ```js -new Vue({ - el: '#blog-posts-events-demo', - data: { - posts: [ - /* ... */ - ], - postFontSize: 1 +const App = { + data() { + return { + posts: [ + /* ... */ + ], + postFontSize: 1 + } } -}) +} ``` Which can be used in the template to control the font size of all blog posts: @@ -221,7 +163,7 @@ Which can be used in the template to control the font size of all blog posts: @@ -230,15 +172,14 @@ Which can be used in the template to control the font size of all blog posts: Now let's add a button to enlarge the text right before the content of every post: ```js -Vue.component('blog-post', { - props: ['post'], +app.component('blog-post', { + props: ['title'], template: `
      -

      {{ post.title }}

      +

      {{ title }}

      -
      ` }) @@ -258,7 +199,7 @@ When we click on the button, we need to communicate to the parent that it should ``` -Then the child component can emit an event on itself by calling the built-in [**`$emit`** method](../api/#vm-emit), passing the name of the event: +Then the child component can emit an event on itself by calling the built-in [**`$emit`** method](TODO:../api/#vm-emit), passing the name of the event: ```html - - - - -{% endraw %} - -The above is made possible by Vue's `` element with the `is` special attribute: - -```html - - -``` - -In the example above, `currentTabComponent` can contain either: - -- the name of a registered component, or -- a component's options object - -See [this fiddle](https://jsfiddle.net/chrisvfritz/o3nycadu/) to experiment with the full code, or [this version](https://jsfiddle.net/chrisvfritz/b2qj69o1/) for an example binding to a component's options object, instead of its registered name. - -Keep in mind that this attribute can be used with regular HTML elements, however they will be treated as components, which means all attributes **will be bound as DOM attributes**. For some properties such as `value` to work as you would expect, you will need to bind them using the [`.prop` modifier](../api/#v-bind). - -That's all you need to know about dynamic components for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Dynamic & Async Components](components-dynamic-async.html). - -## DOM Template Parsing Caveats - -Some HTML elements, such as `
        `, `
          `, `` and ``, and `
          - -
          -``` - -The custom component `` will be hoisted out as invalid content, causing errors in the eventual rendered output. Fortunately, the `is` special attribute offers a workaround: - -```html - - -
          -``` - -It should be noted that **this limitation does _not_ apply if you are using string templates from one of the following sources**: - -- String templates (e.g. `template: '...'`) -- [Single-file (`.vue`) components](single-file-components.html) -- [` + + diff --git a/src/guide/component-basics.md b/src/guide/component-basics.md index cee4b6cc57..cda1aa0d1f 100644 --- a/src/guide/component-basics.md +++ b/src/guide/component-basics.md @@ -295,3 +295,34 @@ Now `v-model` should work perfectly with this component: ``` That's all you need to know about custom component events for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Custom Events](TODO:components-custom-events.html). + +## Content Distribution with Slots + +Just like with HTML elements, it's often useful to be able to pass content to a component, like this: + +```html + + Something bad happened. + +``` + +Which might render something like: + + + +Fortunately, this task is made very simple by Vue's custom `` element: + +```js +app.component('alert-box', { + template: ` +
          + Error! + +
          + ` +}) +``` + +As you'll see above, we just add the slot where we want it to go -- and that's it. We're done! + +That's all you need to know about slots for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Slots](TODO:components-slots.html). From ee9757ea3cef479fae76ea8708b1a74fe9e3dca8 Mon Sep 17 00:00:00 2001 From: ntepluhina Date: Tue, 21 Jan 2020 21:08:54 +0200 Subject: [PATCH 07/24] feat: added dynamic components --- src/.vuepress/components/components-6.vue | 58 +++++++++++++++++++++++ src/.vuepress/components/tab-archive.vue | 3 ++ src/.vuepress/components/tab-home.vue | 3 ++ src/.vuepress/components/tab-posts.vue | 3 ++ src/guide/component-basics.md | 54 +++++++++++++++++++++ 5 files changed, 121 insertions(+) create mode 100644 src/.vuepress/components/components-6.vue create mode 100644 src/.vuepress/components/tab-archive.vue create mode 100644 src/.vuepress/components/tab-home.vue create mode 100644 src/.vuepress/components/tab-posts.vue diff --git a/src/.vuepress/components/components-6.vue b/src/.vuepress/components/components-6.vue new file mode 100644 index 0000000000..aba40af9c8 --- /dev/null +++ b/src/.vuepress/components/components-6.vue @@ -0,0 +1,58 @@ + + + + + diff --git a/src/.vuepress/components/tab-archive.vue b/src/.vuepress/components/tab-archive.vue new file mode 100644 index 0000000000..9b54ae2c81 --- /dev/null +++ b/src/.vuepress/components/tab-archive.vue @@ -0,0 +1,3 @@ + diff --git a/src/.vuepress/components/tab-home.vue b/src/.vuepress/components/tab-home.vue new file mode 100644 index 0000000000..566d6caaab --- /dev/null +++ b/src/.vuepress/components/tab-home.vue @@ -0,0 +1,3 @@ + diff --git a/src/.vuepress/components/tab-posts.vue b/src/.vuepress/components/tab-posts.vue new file mode 100644 index 0000000000..3d01a211f3 --- /dev/null +++ b/src/.vuepress/components/tab-posts.vue @@ -0,0 +1,3 @@ + diff --git a/src/guide/component-basics.md b/src/guide/component-basics.md index cda1aa0d1f..1da6b06252 100644 --- a/src/guide/component-basics.md +++ b/src/guide/component-basics.md @@ -326,3 +326,57 @@ app.component('alert-box', { As you'll see above, we just add the slot where we want it to go -- and that's it. We're done! That's all you need to know about slots for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Slots](TODO:components-slots.html). + +## Dynamic Components + +Sometimes, it's useful to dynamically switch between components, like in a tabbed interface: + + + +The above is made possible by Vue's `` element with the `is` special attribute: + +```html + + +``` + +In the example above, `currentTabComponent` can contain either: + +- the name of a registered component, or +- a component's options object + +See [TODO:this fiddle](https://jsfiddle.net/chrisvfritz/o3nycadu/) to experiment with the full code, or [TODO:this version](https://jsfiddle.net/chrisvfritz/b2qj69o1/) for an example binding to a component's options object, instead of its registered name. + +Keep in mind that this attribute can be used with regular HTML elements, however they will be treated as components, which means all attributes **will be bound as DOM attributes**. For some properties such as `value` to work as you would expect, you will need to bind them using the [`.prop` modifier](TODO:../api/#v-bind). + +That's all you need to know about dynamic components for now, but once you've finished reading this page and feel comfortable with its content, we recommend coming back later to read the full guide on [Dynamic & Async Components](TODO:components-dynamic-async.html). + +## DOM Template Parsing Caveats + +Some HTML elements, such as `
            `, `
              `, `` and ``, and `
              + +
              +``` + +The custom component `` will be hoisted out as invalid content, causing errors in the eventual rendered output. Fortunately, the `is` special attribute offers a workaround: + +```html + + +
              +``` + +It should be noted that **this limitation does _not_ apply if you are using string templates from one of the following sources**: + +- String templates (e.g. `template: '...'`) +- [Single-file (`.vue`) components](TODO:single-file-components.html) +- [`