@dcloudio/vue-cli-plugin-uni 2.0.1-alpha-36320220919002 → 2.0.1-alpha-36720221014001

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,558 @@
1
+ # @vue/composition-api
2
+
3
+ Vue 2 plugin for **Composition API**
4
+
5
+ [![npm](https://img.shields.io/npm/v/@vue/composition-api)](https://www.npmjs.com/package/@vue/composition-api)
6
+ [![GitHub Workflow Status](https://img.shields.io/github/workflow/status/vuejs/composition-api/Build%20&%20Test)](https://github.com/vuejs/composition-api/actions?query=workflow%3A%22Build+%26+Test%22)
7
+ [![Minzipped size](https://badgen.net/bundlephobia/minzip/@vue/composition-api)](https://bundlephobia.com/result?p=@vue/composition-api)
8
+
9
+ English | [中文](./README.zh-CN.md) ・ [**Composition API Docs**](https://v3.vuejs.org/guide/composition-api-introduction.html)
10
+
11
+
12
+ > ⚠️ With the release of [Vue 2.7](https://blog.vuejs.org/posts/vue-2-7-naruto.html), which has Composition API built-in, **you no longer need this plugin**. Thereby this plugin has entered maintenance mode and will only support Vue 2.6 or earlier. This project will reach End of Life by the end of 2022.
13
+
14
+ ## Installation
15
+
16
+ ### NPM
17
+
18
+ ```bash
19
+ npm install @vue/composition-api
20
+ # or
21
+ yarn add @vue/composition-api
22
+ ```
23
+
24
+ You must install `@vue/composition-api` as a plugin via `Vue.use()` before you can use the [Composition API](https://composition-api.vuejs.org/) to compose your component.
25
+
26
+ ```js
27
+ import Vue from 'vue'
28
+ import VueCompositionAPI from '@vue/composition-api'
29
+
30
+ Vue.use(VueCompositionAPI)
31
+ ```
32
+
33
+ ```js
34
+ // use the APIs
35
+ import { ref, reactive } from '@vue/composition-api'
36
+ ```
37
+
38
+ > :bulb: When you migrate to Vue 3, just replacing `@vue/composition-api` to `vue` and your code should just work.
39
+
40
+ ### CDN
41
+
42
+ Include `@vue/composition-api` after Vue and it will install itself automatically.
43
+
44
+ <!--cdn-links-start-->
45
+ ```html
46
+ <script src="https://cdn.jsdelivr.net/npm/vue@2.6"></script>
47
+ <script src="https://cdn.jsdelivr.net/npm/@vue/composition-api@1.7.0"></script>
48
+ ```
49
+ <!--cdn-links-end-->
50
+
51
+ `@vue/composition-api` will be exposed to global variable `window.VueCompositionAPI`.
52
+
53
+ ```ts
54
+ const { ref, reactive } = VueCompositionAPI
55
+ ```
56
+
57
+ ## TypeScript Support
58
+
59
+ > TypeScript version **>4.2** is required
60
+
61
+ To let TypeScript properly infer types inside Vue component options, you need to define components with `defineComponent`
62
+
63
+ ```ts
64
+ import { defineComponent } from '@vue/composition-api'
65
+
66
+ export default defineComponent({
67
+ // type inference enabled
68
+ })
69
+ ```
70
+
71
+ ### JSX/TSX
72
+
73
+ JSX is now officially supported on [vuejs/jsx](https://github.com/vuejs/jsx). You can enable it by following [this document](https://github.com/vuejs/jsx/tree/dev/packages/babel-preset-jsx#usage). A community maintained version can be found at [babel-preset-vca-jsx](https://github.com/luwanquan/babel-preset-vca-jsx) by [@luwanquan](https://github.com/luwanquan).
74
+
75
+ To support TSX, create a declaration file with the following content in your project.
76
+
77
+ ```ts
78
+ // file: shim-tsx.d.ts
79
+ import Vue, { VNode } from 'vue';
80
+ import { ComponentRenderProxy } from '@vue/composition-api';
81
+
82
+ declare global {
83
+ namespace JSX {
84
+ interface Element extends VNode {}
85
+ interface ElementClass extends ComponentRenderProxy {}
86
+ interface ElementAttributesProperty {
87
+ $props: any; // specify the property name to use
88
+ }
89
+ interface IntrinsicElements {
90
+ [elem: string]: any;
91
+ }
92
+ }
93
+ }
94
+ ```
95
+
96
+ ## SSR
97
+
98
+ Even if there is no definitive Vue 3 API for SSR yet, this plugin implements the `onServerPrefetch` lifecycle hook that allows you to use the `serverPrefetch` hook found in the classic API.
99
+
100
+ ```js
101
+ import { onServerPrefetch } from '@vue/composition-api'
102
+
103
+ export default {
104
+ setup(props, { ssrContext }) {
105
+ const result = ref()
106
+
107
+ onServerPrefetch(async () => {
108
+ result.value = await callApi(ssrContext.someId)
109
+ })
110
+
111
+ return {
112
+ result,
113
+ }
114
+ }
115
+ }
116
+ ```
117
+
118
+ ## Browser Compatibility
119
+
120
+ `@vue/composition-api` supports all modern browsers and IE11+. For lower versions IE you should install `WeakMap` polyfill (for example from `core-js` package).
121
+
122
+ ## Limitations
123
+
124
+ > :white_check_mark: Support &nbsp;&nbsp;&nbsp;&nbsp;:x: Not Supported
125
+
126
+ ### `Ref` Unwrap
127
+
128
+ <details>
129
+ <summary>
130
+ ❌ <b>Should NOT</b> use <code>ref</code> in a plain object when working with <code>Array</code>
131
+ </summary>
132
+
133
+ ```js
134
+ const a = {
135
+ count: ref(0),
136
+ }
137
+ const b = reactive({
138
+ list: [a], // `a.count` will not unwrap!!
139
+ })
140
+
141
+ // no unwrap for `count`, `.value` is required
142
+ b.list[0].count.value === 0 // true
143
+ ```
144
+
145
+ ```js
146
+ const b = reactive({
147
+ list: [
148
+ {
149
+ count: ref(0), // no unwrap!!
150
+ },
151
+ ],
152
+ })
153
+
154
+ // no unwrap for `count`, `.value` is required
155
+ b.list[0].count.value === 0 // true
156
+ ```
157
+
158
+ </details>
159
+
160
+ <details>
161
+ <summary>
162
+ ✅ <b>Should</b> always use <code>ref</code> in a <code>reactive</code> when working with <code>Array</code>
163
+ </summary>
164
+
165
+ ```js
166
+ const a = reactive({
167
+ list: [
168
+ reactive({
169
+ count: ref(0),
170
+ }),
171
+ ]
172
+ })
173
+ // unwrapped
174
+ a.list[0].count === 0 // true
175
+
176
+ a.list.push(
177
+ reactive({
178
+ count: ref(1),
179
+ })
180
+ )
181
+ // unwrapped
182
+ a.list[1].count === 1 // true
183
+ ```
184
+
185
+ </details>
186
+
187
+ ### Template Refs
188
+
189
+ <details>
190
+ <summary>
191
+ ✅ String ref && return it from <code>setup()</code>
192
+ </summary>
193
+
194
+ ```html
195
+ <template>
196
+ <div ref="root"></div>
197
+ </template>
198
+
199
+ <script>
200
+ export default {
201
+ setup() {
202
+ const root = ref(null)
203
+
204
+ onMounted(() => {
205
+ // the DOM element will be assigned to the ref after initial render
206
+ console.log(root.value) // <div/>
207
+ })
208
+
209
+ return {
210
+ root,
211
+ }
212
+ },
213
+ }
214
+ </script>
215
+ ```
216
+
217
+ </details>
218
+
219
+ <details>
220
+ <summary>
221
+ ✅ String ref && return it from <code>setup()</code> && Render Function / JSX
222
+ </summary>
223
+
224
+ ```jsx
225
+ export default {
226
+ setup() {
227
+ const root = ref(null)
228
+
229
+ onMounted(() => {
230
+ // the DOM element will be assigned to the ref after initial render
231
+ console.log(root.value) // <div/>
232
+ })
233
+
234
+ return {
235
+ root,
236
+ }
237
+ },
238
+ render() {
239
+ // with JSX
240
+ return () => <div ref="root" />
241
+ },
242
+ }
243
+ ```
244
+
245
+ </details>
246
+
247
+ <details>
248
+ <summary>
249
+ ❌ Function ref
250
+ </summary>
251
+
252
+ ```html
253
+ <template>
254
+ <div :ref="el => root = el"></div>
255
+ </template>
256
+
257
+ <script>
258
+ export default {
259
+ setup() {
260
+ const root = ref(null)
261
+
262
+ return {
263
+ root,
264
+ }
265
+ },
266
+ }
267
+ </script>
268
+ ```
269
+
270
+ </details>
271
+
272
+ <details>
273
+ <summary>
274
+ ❌ Render Function / JSX in <code>setup()</code>
275
+ </summary>
276
+
277
+ ```jsx
278
+ export default {
279
+ setup() {
280
+ const root = ref(null)
281
+
282
+ return () =>
283
+ h('div', {
284
+ ref: root,
285
+ })
286
+
287
+ // with JSX
288
+ return () => <div ref={root} />
289
+ },
290
+ }
291
+ ```
292
+
293
+ </details>
294
+
295
+ <details>
296
+ <summary>
297
+ ⚠️ <code>$refs</code> accessing workaround
298
+ </summary>
299
+
300
+ <br>
301
+
302
+ > :warning: **Warning**: The `SetupContext.refs` won't exist in `Vue 3.0`. `@vue/composition-api` provide it as a workaround here.
303
+
304
+ If you really want to use template refs in this case, you can access `vm.$refs` via `SetupContext.refs`
305
+
306
+ ```jsx
307
+ export default {
308
+ setup(initProps, setupContext) {
309
+ const refs = setupContext.refs
310
+ onMounted(() => {
311
+ // the DOM element will be assigned to the ref after initial render
312
+ console.log(refs.root) // <div/>
313
+ })
314
+
315
+ return () =>
316
+ h('div', {
317
+ ref: 'root',
318
+ })
319
+
320
+ // with JSX
321
+ return () => <div ref="root" />
322
+ },
323
+ }
324
+ ```
325
+
326
+ </details>
327
+
328
+ ### Reactive
329
+
330
+ <details>
331
+ <summary>
332
+ ⚠️ <code>reactive()</code> <b>mutates</b> the original object
333
+ </summary>
334
+
335
+ `reactive` uses `Vue.observable` underneath which will ***mutate*** the original object.
336
+
337
+ > :bulb: In Vue 3, it will return an new proxy object.
338
+
339
+ </details>
340
+
341
+ <details>
342
+ <summary>
343
+ ⚠️ <code>set</code> and <code>del</code> workaround for adding and deleting reactive properties
344
+ </summary>
345
+
346
+ > ⚠️ Warning: `set` and `del` do NOT exist in Vue 3. We provide them as a workaround here, due to the limitation of [Vue 2.x reactivity system](https://vuejs.org/v2/guide/reactivity.html#For-Objects).
347
+ >
348
+ > In Vue 2, you will need to call `set` to track new keys on an `object`(similar to `Vue.set` but for `reactive objects` created by the Composition API). In Vue 3, you can just assign them like normal objects.
349
+ >
350
+ > Similarly, in Vue 2 you will need to call `del` to [ensure a key deletion triggers view updates](https://vuejs.org/v2/api/#Vue-delete) in reactive objects (similar to `Vue.delete` but for `reactive objects` created by the Composition API). In Vue 3 you can just delete them by calling `delete foo.bar`.
351
+
352
+ ```ts
353
+ import { reactive, set, del } from '@vue/composition-api'
354
+
355
+ const a = reactive({
356
+ foo: 1
357
+ })
358
+
359
+ // add new reactive key
360
+ set(a, 'bar', 1)
361
+
362
+ // remove a key and trigger reactivity
363
+ del(a, 'bar')
364
+ ```
365
+
366
+ </details>
367
+
368
+ ### Watch
369
+
370
+ <details>
371
+ <summary>
372
+ ❌ <code>onTrack</code> and <code>onTrigger</code> are not available in <code>WatchOptions</code>
373
+ </summary>
374
+
375
+ ```js
376
+ watch(() => {
377
+ /* ... */
378
+ }, {
379
+ immediate: true,
380
+ onTrack() {}, // not available
381
+ onTrigger() {}, // not available
382
+ })
383
+ ```
384
+
385
+ </details>
386
+
387
+ ### `createApp`
388
+
389
+ <details>
390
+ <summary>
391
+ ⚠️ <code>createApp()</code> is global
392
+ </summary>
393
+
394
+ In Vue 3, `createApp()` is introduced to provide context(plugin, components, etc.) isolation between app instances. Due the the design of Vue 2, in this plugin, we provide `createApp()` as a forward compatible API which is just an alias of the global.
395
+
396
+ ```ts
397
+ const app1 = createApp(RootComponent1)
398
+ app1.component('Foo', Foo) // equivalent to Vue.component('Foo', Foo)
399
+ app1.use(VueRouter) // equivalent to Vue.use(VueRouter)
400
+
401
+ const app2 = createApp(RootComponent2)
402
+ app2.component('Bar', Bar) // equivalent to Vue.use('Bar', Bar)
403
+ ```
404
+
405
+ </details>
406
+
407
+ ### `createElement` / `h`
408
+
409
+ <details>
410
+ <summary>
411
+ ⚠️ <code>createElement</code> / <code>h</code> workaround
412
+ </summary>
413
+
414
+ <br>
415
+
416
+ `createElement` / `h` in Vue 2 is only accessable in `render()` function. To use it outside of `render()`, you can explicitly bind a component instance to it.
417
+
418
+ > :warning: **Warning**: This ability is provided as a workaround Vue 2, it's not part of the Vue 3 API.
419
+
420
+ ```jsx
421
+ import { h as _h } from '@vue/composition-api'
422
+
423
+ export default {
424
+ setup() {
425
+ const vm = getCurrentInstance()
426
+ const h = _h.bind(vm)
427
+
428
+ return () =>
429
+ h('div', {
430
+ ref: 'root',
431
+ })
432
+ },
433
+ }
434
+ ```
435
+
436
+ </details>
437
+
438
+
439
+ ### `shallowReadonly`
440
+
441
+ <details>
442
+ <summary>
443
+ ⚠️ <code>shallowReadonly()</code> will create a new object and with the same root properties, new properties added will <b>not</b> be readonly or reactive.
444
+ </summary>
445
+
446
+ > :bulb: In Vue 3, it will return an new proxy object.
447
+
448
+ </details>
449
+
450
+ ### `readonly`
451
+
452
+ <details>
453
+ <summary>
454
+ ⚠️ <code>readonly()</code> provides <b>only type-level</b> readonly check.
455
+ </summary>
456
+
457
+ `readonly()` is provided as API alignment with Vue 3 on type-level only. Use <code>isReadonly()</code> on it or it's properties can not be guaranteed.
458
+
459
+ </details>
460
+
461
+ ### `props`
462
+
463
+ <details>
464
+ <summary>
465
+ ⚠️ <code>toRefs(props.foo)</code> will incorrectly warn when accessing nested levels of props. <br>
466
+ &nbsp;&nbsp;&nbsp;&nbsp;⚠️ <code>isReactive(props.foo)</code> will return false.
467
+ </summary>
468
+
469
+ ```ts
470
+ defineComponent({
471
+ setup(props) {
472
+ const { bar } = toRefs(props.foo) // it will `warn`
473
+
474
+ // use this instead
475
+ const { foo } = toRefs(props)
476
+ const a = foo.value.bar
477
+ }
478
+ })
479
+ ```
480
+
481
+ </details>
482
+
483
+ ### `computed().effect`
484
+
485
+ <details>
486
+ <summary>
487
+ ⚠️ <code>computed()</code> has a property <code>effect</code> set to <code>true</code> instead of a <code>ReactiveEffect<T></code>.
488
+ </summary>
489
+
490
+ Due to the difference in implementation, there is no such concept as a `ReactiveEffect` in `@vue/composition-api`. Therefore, `effect` is merely `true` to enable differentiating computed from refs:
491
+
492
+ ```ts
493
+ function isComputed<T>(o: ComputedRef<T> | unknown): o is ComputedRef<T>
494
+ function isComputed(o: any): o is ComputedRef {
495
+ return !!(isRef(o) && o.effect)
496
+ }
497
+ ```
498
+
499
+ </details>
500
+
501
+ ### Missing APIs
502
+
503
+ The following APIs introduced in Vue 3 are not available in this plugin.
504
+
505
+ - `onRenderTracked`
506
+ - `onRenderTriggered`
507
+ - `isProxy`
508
+
509
+ ### Reactive APIs in `data()`
510
+
511
+ <details>
512
+ <summary>
513
+ ❌ Passing <code>ref</code>, <code>reactive</code> or other reactive apis to <code>data()</code> would not work.
514
+ </summary>
515
+
516
+ ```jsx
517
+ export default {
518
+ data() {
519
+ return {
520
+ // will result { a: { value: 1 } } in template
521
+ a: ref(1),
522
+ }
523
+ },
524
+ }
525
+ ```
526
+
527
+ </details>
528
+
529
+ ### `emits` Options
530
+
531
+ <details>
532
+ <summary>
533
+ ❌ <code>emits</code> option is provided in type-level only, in order to align with Vue 3's type interface. Does NOT have actual effects on the code.
534
+ </summary>
535
+
536
+ ```ts
537
+ defineComponent({
538
+ emits: {
539
+ // has no effects
540
+ submit: (eventOption) => {
541
+ if (...) {
542
+ return true
543
+ } else {
544
+ console.warn('Invalid submit event payload!')
545
+ return false
546
+ }
547
+ }
548
+ }
549
+ })
550
+ ```
551
+
552
+ </details>
553
+
554
+ ### Performance Impact
555
+
556
+ Due the the limitation of Vue2's public API. `@vue/composition-api` inevitably introduces some performance overhead. Note that in most scenarios, this shouldn't be the source of performance issues.
557
+
558
+ You can check the [benchmark results](https://antfu.github.io/vue-composition-api-benchmark-results/) for more details.