{#script-setup}"">

是在单文件组件 (SFC) 中使用组合式 API 的编译时语法糖。当同时使用 SFC 与组合式 API 时该语法是默认推荐。相比于普通的  语法，它具有更多优势：

• 更少的样板内容，更简洁的代码。

• 能够使用纯 TypeScript 声明 props 和自定义事件。

• 更好的运行时性能 (其模板会被编译成同一作用域内的渲染函数，避免了渲染上下文代理对象)。

• 更好的 IDE 类型推导性能 (减少了语言服务器从代码中抽取类型的工作)。

基本语法

要启用该语法，需要在  代码块上添加 setup attribute：

console.log('hello script setup')

里面的代码会被编译成组件 setup() 函数的内容。这意味着与普通的  只在组件被首次引入的时候执行一次不同， 中的代码会在每次组件实例被创建的时候执行。

顶层的绑定会被暴露给模板

当使用  的时候，任何在  声明的顶层的绑定 (包括变量，函数声明，以及 import 导入的内容) 都能在模板中直接使用：

// 变量const msg = 'Hello!'// 函数function log() {  console.log(msg)}  {{ msg }}

import 导入的内容也会以同样的方式暴露。这意味着我们可以在模板表达式中直接使用导入的 helper 函数，而不需要通过 methods 选项来暴露它：

import { capitalize } from './helpers'  {{ capitalize('hello') }}

响应式

响应式状态需要明确使用响应式 API 来创建。和 setup() 函数的返回值一样，ref 在模板中使用的时候会自动解包：

import { ref } from 'vue'const count = ref(0)  {{ count }}

使用组件

范围里的值也能被直接作为自定义组件的标签名使用：

import MyComponent from './MyComponent.vue'

这里 MyComponent 应当被理解为像是在引用一个变量。如果你使用过 JSX，此处的心智模型是类似的。其 kebab-case 格式的  同样能在模板中使用——不过，我们强烈建议使用 PascalCase 格式以保持一致性。同时这也有助于区分原生的自定义元素。

动态组件

由于组件是通过变量引用而不是基于字符串组件名注册的，在  中要使用动态组件的时候，应该使用动态的 :is 来绑定：

import Foo from './Foo.vue'import Bar from './Bar.vue'

请注意组件是如何在三元表达式中被当做变量使用的。

递归组件

一个单文件组件可以通过它的文件名被其自己所引用。例如：名为 FooBar.vue 的组件可以在其模板中用  引用它自己。

请注意这种方式相比于导入的组件优先级更低。如果有具名的导入和组件自身推导的名字冲突了，可以为导入的组件添加别名：

import { FooBar as FooBarChild } from './components'

命名空间组件

可以使用带 . 的组件标签，例如  来引用嵌套在对象属性中的组件。这在需要从单个文件中导入多个组件的时候非常有用：

import * as Form from './form-components'      label

使用自定义指令

全局注册的自定义指令将正常工作。本地的自定义指令在  中不需要显式注册，但他们必须遵循 vNameOfDirective 这样的命名规范：

const vMyDirective = {  beforeMount: (el) => {    // 在元素上做些操作  }}  This is a Heading

如果指令是从别处导入的，可以通过重命名来使其符合命名规范：

import { myDirective as vMyDirective } from './MyDirective.js'

defineProps() 和 defineEmits()

为了在声明 props 和 emits 选项时获得完整的类型推导支持，我们可以使用 defineProps 和 defineEmits API，它们将自动地在  中可用：

const props = defineProps({  foo: String})const emit = defineEmits(['change', 'delete'])// setup 代码

• defineProps 和 defineEmits 都是只能在  中使用的编译器宏。他们不需要导入，且会随着  的处理过程一同被编译掉。

• defineProps 接收与 props 选项相同的值，defineEmits 接收与 emits 选项相同的值。

• defineProps 和 defineEmits 在选项传入后，会提供恰当的类型推导。

• 传入到 defineProps 和 defineEmits 的选项会从 setup 中提升到模块的作用域。因此，传入的选项不能引用在 setup 作用域中声明的局部变量。这样做会引起编译错误。但是，它可以引用导入的绑定，因为它们也在模块作用域内。

针对类型的 props/emit 声明  {#type-only-props-emit-declarations}"">

props 和 emit 也可以通过给 defineProps 和 defineEmits 传递纯类型参数的方式来声明：

const props = defineProps()const emit = defineEmits()// 3.3+：另一种更简洁的语法const emit = defineEmits()

• defineProps 或 defineEmits 要么使用运行时声明，要么使用类型声明。同时使用两种声明方式会导致编译报错。

• 使用类型声明的时候，静态分析会自动生成等效的运行时声明，从而在避免双重声明的前提下确保正确的运行时行为。

• 在开发模式下，编译器会试着从类型来推导对应的运行时验证。例如这里从 foo: string 类型中推断出 foo: String。如果类型是对导入类型的引用，这里的推导结果会是 foo: null (与 any 类型相等)，因为编译器没有外部文件的信息。

• 在生产模式下，编译器会生成数组格式的声明来减少打包体积 (这里的 props 会被编译成 ['foo', 'bar'])。

• 在 3.2 及以下版本中，defineProps() 的泛型类型参数只能使用类型字面量或者本地接口的引用。

  这个限制已经在 3.3 版本中解决。最新版本的 Vue 支持在类型参数的位置引用导入的和有限的复杂类型。然而，由于类型到运行时的转换仍然基于 AST，因此并不支持使用需要实际类型分析的复杂类型，例如条件类型等。你可以在单个 prop 的类型上使用条件类型，但不能对整个 props 对象使用。

使用类型声明时的默认 props 值

针对类型的 defineProps 声明的不足之处在于，它没有可以给 props 提供默认值的方式。为了解决这个问题，我们还提供了 withDefaults 编译器宏：

export interface Props {  msg?: string  labels?: string[]}const props = withDefaults(defineProps(), {  msg: 'hello',  labels: () => ['one', 'two']})

上面代码会被编译为等价的运行时 props 的 default 选项。此外，withDefaults 辅助函数提供了对默认值的类型检查，并确保返回的 props 的类型删除了已声明默认值的属性的可选标志。

defineExpose()

使用  的组件是默认关闭的——即通过模板引用或者 $parent 链获取到的组件的公开实例，不会暴露任何在  中声明的绑定。

可以通过 defineExpose 编译器宏来显式指定在  组件中要暴露出去的属性：

import { ref } from 'vue'const a = 1const b = ref(2)defineExpose({  a,  b})

当父组件通过模板引用的方式获取到当前组件的实例，获取到的实例会像这样 { a: number, b: number } (ref 会和在普通实例中一样被自动解包)

defineOptions()

这个宏可以用来直接在  中声明组件选项，而不必使用单独的  块：

defineOptions({  inheritAttrs: false,  customOptions: {    /* ... */  }})

• 仅支持 Vue 3.3+。

• 这是一个宏定义，选项将会被提升到模块作用域中，无法访问  中不是字面常数的局部变量。

defineSlots()  {#defineslots}"">

这个宏可以用于为 IDE 提供插槽名称和 props 类型检查的类型提示。

defineSlots() 只接受类型参数，没有运行时参数。类型参数应该是一个类型字面量，其中属性键是插槽名称，值类型是插槽函数。函数的第一个参数是插槽期望接收的 props，其类型将用于模板中的插槽 props。返回类型目前被忽略，可以是 any，但我们将来可能会利用它来检查插槽内容。

它还返回 slots 对象，该对象等同于在 setup 上下文中暴露或由 useSlots() 返回的 slots 对象。

const slots = defineSlots()

• 仅支持 Vue 3.3+。

useSlots() 和 useAttrs()

在  使用 slots 和 attrs 的情况应该是相对来说较为罕见的，因为可以在模板中直接通过 $slots 和 $attrs 来访问它们。在你的确需要使用它们的罕见场景中，可以分别用 useSlots 和 useAttrs 两个辅助函数：

import { useSlots, useAttrs } from 'vue'const slots = useSlots()const attrs = useAttrs()

useSlots 和 useAttrs 是真实的运行时函数，它的返回与 setupContext.slots 和 setupContext.attrs 等价。它们同样也能在普通的组合式 API 中使用。

与普通的  一起使用 ` 一起使用 {#usage-alongside-normal-script}"">

可以和普通的  一起使用。普通的  在有这些需要的情况下或许会被使用到：

• 声明无法在  中声明的选项，例如 inheritAttrs 或插件的自定义选项 (在 3.3+ 中可以通过 defineOptions 替代)。

• 声明模块的具名导出 (named exports)。

• 运行只需要在模块作用域执行一次的副作用，或是创建单例对象。

// 普通 , 在模块作用域下执行 (仅一次)runSideEffectOnce()// 声明额外的选项export default {  inheritAttrs: false,  customOptions: {}}// 在 setup() 作用域中执行 (对每个实例皆如此)

在同一组件中将  与  结合使用的支持仅限于上述情况。具体来说：

• 不要为已经可以用  定义的选项使用单独的  部分，如 props 和 emits。

• 在  中创建的变量不会作为属性添加到组件实例中，这使得它们无法从选项式 API 中访问。我们强烈反对以这种方式混合 API。

如果你发现自己处于以上任一不被支持的场景中，那么你应该考虑切换到一个显式的 setup() 函数，而不是使用 。

顶层 await

中可以使用顶层 await。结果代码会被编译成 async setup()：

const post = await fetch(`/api/post/1`).then((r) => r.json())

另外，await 的表达式会自动编译成在 await 之后保留当前组件实例上下文的格式。

泛型   {#generics}"">

可以使用  标签上的 generic 属性声明泛型类型参数：

defineProps()

generic 的值与 TypeScript 中位于  之间的参数列表完全相同。例如，您可以使用多个参数，extends 约束，默认类型和引用导入的类型：

import type { Item } from './types'defineProps()

限制

• 由于模块执行语义的差异， 中的代码依赖单文件组件的上下文。当将其移动到外部的 .js 或者 .ts 文件中的时候，对于开发者和工具来说都会感到混乱。因此， 不能和 src attribute 一起使用。

• 

  不支持 DOM 内根组件模板。(相关讨论)

图片声明：本站部分配图来自网络。本站只作为美观性配图使用,无任何非法侵犯第三方意图,一切解释权归图片著作权方,本站不承担任何责任。如有恶意碰瓷者,必当奉陪到底严惩不贷!