diff --git a/README.md b/README.md
index ebc92d76..d88b7b81 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,6 @@ Include `@vue/composition-api` after Vue and it will install itself automaticall
```ts
const { ref, reactive } = VueCompositionAPI
```
-
## TypeScript Support
@@ -95,8 +94,7 @@ export default {
## Limitations
-> :white_check_mark:
-> Support :x: Not Supported
+> :white_check_mark: Support :x: Not Supported
### `Ref` Unwrap
@@ -107,15 +105,6 @@ export default {
❌ Should NOT store ref
as a direct child of Array
-You can check the [benchmark results](https://antfu.github.io/vue-composition-api-benchmark-results/) for more details.
-
-
-### `Ref` Unwrap
-
-:x: `Unwrap` is not working with Array index.
-
-#### **Should NOT** store `ref` as a **direct** child of `Array`:
-
```js
const state = reactive({
list: [ref(0)],
diff --git a/README.zh-CN.md b/README.zh-CN.md
index ce805743..2dec35d9 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -5,27 +5,39 @@ Vue 2 插件用于提供 Vue 3 中的 **组合式 API**.
[![npm](https://img.shields.io/npm/v/@vue/composition-api)](https://www.npmjs.com/package/@vue/composition-api)
[![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)
-[**English**](./README.md) | 中文文档 / [**组合式 API RFC**](https://composition-api.vuejs.org/zh)
+[English](./README.md) | 中文 ・ [**组合式 API 文档**](https://composition-api.vuejs.org/zh)
-**请注意:此插件的主要目的是让社区尝试新的API并在其最终确定之前提供反馈。随着RFC的更新,该实现可能包含与RFC有细微的不一致。现阶段,我们暂不建议将此插件用于生产环境。**
----
+## 安装
-# 安装
-
-**npm**
+### NPM
```bash
-npm install @vue/composition-api --save
+npm install @vue/composition-api
+# or
+yarn add @vue/composition-api
```
-**yarn**
+在使用 `@vue/composition-api` 前,必须先先通过 `Vue.use()` 进行安装后方可使用使用新的 [**组合式 API**](https://composition-api.vuejs.org/zh) 进行组件开发。
-```bash
-yarn add @vue/composition-api
+```js
+import Vue from 'vue'
+import VueCompositionAPI from '@vue/composition-api'
+
+Vue.use(VueCompositionAPI)
```
-**CDN**
+```js
+// 使用 API
+import { ref, reactive } from '@vue/composition-api'
+```
+
+> :bulb: 当迁移到 Vue 3 时,只需简单的将 `@vue/composition-api` 替换成 `vue` 即可。你现有的代码几乎无需进行额外的改动。
+
+
+### CDN
+
+在 Vue 之后引入 `@vue/composition-api` 插件将会自动完成安装。
```html
@@ -34,96 +46,95 @@ yarn add @vue/composition-api
```
-通过全局变量 `window.VueCompositionAPI` 来使用。
-
-# 使用
+`@vue/composition-api` 将会暴露在全局变量 `window.VueCompositionAPI` 中。
-在使用任何 `@vue/composition-api` 提供的能力前,必须先通过 `Vue.use()` 进行安装:
-
-```js
-import Vue from 'vue';
-import VueCompositionAPI from '@vue/composition-api';
-
-Vue.use(VueCompositionAPI);
+```ts
+const { ref, reactive } = VueCompositionAPI
```
-安装插件后,您就可以使用新的 [Composition API](https://vue-composition-api-rfc.netlify.com/) 来开发组件了。
+## TypeScript 支持
-# TypeScript
-
-**本插件要求使用 TypeScript 3.5.1 以上版本,如果你正在使用 `vetur`,请将 `vetur.useWorkspaceDependencies` 设为 `true`。**
+> 本插件要求使用 TypeScript **3.5.1** 或以上版本
为了让 TypeScript 在 Vue 组件选项中正确地推导类型,我们必须使用 `defineComponent` 来定义组件:
```ts
-import { defineComponent } from '@vue/composition-api';
-
-const Component = defineComponent({
- // 启用类型推断
-});
+import { defineComponent } from '@vue/composition-api'
-const Component = {
- // 无法进行选项的类型推断
- // TypeScript 无法知道这是一个 Vue 组件的选项对象
-};
+export default defineComponent({
+ // 类型推断启用
+})
```
-## TSX
+### JSX/TSX
-:rocket: 这里有一个配置好 TS/TSX 支持的[示例仓库](https://github.com/liximomo/vue-composition-api-tsx-example)来帮助你快速开始.
+要使得 `@vue/composition-api` 支持 JSX/TSX,请前往查看由 [@luwanquan](https://github.com/luwanquan) 开发的 Babel 插件[babel-preset-vca-jsx](https://github.com/luwanquan/babel-preset-vca-jsx)。
-要支持 TSX,请创建一个类型定义文件并提供正确的 JSX 定义。内容如下:
+## SSR
-```ts
-// 文件: `shim-tsx.d.ts`
-import Vue, { VNode } from 'vue';
-import { ComponentRenderProxy } from '@vue/composition-api';
-
-declare global {
- namespace JSX {
- // tslint:disable no-empty-interface
- interface Element extends VNode {}
- // tslint:disable no-empty-interface
- interface ElementClass extends ComponentRenderProxy {}
- interface ElementAttributesProperty {
- $props: any; // 定义要使用的属性名称
- }
- interface IntrinsicElements {
- [elem: string]: any;
+尽管 Vue 3 暂时没有给出确定的 SSR 的 API,这个插件实现了 `onServerPrefetch` 生命周期钩子函数。这个钩子允许你使用在传统 API 中的 `serverPrefetch` 函数。
+
+```js
+import { onServerPrefetch } from '@vue/composition-api'
+
+export default {
+ setup (props, { ssrContext }) {
+ const result = ref()
+
+ onServerPrefetch(async () => {
+ result.value = await callApi(ssrContext.someId)
+ })
+
+ return {
+ result,
}
- }
+ },
}
```
-# 限制
+## 限制
+
+> :white_check_mark: 支持 :x: 不支持
+
-## `Ref` 自动展开 (unwrap)
+### `Ref` 自动展开 (unwrap)
数组索引属性无法进行自动展开:
-### **不要**使用 `Array` 直接存取 `ref` 对象:
+
+
+
+❌ 不要 使用数组直接存取 ref
对象
+
```js
const state = reactive({
list: [ref(0)],
-});
+})
// 不会自动展开, 须使用 `.value`
-state.list[0].value === 0; // true
+state.list[0].value === 0 // true
-state.list.push(ref(1));
+state.list.push(ref(1))
// 不会自动展开, 须使用 `.value`
-state.list[1].value === 1; // true
+state.list[1].value === 1 // true
```
-### **不要**在数组中使用含有 `ref` 的普通对象:
+
+
+
+
+
+❌ 不要 在数组中使用含有 ref
的普通对象
+
+
```js
const a = {
count: ref(0),
-};
+}
const b = reactive({
list: [a], // `a.count` 不会自动展开!!
-});
+})
// `count` 不会自动展开, 须使用 `.value`
b.list[0].count.value === 0; // true
@@ -136,51 +147,47 @@ const b = reactive({
count: ref(0), // 不会自动展开!!
},
],
-});
+})
// `count` 不会自动展开, 须使用 `.value`
b.list[0].count.value === 0; // true
```
-### **应该**总是将 `ref` 存放到 `reactive` 对象中:
+
+
+
+
+
+✅ 在数组中,应该 总是将 ref
存放到 reactive
对象中
+
```js
const a = reactive({
count: ref(0),
-});
+})
const b = reactive({
list: [a],
-});
+})
// 自动展开
-b.list[0].count === 0; // true
+b.list[0].count === 0 // true
b.list.push(
reactive({
count: ref(1),
})
-);
+)
// 自动展开
b.list[1].count === 1; // true
```
-### `reactive` 会返回一个修改过的原始的对象
-
-此行为与 Vue 2 中的 `Vue.observable` 一致
-> Vue 3 中会返回一个新的的代理对象.
-
----
-
-## `watch()` API
-
-不支持 `onTrack` 和 `onTrigger` 选项。
+
----
+### 模板 Refs
-## 模板 Refs
-
-> :white_check_mark: 支持 :x: 不支持
-
-:white_check_mark: 字符串 ref && 从 `setup()` 返回 ref:
+
+
+✅ 字符串 ref && 从 setup()
返回 ref
+
```html
@@ -190,45 +197,59 @@ b.list[1].count === 1; // true
```
-:white_check_mark: 字符串 ref && 从 `setup()` 返回 ref && 渲染函数 / JSX:
+
+
+
+
+
+
+✅ 字符串 ref && 从 setup()
返回 ref && 渲染函数 / JSX
+
```jsx
export default {
setup() {
- const root = ref(null);
+ const root = ref(null)
onMounted(() => {
// 在初次渲染后 DOM 元素会被赋值给 ref
- console.log(root.value); //
- });
+ console.log(root.value) //
+ })
return {
root,
- };
+ }
},
render() {
// 使用 JSX
- return () => ;
+ return () =>
},
-};
+}
```
-:x: 函数 ref:
+
+
+
+
+
+❌ 函数 ref
+
+
```html
@@ -238,69 +259,158 @@ export default {
```
-:x: 渲染函数 / JSX:
+
+
+
+
+
+❌ 在 setup()
中的渲染函数 / JSX
+
```jsx
export default {
setup() {
- const root = ref(null);
+ const root = ref(null)
return () =>
h('div', {
ref: root,
- });
+ })
// 使用 JSX
- return () => ;
+ return () =>
},
-};
+}
```
-如果你依然选择在 `setup()` 中写 `render` 函数,那么你可以使用 `SetupContext.refs` 来访问模板引用,它等价于 Vue 2.x 中的 `this.$refs`:
+
+
+
+
+⚠️ $refs
访问的变通方案
+
+
> :warning: **警告**: `SetupContext.refs` 并不属于 `Vue 3.0` 的一部分, `@vue/composition-api` 将其曝光在 `SetupContext` 中只是临时提供一种变通方案。
+如果你依然选择在 `setup()` 中写 `render` 函数,那么你可以使用 `SetupContext.refs` 来访问模板引用,它等价于 Vue 2.x 中的 `this.$refs`:
+
```js
export default {
setup(initProps, setupContext) {
- const refs = setupContext.refs;
+ const refs = setupContext.refs
onMounted(() => {
// 在初次渲染后 DOM 元素会被赋值给 ref
console.log(refs.root); //
- });
+ })
return () =>
h('div', {
ref: 'root',
- });
+ })
// 使用 JSX
- return () => ;
+ return () =>
},
-};
+}
```
如果项目使用了 TypeScript,你还需要扩展 `SetupContext` 类型:
```ts
-import Vue from 'vue';
-import VueCompositionAPI from '@vue/composition-api';
-
-Vue.use(VueCompositionAPI);
+import Vue from 'vue'
-declare module '@vue/composition-api/dist/component/component' {
+declare module '@vue/composition-api' {
interface SetupContext {
- readonly refs: { [key: string]: Vue | Element | Vue[] | Element[] };
+ readonly refs: { [key: string]: Vue | Element | Vue[] | Element[] }
}
}
```
+
+
+
+### Reactive
+
+
+
+⚠️ reactive()
会返回一个修改过的原始的对象
+
+
+此行为与 Vue 2 中的 `Vue.observable` 一致
+
+> :bulb: 在 Vue 3 中,`reactive()` 会返回一个新的的代理对象.
+
+
+
+
+### Watch
+
+
+
+❌ 不支持 onTrack
和 onTrigger
选项
+
+
+```js
+watch(() => {
+ /* ... */
+}, {
+ immediate: true,
+ onTrack() {}, // 不可用
+ onTrigger() {}, // 不可用
+})
+```
+
+
+
+
+### 缺失的 API
+
+以下在 Vue 3 新引入的 API ,在本插件中暂不适用:
+
+- `readonly`
+- `shallowReadonly`
+- `defineAsyncComponent`
+- `onRenderTracked`
+- `onRenderTriggered`
+- `customRef`
+- `isProxy`
+- `isReadonly`
+- `isVNode`
+
+
+### 在 `data()` 中使用组合式 API
+
+
+
+❌ 在 data()
中使用 ref
, reactive
或其他组合式 API 将不会生效
+
+
+```jsx
+export default {
+ data() {
+ return {
+ // 在模版中会成为 { a: { value: 1 } }
+ a: ref(1)
+ }
+ },
+}
+```
+
+
+
+
+### 性能影响
+
+用于 Vue 2 所提供的公共 API 的限制,`@vue/composition-api` 不可避免地引入了额外的性能开销。在非极端情况下,这并不会对你造成影响。
+
+你可以查看这个 [跑分结果](https://antfu.github.io/vue-composition-api-benchmark-results/) 了解更多信息。