Skip to content

Commit 9c228e1

Browse files
author
User
committed
Added Directives APIs
1 parent ae9ebd5 commit 9c228e1

File tree

4 files changed

+461
-2
lines changed

4 files changed

+461
-2
lines changed

‎API.js

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ const I_P = require('./apis/instanceproperties')
1010
const I_D = require('./apis/instancedata')
1111
const I_E = require('./apis/instanceevents')
1212
const I_L = require('./apis/instancelifecycle')
13+
const D = require('./apis/directives')
1314

1415

1516
const GlobalConfig = [
@@ -127,6 +128,22 @@ const InstanceLifecycle = [
127128
I_L.VM_$DESTROY
128129
]
129130

131+
const Directives = [
132+
D.V_TEXT,
133+
D.V_HTML,
134+
D.V_SHOW,
135+
D.V_IF,
136+
D.V_ELSE,
137+
D.V_ELSE_IF,
138+
D.V_FOR,
139+
D.V_ON,
140+
D.V_BIND,
141+
D.V_MODEL,
142+
D.V_PRE,
143+
D.V_CLOAK,
144+
D.V_ONCE
145+
]
146+
130147

131148
module.exports = {
132149
GlobalConfig,
@@ -140,5 +157,6 @@ module.exports = {
140157
InstanceProperties,
141158
InstanceData,
142159
InstanceEvents,
143-
InstanceLifecycle
160+
InstanceLifecycle,
161+
Directives
144162
}

‎apis/directives.js

Lines changed: 341 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,341 @@
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 = 'Directives'
9+
10+
11+
const V_TEXT = {
12+
category: cat,
13+
name: 'v-text',
14+
expects: 'string',
15+
details: `Updates the element’s ${colorArgs(`textContent`)}. If you need to update
16+
the part of ${colorArgs(`textContent`)}, you should use ${colorArgs(`{{ Mustache }}`)} interpolations.`,
17+
example: `
18+
${chalk.blue(`<span v-text=${chalk.green(`"msg"`)}></span>
19+
${colorComment(`<!-- same as -->`)}
20+
<span>${chalk.black(`{{msg}}`)}</span>`)}
21+
`
22+
}
23+
const V_HTML = {
24+
category: cat,
25+
name: `v-html`,
26+
expects: 'string',
27+
details: `Updates the element’s ${colorArgs(`innerHTML`)}. ${chalk.bold(`Note that the contents
28+
are inserted as plain HTML - they will not be compiled
29+
as Vue templates`)}. If you find yourself trying to compose
30+
templates using ${colorArgs(`v-html`)}, try to rethink the solution by
31+
using components instead.
32+
Dynamically rendering arbitrary HTML on your website
33+
can be very dangerous because it can easily lead to ${chalk.green(`XSS attacks`)}.
34+
Only use ${colorArgs(`v-html`)} on trusted content and never on user-provided content.
35+
36+
`,
37+
example: `
38+
${chalk.blue(`<div v-html=${chalk.green('"html"')}></div>`)}`
39+
}
40+
const V_SHOW = {
41+
category: cat,
42+
name: 'v-show',
43+
expects: 'any',
44+
usage: `Toggle’s the element’s ${colorArgs(`display`)} CSS property based
45+
on the truthy-ness of the expression value. This directive triggers
46+
transitions when its condition changes.`
47+
}
48+
const V_IF = {
49+
category: cat,
50+
name: 'v-if',
51+
expects: 'any',
52+
usage: `Conditionally render the element based on the truthy-ness
53+
of the expression value. The element and its contained directives / components
54+
are destroyed and re-constructed during toggles. If the element is a
55+
${colorArgs(`<template>`)} element, its content will be extracted as the conditional block.
56+
This directive triggers transitions when its condition changes.
57+
When used together with v-if, v-for has a higher priority than v-if.
58+
See the ${chalk.green(`list rendering guide`)} for details.
59+
`
60+
}
61+
const V_ELSE = {
62+
category: cat,
63+
name: 'v-else',
64+
expects: 'Does not expect expression',
65+
restriction: `previous sibling element must have ${colorArgs('v-if')} or ${colorArgs(`v-else-if`)}`,
66+
usage: `Denote the “else block” for ${colorArgs(`v-if`)} or a ${colorArgs(`v-if`)}/${colorArgs(`v-else-if`)} chain.
67+
${chalk.blue(`<div v-if=${chalk.green(`"Math.random() > 0.5"`)}>
68+
${chalk.black(`Now you see me`)}
69+
</div>
70+
<div v-else>
71+
${chalk.black(`Now you don't`)}
72+
</div>`)}`
73+
}
74+
const V_ELSE_IF = {
75+
category: cat,
76+
name: `v-else-if`,
77+
expects: 'any',
78+
restriction: `previous sibling element must have ${colorArgs('v-if')} or ${colorArgs(`v-else-if`)}`,
79+
usage: `Denote the “else if block” for ${colorArgs(`v-if`)}. Can be chained.
80+
${chalk.blue(`<div v-if=${chalk.green(`"type === 'A'"`)}>
81+
${chalk.black(`A`)}
82+
</div>
83+
<div v-else-if=${chalk.green(`"type === 'B'"`)}>
84+
${chalk.black(`B`)}
85+
</div>
86+
<div v-else-if=${chalk.green(`"type === 'C'"`)}>
87+
${chalk.black(`C`)}
88+
</div>
89+
<div v-else>
90+
${chalk.black(`Not A/B/C`)}
91+
</div>`)}
92+
`
93+
}
94+
const V_FOR = {
95+
category: cat,
96+
name: `v-for`,
97+
expects: `Array | Object | number | string`,
98+
usage: `Render the element or template block multiple times
99+
based on the source data. The directive’s value must use
100+
the special syntax ${colorArgs(`alias in expression`)} to provide an alias
101+
for the current element being iterated on:
102+
103+
${chalk.blue(`<div v-for=${chalk.green(`"item in items"`)}>
104+
${chalk.black(`{{ item.text }}`)}
105+
</div>`)}
106+
107+
Alternatively, you can also specify an alias for the index
108+
(or the key if used on an Object):
109+
110+
${chalk.blue(`<div v-for=${chalk.green(`"(item, index) in items"`)}></div>
111+
<div v-for=${chalk.green(`"(val, key) in object"`)}></div>
112+
<div v-for=${chalk.green(`"(val, key, index) in object"`)}></div>`)}
113+
114+
The default behavior of ${colorArgs(`v-for`)} will try to patch the elements
115+
in-place without moving them. To force it to reorder elements, you need to
116+
provide an ordering hint with the ${colorArgs(`key`)} special attribute:
117+
118+
${chalk.blue(`<div v-for=${chalk.green(`"item in items" :key="item.id"`)}>
119+
${chalk.black(`{{ item.text }}`)}
120+
</div>`)}
121+
122+
When used together with v-if, v-for has a higher priority than v-if.
123+
See the ${chalk.green(`list rendering guide for details`)}.`
124+
}
125+
const V_ON = {
126+
category: cat,
127+
name: `v-on`,
128+
shorthand: '@',
129+
expects: `Function | Inline Statement | Object`,
130+
arguments: [
131+
`event`
132+
],
133+
modifiers: `
134+
135+
${colorArgs(`.stop`)} - call ${colorArgs(`event.stopPropagation()`)}.
136+
${colorArgs(`.prevent`)} - call ${colorArgs(`event.preventDefault()`)}.
137+
${colorArgs(`.capture`)} - add event listener in capture mode.
138+
${colorArgs(`.self`)} - only trigger handler if event was dispatched from this element.
139+
${colorArgs(`.{keyCode | keyAlias}`)} - only trigger handler on certain keys.
140+
${colorArgs(`.native`)} - listen for a native event on the root element of component.
141+
${colorArgs(`.once`)} - trigger handler at most once.
142+
${colorArgs(`.left`)} - (2.2.0+) only trigger handler for left button mouse events.
143+
${colorArgs(`.right`)} - (2.2.0+) only trigger handler for right button mouse events.
144+
${colorArgs(`.middle`)} - (2.2.0+) only trigger handler for middle button mouse events.
145+
${colorArgs(`.passive`)} - (2.3.0+) attaches a DOM event with ${colorArgs(`{ passive: true }`)}.`,
146+
147+
usage: `Attaches an event listener to the element. The event type
148+
is denoted by the argument. The expression can either be
149+
a method name or an inline statement, or simply omitted
150+
when there are modifiers present. Starting in ${colorArgs(`2.4.0`)}, ${colorArgs(`v-on`)} also
151+
supports binding to an object of event/listener pairs without
152+
an argument. Note when using the object syntax, it does not support any modifiers.
153+
When used on a normal element, it listens to ${chalk.bold(`native DOM events`)} only.
154+
When used on a custom element component, it also listens to ${chalk.bold(`custom events`)}
155+
emitted on that child component. When listening to native DOM events,
156+
the method receives the native event as the only argument.
157+
If using inline statement, the statement has access to the
158+
special ${colorArgs(`$event`)} property: ${colorArgs(`v-on:click="handle('ok', $event)"`)}.`,
159+
example: `
160+
${colorComment(`<!-- method handler -->`)}
161+
${chalk.blue(`<button v-on:click=${chalk.green(`"doThis"`)}></button>
162+
${colorComment(`<!-- object syntax (2.4.0+) -->`)}
163+
<button v-on=${chalk.green(`"{ mousedown: doThis, mouseup: doThat }"`)}></button>
164+
${colorComment(`<!-- inline statement -->`)}
165+
<button v-on:click=${chalk.green(`"doThat('hello', $event)"`)}></button>
166+
${colorComment(`<!-- shorthand -->`)}
167+
<button @click=${chalk.green(`"doThis"`)}></button>
168+
${colorComment(`<!-- stop propagation -->`)}
169+
<button @click.stop=${chalk.green(`"doThis"`)}></button>
170+
${colorComment(`<!-- prevent default -->`)}
171+
<button @click.prevent=${chalk.green(`"doThis"`)}></button>
172+
${colorComment(`<!-- prevent default without expression -->`)}
173+
<form @submit.prevent></form>
174+
${colorComment(`<!-- chain modifiers -->`)}
175+
<button @click.stop.prevent=${chalk.green(`"doThis"`)}></button>
176+
${colorComment(`<!-- key modifier using keyAlias -->`)}
177+
<input @keyup.enter=${chalk.green(`"onEnter"`)}>
178+
${colorComment(`<!-- key modifier using keyCode -->`)}
179+
<input @keyup.13=${chalk.green(`"onEnter"`)}>
180+
${colorComment(`<!-- the click event will be triggered at most once -->`)}
181+
<button v-on:click.once=${chalk.green(`"doThis"`)}></button>`)}
182+
183+
184+
Listening to custom events on a child component
185+
(the handler is called when “my-event” is emitted on the child):
186+
187+
${chalk.blue(`<my-component @my-event=${chalk.green(`"handleThis"`)}></my-component>
188+
${colorComment(`<!-- inline statement -->`)}
189+
<my-component @my-event=${chalk.green(`"handleThis(123, $event)"`)}></my-component>
190+
${colorComment(`<!-- native event on component -->`)}
191+
<my-component @click.native=${chalk.green(`"onClick"`)}></my-component>`)}
192+
`
193+
}
194+
const V_BIND = {
195+
category: cat,
196+
name: 'v-bind',
197+
shorthand: ':',
198+
expects: `any (with arguments) | Object (without argument)`,
199+
arguments: [
200+
`attrOrProp (optional)`
201+
],
202+
modifiers: `
203+
${colorArgs(`.prop`)} - Bind as a DOM property instead of an attribute (what’s the difference?).
204+
If the tag is a component then ${colorArgs(`.prop`)} will set the property on the component’s ${colorArgs(`$el`)}.
205+
${colorArgs(`.camel`)} - (2.1.0+) transform the kebab-case attribute name into camelCase.
206+
${colorArgs(`.sync`)} - (2.3.0+) a syntax sugar that expands into a ${colorArgs(`v-on`)} handler for updating the bound value.`,
207+
208+
usage: `Dynamically bind one or more attributes, or a component prop to an expression.
209+
When used to bind the ${colorArgs(`class`)} or ${colorArgs(`style`)} attribute, it supports additional value types
210+
such as Array or Objects. See linked guide section below for more details.
211+
When used for prop binding, the prop must be properly declared in the child component.
212+
When used without an argument, can be used to bind an object containing attribute name-value pairs.
213+
Note in this mode ${colorArgs(`class`)} and ${colorArgs(`style`)} does not support Array or Objects.`,
214+
215+
example: `
216+
${colorComment(`<!-- bind an attribute -->`)}
217+
<img v-bind:src=${chalk.green(`"imageSrc"`)}>
218+
${colorComment(`<!-- shorthand -->`)}
219+
<img :src=${chalk.green(`"imageSrc"`)}>
220+
${colorComment(`<!-- with inline string concatenation -->`)}
221+
<img :src=${chalk.green(`"'/path/to/images/' + fileName"`)}>
222+
${colorComment(`<!-- class binding -->`)}
223+
<div :class=${chalk.green(`"{ red: isRed }"`)}></div>
224+
<div :class=${chalk.green(`"[classA, classB]"`)}></div>
225+
<div :class=${chalk.green(`"[classA, { classB: isB, classC: isC }]"`)}>
226+
${colorComment(`<!-- style binding -->`)}
227+
<div :style=${chalk.green(`"{ fontSize: size + 'px' }"`)}></div>
228+
<div :style=${chalk.green(`"[styleObjectA, styleObjectB]"`)}></div>
229+
${colorComment(`<!-- binding an object of attributes -->`)}
230+
<div v-bind=${chalk.green(`"{ id: someProp, 'other-attr': otherProp }"`)}></div>
231+
${colorComment(`<!-- DOM attribute binding with prop modifier -->`)}
232+
<div v-bind:text-content.prop=${chalk.green(`"text"`)}></div>
233+
${colorComment(`<!-- prop binding. "prop" must be declared in my-component. -->`)}
234+
<my-component :prop=${chalk.green(`"someThing"`)}></my-component>
235+
${colorComment(`<!-- pass down parent props in common with a child component -->`)}
236+
<child-component v-bind=${chalk.green(`"$props"`)}></child-component>
237+
${colorComment(`<!-- XLink -->`)}
238+
<svg><a :xlink:special=${chalk.green(`"foo"`)}></a></svg>
239+
240+
The ${colorArgs(`.camel`)} modifier allows camelizing a ${colorArgs(`v-bind`)} attribute name when using in-DOM templates,
241+
e.g. the SVG ${colorArgs(`viewBox`)} attribute:
242+
243+
${chalk.blue(`<svg :view-box.camel=${chalk.green(`"viewBox"`)}></svg>`)}
244+
245+
${colorArgs(`.camel`)} is not needed if you are using string templates,
246+
or compiling with ${colorArgs(`vue-loader`)}/${colorArgs(`vueify`)}.
247+
248+
249+
`
250+
}
251+
const V_MODEL = {
252+
category: cat,
253+
name: `v-model`,
254+
expects: `varies based on value of form inputs element or output of components`,
255+
limited: `
256+
* ${colorArgs('<input>')}
257+
* ${colorArgs('<select>')}
258+
* ${colorArgs('<textarea>')}
259+
* components
260+
`,
261+
modifiers: `
262+
263+
${colorArgs(`.lazy`)} - listen to ${colorArgs(`change`)} events instead of ${colorArgs(`input`)}
264+
${colorArgs(`.number`)} - cast input string to numbers
265+
${colorArgs(`.trim`)} - trim input
266+
`,
267+
usage: `Create a two-way binding on a form input element or a component.
268+
For detailed usage and other notes, see the Guide section linked below.
269+
`
270+
}
271+
const V_PRE = {
272+
category: cat,
273+
name: 'v-pre',
274+
expects: 'Does not expect expression',
275+
usage: `Skip compilation for this element and all its children.
276+
You can use this for displaying raw mustache tags. Skipping large
277+
numbers of nodes with no directives on them can also speed up compilation.`,
278+
example: `
279+
${chalk.blue(`<span v-pre>${chalk.black(`{{ this will not be compiled }}`)}</span>`)}
280+
`
281+
}
282+
const V_CLOAK = {
283+
category: cat,
284+
name: `v-cloak`,
285+
expects: `Does not expect expression`,
286+
usage: `This directive will remain on the element until the associated
287+
Vue instance finishes compilation. Combined with CSS rules
288+
such as ${colorArgs(`[v-cloak] { display: none }`)}, this directive can be used to hide
289+
un-compiled mustache bindings until the Vue instance is ready.`,
290+
example: `
291+
[v-cloak] {
292+
${colorArgs(`display`)}: none;
293+
}
294+
295+
${chalk.blue(`<div v-cloak>
296+
${chalk.black(`{{ message }}`)}
297+
</div>`)}
298+
299+
The ${colorArgs(`<div>`)} will not be visible until the compilation is done.
300+
301+
`
302+
}
303+
const V_ONCE = {
304+
category: cat,
305+
name: `v-once`,
306+
expects: `Does not expect expression`,
307+
details: `Render the element and component ${chalk.bold(`once`)} only.
308+
On subsequent re-renders, the element/component and all its children
309+
will be treated as static content and skipped.
310+
This can be used to optimize update performance.
311+
312+
${colorComment(`<!-- single element -->`)}
313+
${chalk.blue(`<span v-once>${chalk.black(`This will never change: {{msg}}`)}</span>
314+
${colorComment(`<!-- the element have children -->`)}
315+
<div v-once>
316+
<h1>${chalk.black(`comment`)}</h1>
317+
<p>${chalk.black(`{{msg}}`)}</p>
318+
</div>
319+
${colorComment(`<!-- component -->`)}
320+
<my-component v-once :comment=${chalk.green('"msg"')}></my-component>
321+
${colorComment(`<!-- v-for directive -->`)}
322+
<ul>
323+
<li v-for=${chalk.green(`"i in list"`)} v-once>${chalk.black(`{{i}}`)}</li>
324+
</ul>`)}`
325+
}
326+
327+
module.exports = {
328+
V_TEXT,
329+
V_HTML,
330+
V_SHOW,
331+
V_IF,
332+
V_ELSE,
333+
V_ELSE_IF,
334+
V_FOR,
335+
V_ON,
336+
V_BIND,
337+
V_MODEL,
338+
V_PRE,
339+
V_CLOAK,
340+
V_ONCE
341+
}

0 commit comments

Comments
 (0)