<script lang="py">

<script lang='py'> 是在单文件组件 (SFC) 中使用组合式 API 的编译时语法糖。当同时使用 SFC 与组合式 API 时该语法是默认推荐。它具有更多优势：

更少的样板内容，更简洁的代码。
能够使用纯 Python 声明 props 和自定义事件。
更好的运行时性能 (其模板会被编译成同一作用域内的渲染函数，避免了渲染上下文代理对象)。
更好的 IDE 类型推导性能 (减少了语言服务器从代码中抽取类型的工作)。

基本语法

要启用该语法，需要在 <script> 代码块上添加 lang='py' attribute：

vue

<script lang='py'>
print('hello script setup')
</script>

里面的代码会被编译成组件 setup() 函数的内容。<script lang='py'> 中的代码会在每次组件实例被创建的时候执行。

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

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

vue

<template>
  <Button @click="log()" :label='msg'></Button>
</template>

<script lang='py'>
# 变量
msg = 'Hello!'

# 函数
def log():
  print(msg)
  
</script>

import 导入的内容也会以同样的方式暴露。这意味着我们可以在模板表达式中直接使用导入的 helper 函数。

vue

<template>
  <div>{{ capitalize('hello') }}</div>
</template>

<script lang='py'>
from helpers import capitalize 
</script>

响应式

响应式状态需要明确使用响应式 API 来创建。

vue

<template>
  <button @click="inc()">{{ count.value }}</button>
</template>

<script lang='py'>
from vuepy import ref


count = ref(0)

def inc():
  count.value += 1

</script>

使用组件

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

vue

<template>
  <MyComponent></MyComponent>
</template>

<script lang='py'>
from vuepy import import_sfc

MyComponent = import_sfc('./MyComponent.vue')
</script>

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

动态组件

WARNING

请注意，这是一个预留的语法，当前版本未实现。

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

vue

<script setup>
import Foo from './Foo.vue'
import Bar from './Bar.vue'
</script>

<template>
  <component :is="Foo" />
  <component :is="someCondition ? Foo : Bar" />
</template>

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

递归组件

WARNING

请注意，这是一个预留的语法，当前版本未实现。

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

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

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

命名空间组件

WARNING

请注意，这是一个预留的语法，当前版本未实现。

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

vue

<script setup>
import * as Form from './form-components'
</script>

<template>
  <Form.Input>
    <Form.Label>label</Form.Label>
  </Form.Input>
</template>

使用自定义指令

WARNING

请注意，这是一个预留的语法，当前版本未实现。

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

vue

<script setup>
const vMyDirective = {
  beforeMount: (el) => {
    // 在元素上做些操作
  }
}
</script>
<template>
  <h1 v-my-directive>This is a Heading</h1>
</template>

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

vue

<script setup>
import { myDirective as vMyDirective } from './MyDirective.js'
</script>

defineProps() 和 defineEmits()

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

vue

<script lang='py'>
props = defineProps(['foo'])

emit = defineEmits(['change', 'delete'])
# // setup 代码
</script>

defineProps 和 defineEmits 都是只能在 <script lang='py'> 中使用的编译器宏。会随着 <script lang='py'> 的处理过程一同被编译掉。
defineProps 接收与 props 选项相同的值，defineEmits 接收与 emits 选项相同的值。
defineProps 和 defineEmits 在选项传入后，会提供恰当的类型推导。
传入到 defineProps 和 defineEmits 的选项会从 setup 中提升到模块的作用域。因此，传入的选项不能引用在 setup 作用域中声明的局部变量。这样做会引起编译错误。但是，它可以引用导入的绑定，因为它们也在模块作用域内。

WARNING

请注意，这是一个预留的语法，当前版本未实现。

针对类型的 props/emit 声明

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 对象使用。

使用类型声明时的默认 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 的类型删除了已声明默认值的属性的可选标志。

defineModel()

这个宏可以用来声明一个双向绑定 prop，通过父组件的 v-model 来使用。组件 v-model 指南中也讨论了示例用法。

在底层，这个宏声明了一个 model prop 和一个相应的值更新事件。如果第一个参数是一个字符串字面量，它将被用作 prop 名称；否则，prop 名称将默认为 "value"。在这两种情况下，你都可以再传递一个额外的对象，它可以包含 prop 的选项和 model ref 的值转换选项。

# 声明 "modelValue" prop，由父组件通过 v-model 使用
model = defineModel()
# （暂不支持）或者：声明带选项的 "modelValue" prop
model = defineModel({ type: String })

# 在被修改时，触发 "update:modelValue" 事件
model.value = "hello"

# 声明 "count" prop，由父组件通过 v-model:count 使用
count = defineModel("count")
# （暂不支持）或者：声明带选项的 "count" prop
count = defineModel("count", { type: Number, default: 0 })

def inc():
  # 在被修改时，触发 "update:count" 事件
  count.value += 1

WARNING

如果为 defineModel prop 设置了一个 default 值且父组件没有为该 prop 提供任何值，会导致父组件与子组件之间不同步。在下面的示例中，父组件的 myRef 是 undefined，而子组件的 model 是 1：

# 子组件：
# model = defineModel({ default: 1 })
model = defineModel()
model.value = 1

# 父组件
myRef = ref()

html

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

修饰符和转换器

WARNING

请注意，这是一个预留的语法，当前版本未实现。

为了获取 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
  }
})

defineExpose()

WARNING

请注意，这是一个预留的语法，当前版本未实现。

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

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

vue

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

const a = 1
const b = ref(2)

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

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

defineOptions()

WARNING

请注意，这是一个预留的语法，当前版本未实现。

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

vue

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

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

`useSlots()` 和 `useAttrs()`

WARNING

请注意，这是一个预留的语法，当前版本未实现。

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

vue

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

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

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

限制

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

在 GitHub 上编辑此页

<script lang="py"> ​

基本语法 ​

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

响应式 ​

使用组件 ​

动态组件 ​

递归组件 ​

命名空间组件 ​

使用自定义指令 ​

defineProps() 和 defineEmits() ​

针对类型的 props/emit 声明 ​

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

defineModel() ​

修饰符和转换器 ​

defineExpose() ​

defineOptions() ​

useSlots() 和 useAttrs() ​

限制 ​

<script lang="py">

基本语法

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

响应式

使用组件

动态组件

递归组件

命名空间组件

使用自定义指令

defineProps() 和 defineEmits()

针对类型的 props/emit 声明

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

defineModel()

修饰符和转换器

defineExpose()

defineOptions()

`useSlots()` 和 `useAttrs()`

限制