\
```vue [Parent.vue] <script setup> const myRef = ref() </script> <template> <Child v-model="myRef"></Child> </template>

:::

\


```vue [Parent.vue]
<script setup>
const myRef = ref()
</script>

<template>
  <Child v-model="myRef"></Child>
</template>

:::

修饰符和转换器 {#modifiers-and-transformers}

为了获取 v-model 指令使用的修饰符，我们可以像这样解构 defineModel() 的返回值：

const [modelValue, modelModifiers] = defineModel()

// 对应 v-model.trim
if (modelModifiers.trim) {
  // ...
}

当存在修饰符时，我们可能需要在读取或将其同步回父组件时对其值进行转换。我们可以通过使用 get 和 set 转换器选项来实现这一点：

const [modelValue, modelModifiers] = defineModel({
  // get() 省略了，因为这里不需要它
  set(value) {
    // 如果使用了 .trim 修饰符，则返回裁剪过后的值
    if (modelModifiers.trim) {
      return value.trim()
    }
    // 否则，原样返回
    return value
  }
})

在 TypeScript 中使用 ^{{#usage-with-typescript}}

与 defineProps 和 defineEmits 一样，defineModel 也可以接收类型参数来指定 model 值和修饰符的类型：

const modelValue = defineModel<string>()
//    ^? Ref<string | undefined>

// 用带有选项的默认 model，设置 required 去掉了可能的 undefined 值
const modelValue = defineModel<string>({ required: true })
//    ^? Ref<string>

const [modelValue, modifiers] = defineModel<string, "trim" | "uppercase">()
//                 ^? Record<'trim' | 'uppercase', true | undefined>

defineExpose() {#defineexpose}

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

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

<script setup>
import { ref } from 'vue'

const a = 1
const b = ref(2)

defineExpose({
  a,
  b
})
</script>

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

defineOptions() {#defineoptions}

仅在 3.3+ 中支持

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

<script setup>
defineOptions({
  inheritAttrs: false,
  customOptions: {
    /* ... */
  }
})
</script>

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

defineSlots() ^{{#defineslots}}

仅在 3.3+ 中支持

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

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

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

<script setup lang="ts">
const slots = defineSlots<{
  default(props: { msg: string }): any
}>()
</script>

`useSlots()` 和 `useAttrs()` {#useslots-useattrs}

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

<script setup>
import { useSlots, useAttrs } from 'vue'

const slots = useSlots()
const attrs = useAttrs()
</script>

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

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

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

声明无法在 <script setup> 中声明的选项，例如 inheritAttrs 或插件的自定义选项 (在 3.3+ 中可以通过 defineOptions 替代)。
声明模块的具名导出 (named exports)。
运行只需要在模块作用域执行一次的副作用，或是创建单例对象。

<script>
// 普通 <script>，在模块作用域下执行 (仅一次)
runSideEffectOnce()

// 声明额外的选项
export default {
  inheritAttrs: false,
  customOptions: {}
}
</script>

<script setup>
// 在 setup() 作用域中执行 (对每个实例皆如此)
</script>

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

不要为已经可以用 <script setup> 定义的选项使用单独的 <script> 部分，如 props 和 emits。
在 <script setup> 中创建的变量不会作为属性添加到组件实例中，这使得它们无法从选项式 API 中访问。我们强烈反对以这种方式混合 API。

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

顶层 `await` {#top-level-await}

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

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

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

:::warning 注意 async setup() 必须与 Suspense 组合使用，该特性目前仍处于实验阶段。我们计划在未来的版本中完成该特性并编写文档——但如果你现在就感兴趣，可以参考其测试来了解其工作方式。 :::

导入语句 {#imports-statements}

Vue 中的导入语句遵循 ECMAScript 模块规范。此外，你还可以使用构建工具配置中定义的别名：

<script setup>
import { ref } from 'vue'
import { componentA } from './Components'
import { componentB } from '@/Components'
import { componentC } from '~/Components'
</script>

泛型 ^{#generics}

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

<script setup lang="ts" generic="T">
defineProps<{
  items: T[]
  selected: T
}>()
</script>

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

<script
  setup
  lang="ts"
  generic="T extends string | number, U extends Item"
>
import type { Item } from './types'
defineProps<{
  id: T
  list: U[]
}>()
</script>

当无法自动推断泛型组件的具体类型时，可使用指令 @vue-generic 来显式指定：

<template>
  <!-- @vue-generic {import('@/api').Actor} -->
  <ApiSelect v-model="peopleIds" endpoint="/api/actors" id-prop="actorId" />

  <!-- @vue-generic {import('@/api').Genre} -->
  <ApiSelect v-model="genreIds" endpoint="/api/genres" id-prop="genreId" />
</template>

为了在 ref 中使用泛型组件的引用，你需要使用 vue-component-type-helpers 库，因为 InstanceType 在这种场景下不起作用。

<script
  setup
  lang="ts"
>
import componentWithoutGenerics from '../component-without-generics.vue';
import genericComponent from '../generic-component.vue';

import type { ComponentExposed } from 'vue-component-type-helpers';

// 适用于没有泛型的组件
ref<InstanceType<typeof componentWithoutGenerics>>();

ref<ComponentExposed<typeof genericComponent>>();

限制 {#restrictions}

由于模块执行语义的差异，<script setup> 中的代码依赖单文件组件的上下文。当将其移动到外部的 .js 或者 .ts 文件中的时候，对于开发者和工具来说都会感到混乱。因此，<script setup> 不能和 src attribute 一起使用。
<script setup> 不支持 DOM 内根组件模板。(相关讨论)

修饰符和转换器 {#modifiers-and-transformers}

在 TypeScript 中使用 {#usage-with-typescript}

defineExpose() {#defineexpose}

defineOptions() {#defineoptions}

defineSlots() {#defineslots}

useSlots() 和 useAttrs() {#useslots-useattrs}

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

顶层 await {#top-level-await}