Skip to content

Commit 28e8074

Browse files
NataliaTepluhinaphanan
NataliaTepluhina
and
phanan
authored
Built-in components API (#96)
* feat: added built-in components * Update src/api/built-in-components.md Co-authored-by: Phan An <me@phanan.net> * Update src/api/built-in-components.md Co-authored-by: Phan An <me@phanan.net> * fix: fixed types formatting Co-authored-by: Phan An <me@phanan.net>
1 parent 1e5f8fa commit 28e8074

File tree

4 files changed

+217
-2
lines changed

4 files changed

+217
-2
lines changed

‎src/.vuepress/config.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,7 @@ const sidebar = {
106106
'/api/instance-methods',
107107
'/api/directives',
108108
'/api/special-attributes',
109+
'/api/built-in-components.md',
109110
{
110111
title: 'Reactivity API',
111112
collapsable: false,

‎src/api/built-in-components.md

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# Built-In Components
2+
3+
## component
4+
5+
- **Props:**
6+
7+
- `is` - `string | ComponentDefinition | ComponentConstructor`
8+
9+
- **Usage:**
10+
11+
A "meta component" for rendering dynamic components. The actual component to render is determined by the `is` prop:
12+
13+
```html
14+
<!-- a dynamic component controlled by -->
15+
<!-- the `componentId` property on the vm -->
16+
<component :is="componentId"></component>
17+
18+
<!-- can also render registered component or component passed as prop -->
19+
<component :is="$options.components.child"></component>
20+
```
21+
22+
- **See also:** [Dynamic Components](../guide/component-dynamic-async.html)
23+
24+
## transition
25+
26+
- **Props:**
27+
28+
- `name` - `string` Used to automatically generate transition CSS class names. e.g. `name: 'fade'` will auto expand to `.fade-enter`, `.fade-enter-active`, etc.
29+
- `appear` - `boolean`, Whether to apply transition on initial render. Defaults to `false`.
30+
- `persisted` - `boolean`. If true, indicates this is a transition that doesn't actually insert/remove the element, but toggles the show / hidden status instead. The transition hooks are injected, but will be skipped by the renderer. Instead, a custom directive can control the transition by calling the injected hooks (e.g. `v-show`).
31+
- `css` - `boolean`. Whether to apply CSS transition classes. Defaults to `true`. If set to `false`, will only trigger JavaScript hooks registered via component events.
32+
- `type` - `string`. Specifies the type of transition events to wait for to determine transition end timing. Available values are `"transition"` and `"animation"`. By default, it will automatically detect the type that has a longer duration.
33+
- `mode` - `wtring` Controls the timing sequence of leaving/entering transitions. Available modes are `"out-in"` and `"in-out"`; defaults to simultaneous.
34+
- `duration` - `number | {`enter`: number,`leave`: number }`. Specifies the duration of transition. By default, Vue waits for the first `transitionend` or `animationend` event on the root transition element.
35+
- `enter-from-class` - `string`
36+
- `leave-from-class` - `string`
37+
- `appear-class` - `string`
38+
- `enter-to-class` - `string`
39+
- `leave-to-class` - `string`
40+
- `appear-to-class` - `string`
41+
- `enter-active-class` - `string`
42+
- `leave-active-class` - `string`
43+
- `appear-active-class` - `string`
44+
45+
- **Events:**
46+
47+
- `before-enter`
48+
- `before-leave`
49+
- `enter`
50+
- `leave`
51+
- `after-enter`
52+
- `after-leave`
53+
- `enter-cancelled`
54+
- `leave-cancelled` (`v-show` only)
55+
56+
- **Usage:**
57+
58+
`<transition>` serve as transition effects for **single** element/component. The `<transition>` only applies the transition behavior to the wrapped content inside; it doesn't render an extra DOM element, or show up in the inspected component hierarchy.
59+
60+
```html
61+
<!-- simple element -->
62+
<transition>
63+
<div v-if="ok">toggled content</div>
64+
</transition>
65+
66+
<!-- dynamic component -->
67+
<transition name="fade" mode="out-in" appear>
68+
<component :is="view"></component>
69+
</transition>
70+
71+
<!-- event hooking -->
72+
<div id="transition-demo">
73+
<transition @after-enter="transitionComplete">
74+
<div v-show="ok">toggled content</div>
75+
</transition>
76+
</div>
77+
```
78+
79+
```js
80+
const app = Vue.createApp({
81+
...
82+
methods: {
83+
transitionComplete (el) {
84+
// for passed 'el' that DOM element as the argument, something ...
85+
}
86+
}
87+
...
88+
})
89+
90+
app.mount('#transition-demo')
91+
```
92+
93+
- **See also:** [Transitions: Entering, Leaving, and Lists](TODO)
94+
95+
## transition-group
96+
97+
- **Props:**
98+
99+
- `tag` - `string`, defaults to `span`.
100+
- `move-class` - overwrite CSS class applied during moving transition.
101+
- exposes the same props as `<transition>` except `mode`.
102+
103+
- **Events:**
104+
105+
- exposes the same events as `<transition>`.
106+
107+
- **Usage:**
108+
109+
`<transition-group>` serve as transition effects for **multiple** elements/components. The `<transition-group>` renders a real DOM element. By default it renders a `<span>`, and you can configure what element it should render via the `tag` attribute.
110+
111+
Note that every child in a `<transition-group>` must be [**uniquely keyed**](./special-attributes.html#key) for the animations to work properly.
112+
113+
`<transition-group>` supports moving transitions via CSS transform. When a child's position on screen has changed after an update, it will get applied a moving CSS class (auto generated from the `name` attribute or configured with the `move-class` attribute). If the CSS `transform` property is "transition-able" when the moving class is applied, the element will be smoothly animated to its destination using the [FLIP technique](https://aerotwist.com/blog/flip-your-animations/).
114+
115+
```html
116+
<transition-group tag="ul" name="slide">
117+
<li v-for="item in items" :key="item.id">
118+
{{ item.text }}
119+
</li>
120+
</transition-group>
121+
```
122+
123+
- **See also:** [Transitions: Entering, Leaving, and Lists](TODO)
124+
125+
## keep-alive
126+
127+
- **Props:**
128+
129+
- `include` - `string | RegExp | Array`. Only components with matching names will be cached.
130+
- `exclude` - `string | RegExp | Array`. Any component with a matching name will not be cached.
131+
- `max` - `number | string`. The maximum number of component instances to cache.
132+
133+
- **Usage:**
134+
135+
When wrapped around a dynamic component, `<keep-alive>` caches the inactive component instances without destroying them. Similar to `<transition>`, `<keep-alive>` is an abstract component: it doesn't render a DOM element itself, and doesn't show up in the component parent chain.
136+
137+
When a component is toggled inside `<keep-alive>`, its `activated` and `deactivated` lifecycle hooks will be invoked accordingly.
138+
139+
Primarily used to preserve component state or avoid re-rendering.
140+
141+
```html
142+
<!-- basic -->
143+
<keep-alive>
144+
<component :is="view"></component>
145+
</keep-alive>
146+
147+
<!-- multiple conditional children -->
148+
<keep-alive>
149+
<comp-a v-if="a > 1"></comp-a>
150+
<comp-b v-else></comp-b>
151+
</keep-alive>
152+
153+
<!-- used together with `<transition>` -->
154+
<transition>
155+
<keep-alive>
156+
<component :is="view"></component>
157+
</keep-alive>
158+
</transition>
159+
```
160+
161+
Note, `<keep-alive>` is designed for the case where it has one direct child component that is being toggled. It does not work if you have `v-for` inside it. When there are multiple conditional children, as above, `<keep-alive>` requires that only one child is rendered at a time.
162+
163+
- **`include` and `exclude`**
164+
165+
The `include` and `exclude` props allow components to be conditionally cached. Both props can be a comma-delimited string, a RegExp or an Array:
166+
167+
```html
168+
<!-- comma-delimited string -->
169+
<keep-alive include="a,b">
170+
<component :is="view"></component>
171+
</keep-alive>
172+
173+
<!-- regex (use `v-bind`) -->
174+
<keep-alive :include="/a|b/">
175+
<component :is="view"></component>
176+
</keep-alive>
177+
178+
<!-- Array (use `v-bind`) -->
179+
<keep-alive :include="['a', 'b']">
180+
<component :is="view"></component>
181+
</keep-alive>
182+
```
183+
184+
The match is first checked on the component's own `name` option, then its local registration name (the key in the parent's `components` option) if the `name` option is not available. Anonymous components cannot be matched against.
185+
186+
- **`max`**
187+
188+
The maximum number of component instances to cache. Once this number is reached, the cached component instance that was least recently accessed will be destroyed before creating a new instance.
189+
190+
```html
191+
<keep-alive :max="10">
192+
<component :is="view"></component>
193+
</keep-alive>
194+
```
195+
196+
::: warning
197+
`<keep-alive>` does not work with functional components because they do not have instances to be cached.
198+
:::
199+
200+
- **See also:** [Dynamic Components - keep-alive](../guide/component-dynamic-async.html#dynamic-components-with-keep-alive)
201+
202+
## slot
203+
204+
- **Props:**
205+
206+
- `name` - `string`, Used for named slot.
207+
208+
- **Usage:**
209+
210+
`<slot>` serve as content distribution outlets in component templates. `<slot>` itself will be replaced.
211+
212+
For detailed usage, see the guide section linked below.
213+
214+
- **See also:** [Content Distribution with Slots](../guide/component-basics.html#content-distribution-with-slots)

‎src/api/instance-properties.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -114,7 +114,7 @@
114114
```
115115

116116
- **See also:**
117-
- [`<slot>` Component](TODO)
117+
- [`<slot>` Component](built-in-components.html#slot)
118118
- [Content Distribution with Slots](../guide/component-basics.html#content-distribution-with-slots)
119119
- [Render Functions - Slots](..guide/render-function.html#slots)
120120

‎src/guide/component-dynamic-async.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ Check out the result below:
4141

4242
Now the _Posts_ tab maintains its state (the selected post) even when it's not rendered.
4343

44-
Check out more details on `<keep-alive>` in the [API reference](TODO:../api/#keep-alive).
44+
Check out more details on `<keep-alive>` in the [API reference](../api/built-in-components.html#keep-alive).
4545

4646
## Async Components
4747

0 commit comments

Comments
 (0)