Skip to content

Commit ada130c

Browse files
author
User
committed
added Built-In Components APIs
1 parent 9c228e1 commit ada130c

File tree

5 files changed

+427
-1
lines changed

5 files changed

+427
-1
lines changed

‎API.js

Lines changed: 20 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ const I_D = require('./apis/instancedata')
1111
const I_E = require('./apis/instanceevents')
1212
const I_L = require('./apis/instancelifecycle')
1313
const D = require('./apis/directives')
14+
const S_A = require('./apis/specialattributes')
15+
const B_C = require('./apis/builtincomp')
1416

1517

1618
const GlobalConfig = [
@@ -144,6 +146,21 @@ const Directives = [
144146
D.V_ONCE
145147
]
146148

149+
const SpecialAttributes = [
150+
S_A.KEY,
151+
S_A.REF,
152+
S_A.SLOT,
153+
S_A.IS
154+
]
155+
156+
const BuiltInComponents = [
157+
B_C.COMPONENT,
158+
B_C.TRANSITION,
159+
B_C.TRANSITION_GROUP,
160+
B_C.KEEP_ALIVE,
161+
B_C.SLOT_COMPONENT
162+
]
163+
147164

148165
module.exports = {
149166
GlobalConfig,
@@ -158,5 +175,7 @@ module.exports = {
158175
InstanceData,
159176
InstanceEvents,
160177
InstanceLifecycle,
161-
Directives
178+
Directives,
179+
SpecialAttributes,
180+
BuiltInComponents
162181
}

‎apis/builtincomp.js

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
const chalk = require('chalk')
2+
const custom = require('../customcolors')
3+
const colorComment = custom.colorComment
4+
const colorPrimitive = custom.colorPrimitive
5+
const colorError = custom.colorError
6+
const colorArgs = custom.colorArgs
7+
8+
9+
const cat = 'Built-In Components'
10+
11+
const COMPONENT = {
12+
category: cat,
13+
name: `component`,
14+
props: `
15+
16+
* ${colorArgs(`is`)} - string | ComponentDefinition | ComponentConstructor
17+
* ${colorArgs(`inline-template`)} - boolean
18+
19+
`,
20+
usage: `A “meta component” for rendering dynamic components.
21+
The actual component to render is determined by the ${colorArgs(`is`)} prop:
22+
23+
${colorComment(`<!-- a dynamic component controlled by -->`)}
24+
${colorComment(`<!-- the 'componentId' property on the vm -->`)}
25+
${chalk.blue(`<component :is=${chalk.green(`"componentId"`)}></component>`)}
26+
27+
${colorComment(`<!-- can also render registered component or component passed as prop -->`)}
28+
${chalk.blue(`<component :is=${chalk.green(`"$options.components.child"`)}></component>`)}
29+
30+
31+
`
32+
}
33+
const TRANSITION = {
34+
category: cat,
35+
name: `transition`,
36+
props: `
37+
38+
* ${colorArgs(`name`)} - string, Used to automatically generate transition CSS class names.
39+
e.g. ${colorArgs(`name: 'fade'`)} will auto expand to ${colorArgs(`.fade-enter`)},
40+
${colorArgs(`.fade-enter-active`)}, etc. Defaults to ${colorArgs(`"v"`)}.
41+
* ${colorArgs(`appear`)} - boolean, Whether to apply transition on initial render. Defaults to ${colorArgs(`false`)}.
42+
* ${colorArgs(`css`)} - boolean, Whether to apply CSS transition classes. Defaults to ${colorArgs(`true`)}.
43+
If set to ${colorArgs(`false`)}, will only trigger JavaScript hooks registered via component events.
44+
* ${colorArgs(`type`)} - string, Specify the type of transition events to wait for to determine transition end timing.
45+
Available values are ${colorArgs(`"transition"`)} and ${colorArgs(`"animation"`)}.
46+
By default, it will automatically detect the type that has a longer duration.
47+
* ${colorArgs(`mode`)} - string, Controls the timing sequence of leaving/entering transitions. Available modes are
48+
${colorArgs(`"out-in"`)} and ${colorArgs(`"in-out"`)}; defaults to simultaneous.
49+
* ${colorArgs(`enter-class`)} - string
50+
* ${colorArgs(`leave-class`)} - string
51+
* ${colorArgs(`appear-class`)} - string
52+
* ${colorArgs(`enter-to-class`)} - string
53+
* ${colorArgs(`leave-to-class`)} - string
54+
* ${colorArgs(`appear-to-class`)} - string
55+
* ${colorArgs(`enter-active-class`)} - string
56+
* ${colorArgs(`leave-active-class`)} - string
57+
* ${colorArgs(`appear-active-class`)} - string
58+
`,
59+
events: `
60+
61+
* ${colorArgs(`before-enter`)}
62+
* ${colorArgs(`before-leave`)}
63+
* ${colorArgs(`before-appear`)}
64+
* ${colorArgs(`enter`)}
65+
* ${colorArgs(`leave`)}
66+
* ${colorArgs(`appear`)}
67+
* ${colorArgs(`after-enter`)}
68+
* ${colorArgs(`after-leave`)}
69+
* ${colorArgs(`after-appear`)}
70+
* ${colorArgs(`enter-cancelled`)}
71+
* ${colorArgs(`enter-cancelled`)} (v-show only)
72+
* ${colorArgs(`appear-cancelled`)}
73+
74+
`,
75+
usage: `${colorArgs(`<transition>`)} serve as transition effects for ${chalk.bold(`single`)} element/component.
76+
The ${colorArgs(`<transition>`)} does not render an extra DOM element,
77+
nor does it show up in the inspected component hierarchy.
78+
It simply applies the transition behavior to the wrapped content inside.
79+
80+
${colorComment(`<!-- simple element -->`)}
81+
${chalk.blue(`<transition>
82+
<div v-if=${chalk.green(`"ok"`)}>${chalk.black(`toggled content`)}</div>
83+
</transition>
84+
85+
${colorComment(`<!-- dynamic component -->`)}
86+
<transition name=${chalk.green(`"fade"`)} mode=${chalk.green(`"out-in"`)} appear>
87+
<component :is=${chalk.green(`"view"`)}></component>
88+
</transition>
89+
90+
${colorComment(`<!-- event hooking -->`)}
91+
<div id=${chalk.green(`"transition-demo"`)}>
92+
<transition @after-enter=${chalk.green(`"transitionComplete"`)}>
93+
<div v-show=${chalk.green(`"ok"`)}>${chalk.black(`toggled content`)}</div>
94+
</transition>
95+
</div>`)}
96+
97+
${colorArgs(`new`)} Vue({
98+
...
99+
methods: {
100+
transitionComplete: ${chalk.blue(`function`)} (el) {
101+
${colorComment(`// for passed 'el' that DOM element as the argument, something ...`)}
102+
}
103+
}
104+
...
105+
}).$mount(${chalk.green(`'#transition-demo'`)})
106+
107+
`
108+
}
109+
const TRANSITION_GROUP = {
110+
category: cat,
111+
name: `transition-group`,
112+
props: `
113+
114+
115+
* ${colorArgs(`tag`)} - string, defaults to ${colorArgs(`span`)}.
116+
* ${colorArgs(`move-class`)} - overwrite CSS class applied during moving transition.
117+
* exposes the same props as ${colorArgs(`<transition>`)} except ${colorArgs(`mode`)}.
118+
`,
119+
events: `
120+
121+
* exposes the same events as ${colorArgs(`<transition>`)}.
122+
`,
123+
usage: `${colorArgs(`<transition-group>`)} serve as transition effects for ${chalk.bold(`multiple`)}
124+
elements/components. The ${colorArgs(`<transition-group>`)} renders a real DOM element.
125+
By default it renders a ${colorArgs(`<span>`)}, and you can configure what element it
126+
should render via the ${colorArgs(`tag`)} attribute. Note every child in a ${colorArgs(`<transition-group>`)}
127+
must be ${chalk.bold(`uniquely keyed`)} for the animations to work properly.
128+
129+
${colorArgs(`<transition-group>`)} supports moving transitions via CSS transform.
130+
When a child’s position on screen has changed after an updated,
131+
it will get applied a moving CSS class (auto generated from the ${colorArgs(`name`)} attribute
132+
or configured with the ${colorArgs(`move-class`)} attribute). If the CSS transform property is
133+
“transition-able” when the moving class is applied, the element will be smoothly
134+
animated to its destination using the ${chalk.green(`FLIP technique`)}.
135+
136+
${chalk.blue(`<transition-group tag=${chalk.green(`"ul"`)} name=${chalk.green(`"slide"`)}>
137+
<li v-for=${chalk.green(`"item in items"`)} :key=${chalk.green(`"item.id"`)}>
138+
${chalk.black(`{{ item.text }}`)}
139+
</li>
140+
</transition-group>`)}
141+
`
142+
}
143+
const KEEP_ALIVE = {
144+
category: cat,
145+
name: 'keep-alive',
146+
props: `
147+
148+
149+
* ${colorArgs(`include`)} - string or RegExp or Array. Only components matched by this will be cached.
150+
* ${colorArgs(`exclude`)} - string or RegExp or Array. Any component matched by this will not be cached.
151+
`,
152+
usage: `When wrapped around a dynamic component, ${colorArgs(`<keep-alive>`)} caches
153+
the inactive component instances without destroying them.
154+
Similar to ${colorArgs(`<transition>`)}, ${colorArgs(`<keep-alive>`)} is an abstract component:
155+
it doesn’t render a DOM element itself, and doesn’t show up
156+
in the component parent chain.
157+
158+
When a component is toggled inside ${colorArgs(`<keep-alive>`)}, its ${colorArgs(`activated`)}
159+
and ${colorArgs(`deactivated`)} lifecycle hooks will be invoked accordingly.
160+
161+
In 2.2.0 and above, ${colorArgs(chalk.bold(`activated`))} and ${colorArgs(chalk.bold(`deactivated`))} will fire for all
162+
nested components inside a ${colorArgs(chalk.bold(`<keep-alive>`))} tree.
163+
164+
Primarily used with preserve component state or avoid re-rendering.
165+
166+
${colorComment(`<!-- basic -->`)}
167+
${chalk.blue(`<keep-alive>
168+
<component :is=${chalk.green(`"view"`)}></component>
169+
</keep-alive>
170+
${colorComment(`<!-- multiple conditional children -->`)}
171+
<keep-alive>
172+
<comp-a v-if=${chalk.green(`"a > 1"`)}></comp-a>
173+
<comp-b v-else></comp-b>
174+
</keep-alive>
175+
${colorComment(`<!-- used together with <transition> -->`)}
176+
<transition>
177+
<keep-alive>
178+
<component :is=${chalk.green(`"view"`)}></component>
179+
</keep-alive>
180+
</transition>`)}
181+
182+
183+
Note, ${colorArgs(`<keep-alive>`)} is designed for the case where it has one
184+
direct child component that is being toggled. It does not work if you
185+
have ${colorArgs(`v-for`)} inside it. When there are multiple conditional children,
186+
as above, ${colorArgs(`<keep-alive>`)} requires that only one child is rendered
187+
at a time.
188+
189+
${chalk.underline(`include and exclude`)}
190+
191+
${chalk.bold(`New in 2.1.0`)}
192+
193+
The ${colorArgs(chalk.bold('include'))} and ${colorArgs(chalk.bold('exclude'))} props allow components to be conditionally cached.
194+
Both props can be a comma-delimited string, a RegExp or an Array:
195+
196+
${colorComment(`<!-- comma-delimited string -->`)}
197+
${chalk.blue(`<keep-alive include=${chalk.green(`"a,b"`)}>
198+
<component :is=${chalk.green(`"view"`)}></component>
199+
</keep-alive>
200+
${colorComment(`<!-- regex (use v-bind) -->`)}
201+
<keep-alive :include=${chalk.green(`"/a|b/"`)}>
202+
<component :is=${chalk.green(`"view"`)}></component>
203+
</keep-alive>
204+
${colorComment(`<!-- Array (use v-bind) -->`)}
205+
<keep-alive :include=${chalk.green(`"['a', 'b']"`)}>
206+
<component :is=${chalk.green(`"view"`)}></component>
207+
</keep-alive>`)}
208+
209+
The match is first checked on the component’s own ${colorArgs(`name`)} option,
210+
then its local registration name (the key in the parent’s ${colorArgs(`components`)}
211+
option) if the ${colorArgs(`name`)} option is not available. Anonymous components
212+
cannot be matched against.
213+
214+
${colorArgs(`<keep-alive>`)} does not work with functional components because they
215+
do not have instances to be cached.
216+
217+
218+
`
219+
}
220+
const SLOT_COMPONENT = {
221+
category: cat,
222+
name: 'slot',
223+
props: `
224+
225+
* ${colorArgs('slot')} -string, Used for named slot.
226+
`,
227+
usage: `
228+
229+
${colorArgs(`<slot>`)} serve as content distribution outlets in component templates.
230+
${colorArgs(`<slot>`)} itself will be replaced.
231+
232+
`
233+
}
234+
235+
236+
module.exports = {
237+
COMPONENT,
238+
TRANSITION,
239+
TRANSITION_GROUP,
240+
KEEP_ALIVE,
241+
SLOT_COMPONENT
242+
}

‎apis/specialattributes.js

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
const chalk = require('chalk')
2+
const custom = require('../customcolors')
3+
const colorComment = custom.colorComment
4+
const colorPrimitive = custom.colorPrimitive
5+
const colorError = custom.colorError
6+
const colorArgs = custom.colorArgs
7+
8+
const cat = 'Special Attributes'
9+
10+
const KEY = {
11+
category: cat,
12+
name: 'key',
13+
expects: 'string',
14+
details: `The ${colorArgs(`key`)} special attribute is primarily used as a hint for
15+
Vue’s virtual DOM algorithm to identify VNodes when diffing the new list
16+
of nodes against the old list. Without keys, Vue uses an algorithm
17+
that minimizes element movement and tries to patch/reuse elements of the same type
18+
in-place as much as possible. With keys, it will reorder elements based on the order
19+
change of keys, and elements with keys that are no longer present will always be removed/destroyed.
20+
Children of the same common parent must have ${chalk.bold(`unique keys`)}. Duplicate keys will cause render errors.
21+
The most common use case is combined with ${colorArgs(`v-for`)}:
22+
23+
${chalk.blue(`<ul>
24+
<li v-for=${chalk.green(`"item in items" :key="item.id"`)}>${chalk.black(`...`)}</li>
25+
</ul>`)}
26+
27+
It can also be used to force replacement of an element/component instead of reusing it.
28+
This can be useful when you want to:
29+
30+
* Properly trigger lifecycle hooks of a component
31+
* Trigger transitions
32+
`,
33+
example:`
34+
${chalk.blue(`<transition>
35+
<span :key=${chalk.green(`"text"`)}>${chalk.black(`{{ text }}`)}</span>
36+
</transition>`)}
37+
38+
When ${colorArgs(`text`)} changes, the ${colorArgs(`<span>`)} will always be replaced instead of patched,
39+
so a transition will be triggered.
40+
`
41+
}
42+
const REF = {
43+
category: cat,
44+
name: `ref`,
45+
expects: `string`,
46+
details: `${colorArgs(`ref`)} is used to register a reference to an element or a child component.
47+
The reference will be registered under the parent component’s ${colorArgs(`$refs`)} object.
48+
If used on a plain DOM element, the reference will be that element;
49+
if used on a child component, the reference will be component instance:
50+
51+
${colorComment(`<!-- vm.$refs.p will be the DOM node -->`)}
52+
${chalk.blue(`<p ref=${chalk.green(`"p"`)}>${chalk.black(`hello`)}</p>
53+
${colorComment(`<!-- vm.$refs.child will be the child comp instance -->`)}
54+
<child-comp ref=${chalk.green(`"child"`)}></child-comp>`)}
55+
56+
When used on elements/components with ${colorArgs(`v-for`)}, the registered reference will
57+
be an Array containing DOM nodes or component instances.
58+
An important note about the ref registration timing: because the refs
59+
themselves are created as a result of the render function, you cannot
60+
access them on the initial render - they don’t exist yet! ${colorArgs(`$refs`)} is also
61+
non-reactive, therefore you should not attempt to use it in templates for data-binding.
62+
`
63+
}
64+
const SLOT = {
65+
category: cat,
66+
name: 'slot',
67+
expects: 'string',
68+
details: `Used on content inserted into child components to indicate which named slot the content belongs to.
69+
For detailed usage, see the guide section linked below.`
70+
}
71+
const IS = {
72+
category: cat,
73+
name: 'is',
74+
expects: 'string',
75+
details: `Used for dynamic components and to work around limitations of in-DOM templates.`,
76+
example: `
77+
${colorArgs(`<!-- component changes when currentView changes -->`)}
78+
${chalk.blue(`<component v-bind:is=${chalk.green(`"currentView"`)}></component>
79+
${colorComment(`<!-- necessary because <my-row> would be invalid inside -->
80+
<!-- a <table> element and so would be hoisted out -->`)}
81+
<table>
82+
<tr is=${chalk.green(`"my-row"`)}></tr>
83+
</table>`)}
84+
`
85+
}
86+
87+
88+
module.exports = {
89+
KEY,
90+
REF,
91+
SLOT,
92+
IS
93+
}

‎logfunctions/logbuiltincomp.js

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
const chalk = require('chalk')
2+
const custom = require('../customcolors')
3+
const args = custom.colorArgs
4+
module.exports = {
5+
logBuiltInComp: function(obj){
6+
return(
7+
`
8+
${chalk.green('Category:')} ${obj.category}
9+
${chalk.green('Name:')} ${obj.name + '\n'}
10+
${obj.props ? `* Props: ${obj.props}` : ''}
11+
${obj.events ? `* Event: ${obj.events}` : ''}
12+
${obj.usage ? `* Usage: ${obj.usage}` : ``}
13+
${obj.example ? `* Example: ${obj.example}` : ''}
14+
`
15+
)
16+
}
17+
}

0 commit comments

Comments
 (0)