From 2221ea8ce579ce72de0807c00d5274fed0c3d804 Mon Sep 17 00:00:00 2001 From: NataliaTepluhina Date: Wed, 1 Jul 2020 20:14:31 +0300 Subject: [PATCH 01/10] feat: finished teleport guide --- src/.vuepress/config.js | 9 +-- src/guide/component-teleport.md | 104 ++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+), 6 deletions(-) create mode 100644 src/guide/component-teleport.md diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index 25920a938a..99afb3c790 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -28,6 +28,7 @@ const sidebar = { '/guide/component-provide-inject', '/guide/component-dynamic-async', '/guide/component-template-refs', + '/guide/component-teleport', '/guide/component-edge-cases' ] }, @@ -54,9 +55,7 @@ const sidebar = { { title: 'Tooling', collapsable: false, - children: [ - '/guide/single-file-component' - ] + children: ['/guide/single-file-component'] }, { title: 'Scaling Up', @@ -71,9 +70,7 @@ const sidebar = { { title: 'Tooling', collapsable: false, - children: [ - '/guide/testing' - ] + children: ['/guide/testing'] }, { title: 'Migration to Vue 3', diff --git a/src/guide/component-teleport.md b/src/guide/component-teleport.md new file mode 100644 index 0000000000..45a89223c2 --- /dev/null +++ b/src/guide/component-teleport.md @@ -0,0 +1,104 @@ +# Teleport + +> This page assumes you've already read the [Components Basics](component-basics.md). Read that first if you are new to components. + +Vue encourages us to build our UIs by encapsulating UI and related behavior into components. We can nest them inside one another to build a tree that makes up an application UI. + +However, sometimes a part of a component's template belongs into this component logically, while from a technical point of view, it would be preferable to move this part of the template somewhere else in the DOM, outside of Vue app. For example, due to styling requirements, we want to move `

` from it's deeply nested position to the `

` with `id="endofbody"` + +```html + +
+

Move the #content with the portal component

+
+

+ This should be moved to #endofbody. +

+ This content should be nested +
+
+
+ +``` + +To do so, we can use Vue built-in `` component: + +```html + +
+

Move the #content with the portal component

+
+ +

+ This should be moved to #endofbody. +

+ + This content should be nested +
+
+
+ +``` + +As a result, we will have `teleport` content moved in the rendered DOM tree: + +

+ See the Pen + Teleport by Vue (@Vue) + on CodePen. +

+ + +As you can see, all of the children of `` will be appended to `
`. + +## Using with Vue components + +If `teleport` contains a Vue component, it will remain a child component of the ``'s parent: + +```js +const app = Vue.createApp({ + template: ` +

Root instance

+ + ` +}) + +app.component('parent-component', { + template: ` +

This is a parent component

+ + + + ` +}) + +app.component('child-component', { + props: ['name'], + template: ` +
Hello, {{ name }}
+ ` +}) +``` + +In this case, even when `child-component` is rendered in the different place, it will remain a child of `parent-component` and will receive a `name` prop from it. + +## Using multiple teleports on the same target + +A common use case scenario would be a reusable `` component of which there might be multiple instances active at the same time. For this kind of scenario, multiple `` components can mount their content to the same target element. The order will be a simple append - later mounts will be located after earlier ones within the target element. + +```html + +
A
+ + +
B
+ + + +
+
A
+
B
+
+``` + +You can check `` component options in the [API reference]() From 1dae759bd5a322b3088e48ebf85505d55f8a998b Mon Sep 17 00:00:00 2001 From: NataliaTepluhina Date: Wed, 1 Jul 2020 20:22:43 +0300 Subject: [PATCH 02/10] feat: added Teleport API --- src/.vuepress/config.js | 2 +- src/api/built-in-components.md | 29 +++++++++++++++++++ .../{component-teleport.md => teleport.md} | 4 +-- 3 files changed, 31 insertions(+), 4 deletions(-) rename src/guide/{component-teleport.md => teleport.md} (96%) diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js index 99afb3c790..d9e6e31338 100644 --- a/src/.vuepress/config.js +++ b/src/.vuepress/config.js @@ -28,7 +28,6 @@ const sidebar = { '/guide/component-provide-inject', '/guide/component-dynamic-async', '/guide/component-template-refs', - '/guide/component-teleport', '/guide/component-edge-cases' ] }, @@ -47,6 +46,7 @@ const sidebar = { children: [ '/guide/mixins', '/guide/custom-directive', + '/guide/teleport', '/guide/render-function', '/guide/plugins', '/guide/composition-api-introduction' diff --git a/src/api/built-in-components.md b/src/api/built-in-components.md index 4b576b77a3..9bbf7ad36e 100644 --- a/src/api/built-in-components.md +++ b/src/api/built-in-components.md @@ -212,3 +212,32 @@ For detailed usage, see the guide section linked below. - **See also:** [Content Distribution with Slots](../guide/component-basics.html#content-distribution-with-slots) + +## teleport + +- **Props:** + + - `to` - `string`. Required prop, has to be a valid query selector, or an HTMLElement (if used in a browser environment). Specifies a target element where `` content will be moved + + ```html + + + + + + + + + ``` + + - `disabled` - `boolean`. This optional prop can be used to disable the portal's functionality, which means that its slot content will not be moved anywhere and instead be rendered where you specified the `` in the surrounding parent component. + + ```html + + + ``` + +- **See also:** [Teleport component](..//guide/teleport.html#teleport) diff --git a/src/guide/component-teleport.md b/src/guide/teleport.md similarity index 96% rename from src/guide/component-teleport.md rename to src/guide/teleport.md index 45a89223c2..6a70122e68 100644 --- a/src/guide/component-teleport.md +++ b/src/guide/teleport.md @@ -1,7 +1,5 @@ # Teleport -> This page assumes you've already read the [Components Basics](component-basics.md). Read that first if you are new to components. - Vue encourages us to build our UIs by encapsulating UI and related behavior into components. We can nest them inside one another to build a tree that makes up an application UI. However, sometimes a part of a component's template belongs into this component logically, while from a technical point of view, it would be preferable to move this part of the template somewhere else in the DOM, outside of Vue app. For example, due to styling requirements, we want to move `

` from it's deeply nested position to the `

` with `id="endofbody"` @@ -101,4 +99,4 @@ A common use case scenario would be a reusable `` component of which ther
``` -You can check `` component options in the [API reference]() +You can check `` component options in the [API reference](../api/built-in-components.html#teleport) From 93c7528e9736ef1978d1ce2f3f2d3e5aed28dece Mon Sep 17 00:00:00 2001 From: Natalia Tepluhina Date: Fri, 3 Jul 2020 11:29:04 +0300 Subject: [PATCH 03/10] Update src/api/built-in-components.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Thorsten Lünborg --- src/api/built-in-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/built-in-components.md b/src/api/built-in-components.md index 9bbf7ad36e..f168000b6a 100644 --- a/src/api/built-in-components.md +++ b/src/api/built-in-components.md @@ -223,7 +223,7 @@ - + From ee6cce1d8dcfb588eb561cb2ea2d47a4f0a88cc6 Mon Sep 17 00:00:00 2001 From: Natalia Tepluhina Date: Fri, 3 Jul 2020 11:29:16 +0300 Subject: [PATCH 04/10] Update src/api/built-in-components.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Thorsten Lünborg --- src/api/built-in-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/built-in-components.md b/src/api/built-in-components.md index f168000b6a..eb8bd0ccbd 100644 --- a/src/api/built-in-components.md +++ b/src/api/built-in-components.md @@ -232,7 +232,7 @@ ``` - - `disabled` - `boolean`. This optional prop can be used to disable the portal's functionality, which means that its slot content will not be moved anywhere and instead be rendered where you specified the `` in the surrounding parent component. + - `disabled` - `boolean`. This optional prop can be used to disable the ``'s functionality, which means that its slot content will not be moved anywhere and instead be rendered where you specified the `` in the surrounding parent component. ```html From 5543a16ca003a2c74fd4ce8b2f99827c38a0d935 Mon Sep 17 00:00:00 2001 From: Natalia Tepluhina Date: Fri, 3 Jul 2020 11:29:24 +0300 Subject: [PATCH 05/10] Update src/guide/teleport.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Thorsten Lünborg --- src/guide/teleport.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/guide/teleport.md b/src/guide/teleport.md index 6a70122e68..ec85b76132 100644 --- a/src/guide/teleport.md +++ b/src/guide/teleport.md @@ -51,7 +51,7 @@ As you can see, all of the children of `` will be appended to `
`'s parent: +If `` contains a Vue component, it will remain a logical child component of the ``'s parent: ```js const app = Vue.createApp({ From 68e13a321381533d654502c13d659b1fac144d4a Mon Sep 17 00:00:00 2001 From: Natalia Tepluhina Date: Fri, 3 Jul 2020 11:29:36 +0300 Subject: [PATCH 06/10] Update src/guide/teleport.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Thorsten Lünborg --- src/guide/teleport.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/guide/teleport.md b/src/guide/teleport.md index ec85b76132..3958e6477d 100644 --- a/src/guide/teleport.md +++ b/src/guide/teleport.md @@ -19,7 +19,7 @@ However, sometimes a part of a component's template belongs into this component ``` -To do so, we can use Vue built-in `` component: +To do so, we can use Vue's built-in `` component: ```html From ef340951be7145211675b60e37da98fa2cfb4fa2 Mon Sep 17 00:00:00 2001 From: Natalia Tepluhina Date: Fri, 3 Jul 2020 11:29:43 +0300 Subject: [PATCH 07/10] Update src/guide/teleport.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Thorsten Lünborg --- src/guide/teleport.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/guide/teleport.md b/src/guide/teleport.md index 3958e6477d..b03ec2b9cd 100644 --- a/src/guide/teleport.md +++ b/src/guide/teleport.md @@ -80,6 +80,8 @@ app.component('child-component', { In this case, even when `child-component` is rendered in the different place, it will remain a child of `parent-component` and will receive a `name` prop from it. +This also means that injections from a parent component work as expected, and that the child component will be nested below the parent component in the Vue Devtools, instead of being placed where the actual content moved to. + ## Using multiple teleports on the same target A common use case scenario would be a reusable `` component of which there might be multiple instances active at the same time. For this kind of scenario, multiple `` components can mount their content to the same target element. The order will be a simple append - later mounts will be located after earlier ones within the target element. From 4850af1bae1b8a7eec2b368837fde0723b22d93e Mon Sep 17 00:00:00 2001 From: Natalia Tepluhina Date: Fri, 3 Jul 2020 11:29:52 +0300 Subject: [PATCH 08/10] Update src/api/built-in-components.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Thorsten Lünborg --- src/api/built-in-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/built-in-components.md b/src/api/built-in-components.md index eb8bd0ccbd..f7671b78f5 100644 --- a/src/api/built-in-components.md +++ b/src/api/built-in-components.md @@ -239,5 +239,5 @@ ``` - +Notice that this will move the actual DOM nodes instead of being destroyed and recreated, and it will keep any component instances alive as well. All stateful HTML elements (i.e. a playing video) will keep their state. - **See also:** [Teleport component](..//guide/teleport.html#teleport) From 39b163c84feec55a769173ea8ea787bf84589af1 Mon Sep 17 00:00:00 2001 From: NataliaTepluhina Date: Fri, 3 Jul 2020 11:31:18 +0300 Subject: [PATCH 09/10] fix: moved h1 to 'wrong' section --- src/api/built-in-components.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/api/built-in-components.md b/src/api/built-in-components.md index f7671b78f5..9c32cd374f 100644 --- a/src/api/built-in-components.md +++ b/src/api/built-in-components.md @@ -224,11 +224,9 @@ - - + + ``` @@ -239,5 +237,7 @@ ``` -Notice that this will move the actual DOM nodes instead of being destroyed and recreated, and it will keep any component instances alive as well. All stateful HTML elements (i.e. a playing video) will keep their state. + + Notice that this will move the actual DOM nodes instead of being destroyed and recreated, and it will keep any component instances alive as well. All stateful HTML elements (i.e. a playing video) will keep their state. + - **See also:** [Teleport component](..//guide/teleport.html#teleport) From d4f0f107a58eeecc3af97dcc3015f5e0e60c17f5 Mon Sep 17 00:00:00 2001 From: NataliaTepluhina Date: Fri, 3 Jul 2020 11:31:42 +0300 Subject: [PATCH 10/10] fix: typo --- src/api/built-in-components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/api/built-in-components.md b/src/api/built-in-components.md index 9c32cd374f..c59f326b8f 100644 --- a/src/api/built-in-components.md +++ b/src/api/built-in-components.md @@ -240,4 +240,4 @@ Notice that this will move the actual DOM nodes instead of being destroyed and recreated, and it will keep any component instances alive as well. All stateful HTML elements (i.e. a playing video) will keep their state. -- **See also:** [Teleport component](..//guide/teleport.html#teleport) +- **See also:** [Teleport component](../guide/teleport.html#teleport)