目录
是在单文件组件 (SFC) 中使用组合式 API 的编译时语法糖。当同时使用 SFC 与组合式 API 时该语法是默认推荐。相比于普通的
语法,它具有更多优势:
要启用该语法,需要在 代码块上添加
setup
attribute:
- <script setup>
- console.log('hello script setup')
- script>
里面的代码会被编译成组件 setup()
函数的内容。这意味着与普通的 只在组件被首次引入的时候执行一次不同,
中的代码会在每次组件实例被创建的时候执行。
当使用 的时候,任何在
声明的顶层的绑定 (包括变量,函数声明,以及 import 导入的内容) 都能在模板中直接使用:
- <script setup>
- // 变量
- const msg = 'Hello!'
-
- // 函数
- function log() {
- console.log(msg)
- }
- script>
-
- <template>
- <button @click="log">{{ msg }}button>
- template>
import 导入的内容也会以同样的方式暴露。这意味着我们可以在模板表达式中直接使用导入的 helper 函数,而不需要通过 methods
选项来暴露它:
- <script setup>
- import { capitalize } from './helpers'
- script>
-
- <template>
- <div>{{ capitalize('hello') }}div>
- template>
响应式状态需要明确使用响应式 API 来创建。和 setup()
函数的返回值一样,ref 在模板中使用的时候会自动解包:
- <script setup>
- import { ref } from 'vue'
-
- const count = ref(0)
- script>
-
- <template>
- <button @click="count++">{{ count }}button>
- template>
范围里的值也能被直接作为自定义组件的标签名使用:
- <script setup>
- import MyComponent from './MyComponent.vue'
- script>
-
- <template>
- <MyComponent />
- template>
这里 MyComponent
应当被理解为像是在引用一个变量。如果你使用过 JSX,此处的心智模型是类似的。其 kebab-case 格式的
同样能在模板中使用——不过,我们强烈建议使用 PascalCase 格式以保持一致性。同时这也有助于区分原生的自定义元素。
由于组件是通过变量引用而不是基于字符串组件名注册的,在 中要使用动态组件的时候,应该使用动态的
:is
来绑定:
- <script setup>
- import Foo from './Foo.vue'
- import Bar from './Bar.vue'
- script>
-
- <template>
- <component :is="Foo" />
- <component :is="someCondition ? Foo : Bar" />
- template>
请注意组件是如何在三元表达式中被当做变量使用的。
一个单文件组件可以通过它的文件名被其自己所引用。例如:名为 FooBar.vue
的组件可以在其模板中用
引用它自己。
请注意这种方式相比于导入的组件优先级更低。如果有具名的导入和组件自身推导的名字冲突了,可以为导入的组件添加别名:
import { FooBar as FooBarChild } from './components'
可以使用带 .
的组件标签,例如
来引用嵌套在对象属性中的组件。这在需要从单个文件中导入多个组件的时候非常有用:
- <script setup>
- import * as Form from './form-components'
- script>
-
- <template>
- <Form.Input>
- <Form.Label>labelForm.Label>
- Form.Input>
- template>
全局注册的自定义指令将正常工作。本地的自定义指令在 中不需要显式注册,但他们必须遵循
vNameOfDirective
这样的命名规范:
- <script setup>
- const vMyDirective = {
- beforeMount: (el) => {
- // 在元素上做些操作
- }
- }
- script>
- <template>
- <h1 v-my-directive>This is a Headingh1>
- template>
如果指令是从别处导入的,可以通过重命名来使其符合命名规范:
- <script setup>
- import { myDirective as vMyDirective } from './MyDirective.js'
- script>
为了在声明 props
和 emits
选项时获得完整的类型推导支持,我们可以使用 defineProps
和 defineEmits
API,它们将自动地在 中可用:
- <script setup>
- const props = defineProps({
- foo: String
- })
-
- const emit = defineEmits(['change', 'delete'])
- // setup 代码
- script>
defineProps
和 defineEmits
都是只能在 中使用的编译器宏。他们不需要导入,且会随着
的处理过程一同被编译掉。
defineProps
接收与 props
选项相同的值,defineEmits
接收与 emits
选项相同的值。
defineProps
和 defineEmits
在选项传入后,会提供恰当的类型推导。
传入到 defineProps
和 defineEmits
的选项会从 setup 中提升到模块的作用域。因此,传入的选项不能引用在 setup 作用域中声明的局部变量。这样做会引起编译错误。但是,它可以引用导入的绑定,因为它们也在模块作用域内。
props 和 emit 也可以通过给 defineProps
和 defineEmits
传递纯类型参数的方式来声明:
- const props = defineProps<{
- foo: string
- bar?: number
- }>()
-
- const emit = defineEmits<{
- (e: 'change', id: number): void
- (e: 'update', value: string): void
- }>()
-
- // 3.3+:另一种更简洁的语法
- const emit = defineEmits<{
- change: [id: number] // 具名元组语法
- update: [value: string]
- }>()
defineProps
或 defineEmits
要么使用运行时声明,要么使用类型声明。同时使用两种声明方式会导致编译报错。
使用类型声明的时候,静态分析会自动生成等效的运行时声明,从而在避免双重声明的前提下确保正确的运行时行为。
在开发模式下,编译器会试着从类型来推导对应的运行时验证。例如这里从 foo: string
类型中推断出 foo: String
。如果类型是对导入类型的引用,这里的推导结果会是 foo: null
(与 any
类型相等),因为编译器没有外部文件的信息。
在生产模式下,编译器会生成数组格式的声明来减少打包体积 (这里的 props 会被编译成 ['foo', 'bar']
)。
在 3.2 及以下版本中,defineProps()
的泛型类型参数只能使用类型字面量或者本地接口的引用。
这个限制已经在 3.3 版本中解决。最新版本的 Vue 支持在类型参数的位置引用导入的和有限的复杂类型。然而,由于类型到运行时的转换仍然基于 AST,因此并不支持使用需要实际类型分析的复杂类型,例如条件类型等。你可以在单个 prop 的类型上使用条件类型,但不能对整个 props 对象使用。
针对类型的 defineProps
声明的不足之处在于,它没有可以给 props 提供默认值的方式。为了解决这个问题,我们还提供了 withDefaults
编译器宏:
- export interface Props {
- msg?: string
- labels?: string[]
- }
-
- const props = withDefaults(defineProps<Props>(), {
- msg: 'hello',
- labels: () => ['one', 'two']
- })
上面代码会被编译为等价的运行时 props 的 default
选项。此外,withDefaults
辅助函数提供了对默认值的类型检查,并确保返回的 props
的类型删除了已声明默认值的属性的可选标志。
await
中可以使用顶层
await
。结果代码会被编译成 async setup()
:
- <script setup>
- const post = await fetch(`/api/post/1`).then((r) => r.json())
- script>
另外,await 的表达式会自动编译成在 await
之后保留当前组件实例上下文的格式。
注意
async setup()
必须与 Suspense 内置组件组合使用,Suspense
目前还是处于实验阶段的特性,会在将来的版本中稳定。
中的代码依赖单文件组件的上下文。当将其移动到外部的 .js
或者 .ts
文件中的时候,对于开发者和工具来说都会感到混乱。因此,
不能和 src
attribute 一起使用。
不支持 DOM 内根组件模板。(相关讨论)