Skip to content

Commit d0031d8

Browse files
antfuantfu
committed
Merge branch 'master' into rc
2 parents 9d3b241 + 6e4e949 commit d0031d8

File tree

1 file changed

+139
-48
lines changed

1 file changed

+139
-48
lines changed

‎README.md

Lines changed: 139 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ Vue 2 plugin for **Composition API**
55
[![npm](https://img.shields.io/npm/v/@vue/composition-api)](https://www.npmjs.com/package/@vue/composition-api)
66
[![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)
77

8-
English | [中文](./README.zh-CN.md) · [**Composition API Docs**](https://composition-api.vuejs.org/)
8+
English | [中文](./README.zh-CN.md) ・ [**Composition API Docs**](https://composition-api.vuejs.org/)
99

1010
## Installation
1111

@@ -69,14 +69,43 @@ export default defineComponent({
6969

7070
To make JSX/TSX work with `@vue/composition-api`, check out [babel-preset-vca-jsx](https://github.com/luwanquan/babel-preset-vca-jsx) by [@luwanquan](https://github.com/luwanquan).
7171

72+
73+
74+
## SSR
75+
76+
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.
77+
78+
```js
79+
import { onServerPrefetch } from '@vue/composition-api'
80+
81+
export default {
82+
setup (props, { ssrContext }) {
83+
const result = ref()
84+
85+
onServerPrefetch(async () => {
86+
result.value = await callApi(ssrContext.someId)
87+
})
88+
89+
return {
90+
result,
91+
}
92+
},
93+
};
94+
```
95+
7296
## Limitations
7397

7498
> :white_check_mark:
7599
> Support     :x: Not Supported
76100
77-
### Performance Impact
101+
### `Ref` Unwrap
78102

79-
Due the the limitation of Vue2's public API. `@vue/composition-api` inevitably introduced some extract costs.
103+
`Unwrap` is not working with Array index.
104+
105+
<details>
106+
<summary>
107+
❌ <b>Should NOT</b> store <code>ref</code> as a <b>direct</b> child of <code>Array</code>
108+
</summary>
80109

81110
You can check the [benchmark results](https://antfu.github.io/vue-composition-api-benchmark-results/) for more details.
82111

@@ -99,7 +128,13 @@ state.list.push(ref(1))
99128
state.list[1].value === 1 // true
100129
```
101130

102-
#### **Should NOT** use `ref` in a plain object when working with `Array`:
131+
</details>
132+
133+
<details>
134+
<summary>
135+
❌ <b>Should NOT</b> use <code>ref</code> in a plain object when working with <code>Array</code>
136+
</summary>
137+
103138

104139
```js
105140
const a = {
@@ -126,42 +161,42 @@ const b = reactive({
126161
b.list[0].count.value === 0 // true
127162
```
128163

129-
#### **Should** always use `ref` in a `reactive` when working with `Array`:
164+
</details>
165+
166+
<details>
167+
<summary>
168+
✅ <b>Should</b> always use <code>ref</code> in a <code>reactive</code> when working with <code>Array</code>
169+
</summary>
130170

131171
```js
132172
const a = reactive({
133-
count: ref(0),
134-
})
135-
const b = reactive({
136-
list: [a],
173+
list: [
174+
reactive({
175+
count: ref(0),
176+
})
177+
],
137178
})
138179
// unwrapped
139-
b.list[0].count === 0 // true
180+
a.list[0].count === 0 // true
140181

141-
b.list.push(
182+
a.list.push(
142183
reactive({
143184
count: ref(1),
144185
})
145186
)
146187
// unwrapped
147-
b.list[1].count === 1 // true
188+
a.list[1].count === 1 // true
148189
```
149190

150-
### :warning: `reactive` ***mutates*** the original object
151-
152-
`reactive` uses `Vue.observable` underneath which will ***mutate*** the original object.
153-
154-
> :bulb: Vue 3 will return an new proxy object.
155-
156-
157-
### `watch()` API
191+
</details>
158192

159-
:x: `onTrack` and `onTrigger` are not available in `WatchOptions`.
160193

161194
### Template Refs
162195

163-
:white_check_mark:
164-
String ref && return it from `setup()`:
196+
<details>
197+
<summary>
198+
✅ String ref && return it from <code>setup()</code>
199+
</summary>
165200

166201
```html
167202
<template>
@@ -186,8 +221,13 @@ String ref && return it from `setup()`:
186221
</script>
187222
```
188223

189-
:white_check_mark:
190-
String ref && return it from `setup()` && Render Function / JSX:
224+
</details>
225+
226+
227+
<details>
228+
<summary>
229+
✅ String ref && return it from <code>setup()</code> && Render Function / JSX
230+
</summary>
191231

192232
```jsx
193233
export default {
@@ -209,8 +249,13 @@ export default {
209249
},
210250
}
211251
```
252+
</details>
253+
212254

213-
:x: Function ref:
255+
<details>
256+
<summary>
257+
❌ Function ref
258+
</summary>
214259

215260
```html
216261
<template>
@@ -230,7 +275,13 @@ export default {
230275
</script>
231276
```
232277

233-
:x: Render Function / JSX in `setup()`:
278+
</details>
279+
280+
281+
<details>
282+
<summary>
283+
❌ Render Function / JSX in <code>setup()</code>
284+
</summary>
234285

235286
```jsx
236287
export default {
@@ -248,15 +299,18 @@ export default {
248299
}
249300
```
250301

302+
</details>
303+
251304
<details>
252-
<summary><code>$refs</code> accessing workaround
305+
<summary>
306+
⚠️ <code>$refs</code> accessing workaround
253307
</summary>
254308

255309
<br>
256310

257311
> :warning: **Warning**: The `SetupContext.refs` won't exist in `Vue 3.0`. `@vue/composition-api` provide it as a workaround here.
258312
259-
If you really want to use template refs in this case, you can access `vm.$refs` via `SetupContext.refs`.
313+
If you really want to use template refs in this case, you can access `vm.$refs` via `SetupContext.refs`
260314

261315

262316
```jsx
@@ -293,10 +347,59 @@ declare module '@vue/composition-api' {
293347

294348
</details>
295349

350+
### Reactive
351+
352+
<details>
353+
<summary>
354+
⚠️ <code>reactive()</code> <b>mutates</b> the original object
355+
</summary>
356+
357+
`reactive` uses `Vue.observable` underneath which will ***mutate*** the original object.
358+
359+
> :bulb: In Vue 3, it will return an new proxy object.
360+
361+
362+
</details>
363+
364+
### Watch
365+
366+
<details>
367+
<summary>
368+
❌ <code>onTrack</code> and <code>onTrigger</code> are not available in <code>WatchOptions</code>
369+
</summary>
370+
371+
```js
372+
watch(() => {
373+
/* ... */
374+
}, {
375+
immediate: true,
376+
onTrack() {}, // not available
377+
onTrigger() {}, // not available
378+
})
379+
```
380+
381+
</details>
382+
383+
### Missing APIs
384+
385+
The following APIs introduced in Vue 3 are not available in this plugin.
296386

297-
### :x: Reactive APIs in `data()`
387+
- `readonly`
388+
- `shallowReadonly`
389+
- `defineAsyncComponent`
390+
- `onRenderTracked`
391+
- `onRenderTriggered`
392+
- `customRef`
393+
- `isProxy`
394+
- `isReadonly`
395+
- `isVNode`
298396

299-
Passing `ref`, `reactive` or other reactive apis to `data()` would not work.
397+
### Reactive APIs in `data()`
398+
399+
<details>
400+
<summary>
401+
❌ Passing <code>ref</code>, <code>reactive</code> or other reactive apis to <code>data()</code> would not work.
402+
</summary>
300403

301404
```jsx
302405
export default {
@@ -306,27 +409,15 @@ export default {
306409
a: ref(1)
307410
}
308411
},
309-
};
412+
}
310413
```
311414

312-
## SSR
415+
</details>
313416

314-
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.
315417

316-
```js
317-
import { onServerPrefetch } from '@vue/composition-api'
418+
### Performance Impact
318419

319-
export default {
320-
setup (props, { ssrContext }) {
321-
const result = ref()
420+
Due the the limitation of Vue2's public API. `@vue/composition-api` inevitably introduced some extract costs. It shouldn't bother you unless in extreme environments.
322421

323-
onServerPrefetch(async () => {
324-
result.value = await callApi(ssrContext.someId)
325-
})
422+
You can check the [benchmark results](https://antfu.github.io/vue-composition-api-benchmark-results/) for more details.
326423

327-
return {
328-
result,
329-
}
330-
},
331-
}
332-
```

0 commit comments

Comments
 (0)