本文主要是讲解 <script setup>
与 TypeScript
的基本使用。
<script setup>
是什么?
<script setup>
是在单文件组件 (SFC) 中使用 composition api
的编译时语法糖。
本文写作时,vue
使用的 3.2.26 版本。
1.1. 发展历程
我们先看看 vue3 <script setup>
的发展历程:
Vue3
在早期版本( 3.0.0-beta.21
之前)中对 composition api
的支持,只能在组件选项 setup
函数中使用。
<template><h1>{{ msg }}</h1><button type="button" @click="add">count is: {{ count }}</button><ComponentA /><ComponentB /></template><script>import { defineComponent, ref } from 'vue'import ComponentA from '@/components/ComponentA'import ComponentB from '@/components/ComponentB'export default defineComponent({name: 'HelloWorld',components: { ComponentA, ComponentB },props: {msg: String,},setup(props, ctx) {const count = ref(0)function add() {count.value++}// 使用return {} 把变量、方法暴露给模板return {count,add,}},})</script>
在 3.0.0-beta.21 版本中增加了 <script setup>
的实验特性。如果你使用了,会提示你 <script setup>
还处在实验特性阶段。
在 3.2.0 版本中移除 <script setup>
的实验状态,从此,宣告 <script setup>
正式转正使用,成为框架稳定的特性之一。
<script setup lang="ts">import { ref } from 'vue'import ComponentA from '@/components/ComponentA'import ComponentB from '@/components/ComponentB'defineProps<{ msg: string }>()const count = ref(0)function add() {count.value++}</script>x<template><h1>{{ msg }}</h1><button type="button" @click="add">count is: {{ count }}</button><ComponentA /><ComponentB /></template>
1.2. 优势
与组件选项 setup
函数对比, <script setup>
的优点:
更少、更简洁的代码,不需要使用 return {}
暴露变量和方法了,使用组件时不需要主动注册了;更好的 Typescript
支持,使用纯 Typescript
声明 props
和抛出事件,不会再像 option api
里那么蹩脚了;更好的运行时性能;
当然, <script setup>
也是有自己的缺点的,比如需要学习额外的 API
。
那么 <script setup>
怎么使用呢?有哪些使用要点?与TypeScript如何结合?
2. 使用要点 2.1. 工具
Vue3
单文件组件 (SFC) 的 TS IDE
支持请用 <script setup lang="ts"> + VSCode + Volar
。
类型检查使用 vue-tsc
命令。
VSCode:前端最好用的 IDE
。Volar:为 Vue3
的 *.vue
单文件组件提供代码高亮、语法提示等功能支持的 VSCode
插件;Vue2
你可能是使用的 Vetur
插件,需要禁用 Vetur
,下载 Volar
,并启用它。vue-tsc:类型检查和 dts
构建命令行工具。2.2. 基本用法
将 setup
属性添加到 <script>
代码块上。
<script setup>import { ref } from 'vue'defineProps({msg: String})const count = ref(0)function add() {count.value++}</script><template><h1>{{ msg }}</h1><button type="button" @click="add">count is: {{ count }}</button></template>
若需要使用 TypeScript
,则将 lang
属性添加到 <script>
代码块上,并赋值 ts
。
<script setup lang="ts">import { ref } from 'vue'defineProps<{ msg: string }>()const count = ref(0)function add() {count.value++}</script><template><h1>{{ msg }}</h1><button type="button" @click="add">count is: {{ count }}</button></template>
<script setup>
块中的脚本会被编译成组件选项 setup
函数的内容,也就是说它会在每次组件实例被创建的时候执行。
在 <script setup>
声明的顶层绑定(变量、函数、import引入的内容),都会自动暴露给模板,在模板中直接使用。
<script setup>import { ref } from 'vue'// 外部引入的方法,不需要通过 methods 选项来暴露它,模板可以直接使用import { getToken } from './utils'// 外部引入的组件,不需要通过 components 选项来暴露它,模板可以直接使用import ComponentA from '@/components/ComponentA'defineProps({msg: String})// 变量声明,模板可以直接使用const count = ref(0)// 函数声明,模板可以直接使用function add() {count.value++}</script><template><h1>{{ msg }}</h1><h1>{{ getToken() }}</h1><button type="button" @click="add">count is: {{ count }}</button><ComponentA /></template>
注意:
每个 *.vue
文件最多可同时包含一个 <script>
块 (不包括<script setup>
);
每个 *.vue
文件最多可同时包含一个 <script setup>
块 (不包括常规的 <script>
);
2.3. 编译器宏
编译器宏(compiler macros) 有:defineProps
、defineEmits
、withDefaults
、defineExpose
等。
编译器宏只能在 <script setup>
块中使用,不需要被导入,并且会在处理 <script setup>
块时被一同编译掉。
编译器宏必须在 <script setup>
的顶层使用,不可以在 <script setup>
的局部变量中引用。
defineProps
在 <script setup>
块中是没有组件配置项的,也就是说是没有 props
选项,需要使用 defineProps
来声明 props
相关信息。defineProps
接收的对象和组件选项 props
的值一样。
<script setup>const props = defineProps({msg: String,title: {type: String,default: '我是'},list: {type: Array,default: () => []}})// 在 js 中使用 props 中的属性console.log(props.msg)</script><template><!-- 在模板中直接使用 props 中声明的变量 --><h1>{{ msg }}</h1><div>{{ title }}</div></template>
TS 版本:
<script setup lang="ts">interface ListItem {name: stringage: number}const props = defineProps<{msg: stringtitle: stringlist: ListItem[]}>()// 在 ts 中使用 props 中的属性,具有很好的类型推断能力console.log(props.list[0].age)</script><template><h1>{{ msg }}</h1><div>{{ title }}</div></template>
从代码中可以发现 TS
写法里 props
没有定义默认值。
Vue3
为我们提供了 withDefaults
这个编译器宏,给 props
提供默认值。
<script setup lang="ts">interface ListItem {name: stringage: number}interface Props {msg: string// title可选title?: stringlist: ListItem[]}// withDefaults 的第二个参数便是默认参数设置,会被编译为运行时 props 的 default 选项const props = withDefaults(defineProps<Props>(), {title: '我是',// 对于array、object需要使用函数,和以前的写法一样list: () => []})// 在 ts 中使用 props 中的属性,具有很好的类型推断能力console.log(props.list[0].age)</script><template><h1>{{ msg }}</h1><div>{{ title }}</div></template>
一个需要注意的地方:在顶层声明一个和props
的属性同名的变量,会有些问题。
<script setup>const props = defineProps({title: {type: String,default: '我是'}})// 在顶层声明一个和props的属性title同名的变量const title = '123'</script><template><!-- props.title 显示的是 props.title 的值,‘我是’ --><div>{{ props.title }}</div><!-- title 显示的是 在顶层声明的 title 的值,‘123’ --><div>{{ title }}</div></template>
所以,和组件选项一样,不要定义和 props
的属性同名的顶层变量。
defineEmits
一样的,在 <script setup>
块中也是没有组件配置项 emits
的,需要使用 defineEmits
编译器宏声明 emits
相关信息。
// ./components/HelloWorld.vue<script setup>defineProps({msg: String,})const emits = defineEmits(['changeMsg'])const handleChangeMsg = () => {emits('changeMsg', 'Hello TS')}</script><template><h1>{{ msg }}</h1><button @click="handleChangeMsg">handleChangeMsg</button></template>
使用组件:
<script setup>import { ref } from 'vue'import HelloWorld from './components/HelloWorld.vue'const msg = ref('Hello Vue3')const changeMsg = (v) => {msg.value = v}</script><template><HelloWorld :msg="msg" @changeMsg="changeMsg" /></template>
TS 版本:
// ./components/HelloWorld.vue<script setup lang="ts">defineProps<{msg: string}>()const emits = defineEmits<{(e: 'changeMsg', value: string): void}>()const handleChangeMsg = () => {emits('changeMsg', 'Hello TS')}</script><template><h1>{{ msg }}</h1><button @click="handleChangeMsg">handleChangeMsg</button></template>
使用组件:
<script setup lang="ts">import { ref } from 'vue'import HelloWorld from './components/HelloWorld.vue'const msg = ref('Hello Vue3')const changeMsg = (v: string) => {msg.value = v}</script><template><HelloWorld :msg="msg" @changeMsg="changeMsg" /></template>
defineExpose
在 Vue3
中,默认不会暴露任何在 <script setup>
中声明的绑定,即不能通过模板 ref
获取到组件实例声明的绑定。
Vue3
提供了 defineExpose
编译器宏,可以显式地暴露需要暴露的组件中声明的变量和方法。
// ./components/HelloWorld.vue<script setup>import { ref } from 'vue'const msg = ref('Hello Vue3')const handleChangeMsg = (v) => {msg.value = v}// 对外暴露的属性defineExpose({msg,handleChangeMsg,})</script>
使用组件:
<script setup>import { ref, onMounted } from 'vue'import HelloWorld from './components/HelloWorld.vue'const root = ref(null)onMounted(() => {console.log(root.value.msg)})const handleChangeMsg = () => {root.value.handleChangeMsg('Hello TS')}</script><template><HelloWorld ref="root" /><button @click="handleChangeMsg">handleChangeMsg</button></template>
TS 版本:
// ./components/HelloWorld.vue<script setup lang="ts">import { ref } from 'vue'const msg = ref('Hello Vue3')const handleChangeMsg = (v: string) => {msg.value = v}defineExpose({msg,handleChangeMsg})</script><template><h1>{{ msg }}</h1></template>
使用组件:
<script setup lang="ts">import { ref, onMounted } from 'vue'import HelloWorld from './components/HelloWorld.vue'// 此处暂时使用any,需要定义类型const root = ref<any>(null)onMounted(() => {console.log(root.value.msg)})const handleChangeMsg = () => {root.value.handleChangeMsg('Hello TS')}</script><template><HelloWorld ref="root" /><button @click="handleChangeMsg">handleChangeMsg</button></template>
2.4. 辅助函数
在 <script setup>
中常用的辅助函数hooks api
,主要有:useAttrs
、useSlots
、useCssModule
,其他的辅助函数还在实验阶段,不做介绍。
useAttrs
在模板中使用 $attrs
来访问 attrs
数据,与 Vue2
相比,Vue3
的 $attrs
还包含了 class
和 style
属性。
在 <script setup>
中使用 useAttrs
函数获取 attrs
数据。
<script setup>import HelloWorld from './components/HelloWorld.vue'</script><template><HelloWorld class="hello-word" title="我是" /></template>
// ./components/HelloWorld.vue<script setup>import { useAttrs } from 'vue'const attrs = useAttrs()// js中使用console.log(attrs.class) // hello-wordconsole.log(attrs.title) // 我是</script><template><!-- 在模板中使用 $attrs 访问属性 --><div>{{ $attrs.title }}</div></template>
useSlots
在模板中使用 $slots
来访问 slots
数据。
在 <script setup>
中使用 useSlots
函数获取 slots
插槽数据。
<script setup>import HelloWorld from './components/HelloWorld.vue'</script><template><HelloWorld><div>默认插槽</div><template v-slot:footer><div>具名插槽footer</div></template></HelloWorld></template>
<script setup>import { useSlots } from 'vue'const slots = useSlots()// 在js中访问插槽默认插槽default、具名插槽footerconsole.log(slots.default)console.log(slots.footer)</script><template><div><!-- 在模板中使用插槽 --><slot></slot><slot name="footer"></slot></div></template>
useCssModule
在 Vue3
中,也是支持 CSS Modules
的,在 <style>
上增加 module
属性,即<style module>
。
<style module>
代码块会被编译为 CSS Modules
并且将生成的 CSS 类作为 $style
对象的键暴露给组件,可以直接在模板中使用 $style
。而对于如 <style module="content">
具名 CSS Modules
,编译后生成的 CSS 类作为 content
对象的键暴露给组件,即module
属性值什么,就暴露什么对象。
<script setup lang="ts">import { useCssModule } from 'vue'// 不传递参数,获取<style module>代码块编译后的css类对象const style = useCssModule()console.log(style.success) // 获取到的是success类名经过 hash 计算后的类名// 传递参数content,获取<style module="content">代码块编译后的css类对象const contentStyle = useCssModule('content')</script><template><div class="success">普通style red</div><div :class="$style.success">默认CssModule pink</div><div :class="style.success">默认CssModule pink</div><div :class="contentStyle.success">具名CssModule blue</div><div :class="content.success">具名CssModule blue</div></template><!-- 普通style --><style>.success {color: red;}</style><!-- 无值的css module --><style module lang="less">.success {color: pink;}</style><!-- 具名的css module --><style module="content" lang="less">.success {color: blue;}</style>
注意,同名的CSS Module,后面的会覆盖前面的。
2.5. 使用组件
在组件选项中,模板需要使用组件(除了全局组件),需要在 components
选项中注册。
而在 <script setup>
中组件不需要再注册,模板可以直接使用,其实就是相当于一个顶层变量。
建议使用大驼峰(PascalCase)命名组件和使用组件。
<script setup>import HelloWorld from './HelloWorld.vue'</script><template><HelloWorld /></template>
2.6. 组件name
<script setup>
是没有组件配置项 name
的,可以再使用一个普通的 <script>
来配置 name
。
// ./components/HelloWorld.vue<script>export default {name: 'HelloWorld'}</script><script setup>import { ref } from 'vue'const total = ref(10)</script><template><div>{{ total }}</div></template>
使用:
<script setup>import HelloWorld from './components/HelloWorld.vue'console.log(HelloWorld.name) // 'HelloWorld'</script><template><HelloWorld /></template>
注意: 如果你设置了 lang
属性,<script setup>
和 <script>
的 lang
需要保持一致。
2.7. inheritAttrs
inheritAttrs
表示是否禁用属性继承,默认值是 true
。
<script setup>
是没有组件配置项 inheritAttrs 的,可以再使用一个普通的 <script>
。
<script setup>import HelloWorld from './components/HelloWorld.vue'</script><template><HelloWorld title="我是title"/></template>
./components/HelloWorld.vue
<script>export default {name: 'HelloWorld',inheritAttrs: false,}</script><script setup>import { useAttrs } from 'vue'const attrs = useAttrs()</script><template><div><span :title="attrs.title">hover一下看title</span><span :title="$attrs.title">hover一下看title</span></div></template>
2.8. 顶层await支持
<script setup>
中可以使用顶层 await。结果代码会被编译成 async setup()
<script setup>const userInfo = await fetch(`/api/post/getUserInfo`)</script>
注意:async setup()
必须与 Suspense
组合使用,Suspense
目前还是处于实验阶段的特性,其 API 可能随时会发生变动,建议暂时不要使用。
2.9. 命名空间组件
在 vue3
中,我们可以使用点语法来使用挂载在一个对象上的组件。
// components/Form/index.jsimport Form from './Form.vue'import Input from './Input.vue'import Label from './Label.vue'// 把Input、Label组件挂载到 Form 组件上Form.Input = InputForm.Label = Labelexport default Form// 使用:<script setup lang="ts">import Form from './components/Form'</script><template><Form><Form.Label /><Form.Input /></Form></template>
/
命名空间组件在另外一种场景中的使用,从单个文件中导入多个组件时:
// FormComponents/index.jsimport Input from './Input.vue'import Label from './Label.vue'export default {Input,Label,}// 使用<script setup>import * as Form from './FormComponents'</script><template><Form.Input><Form.Label>label</Form.Label></Form.Input></template>
2.10. 状态驱动的动态 CSS
Vue3
中 <style>
标签可以通过 v-bind
这一 CSS 函数将 CSS 的值关联到动态的组件状态上。
<script setup>const theme = {color: 'red'}</script><template><p>hello</p></template><style scoped>p {// 使用顶层绑定color: v-bind('theme.color');}</style>
2.11. 指令
全局指令:
<template>
<div v-click-outside />
</template>
自定义指令:
<script setup>import { ref } from 'vue'const total = ref(10)// 自定义指令// 必须以 小写字母v开头的小驼峰 的格式来命名本地自定义指令// 在模板中使用时,需要用中划线的格式表示,不可直接使用vMyDirectiveconst vMyDirective = {beforeMount: (el, binding, vnode) => {el.style.borderColor = 'red'},updated(el, binding, vnode) {if (el.value % 2 !== 0) {el.style.borderColor = 'blue'} else {el.style.borderColor = 'red'}},}const add = () => {total.value++}</script><template><input :value="total" v-my-directive /><button @click="add">add+1</button></template>
导入的指令:
<script setup>// 导入的指令同样需要满足命名规范import { directive as vClickOutside } from 'v-click-outside'</script><template><div v-click-outside /></template>
更多关于指令,见官方文档(https://v3.cn.vuejs.org/guide/custom-directive.html#%E7%AE%80%E4%BB%8B、https://v3.cn.vuejs.org/api/application-api.html#directive)。
2.12. Composition Api类型约束
<script setup lang="ts">import { ref, reactive, computed } from 'vue' type User = { name: string age: number} // refconst msg1 = ref('') // 会默认约束成 string 类型,因为ts类型推导const msg2 = ref<string>('') // 可以通过范型约束类型const user1 = ref<User>({ name: 'tang', age: 18 }) // 范型约束const user2 = ref({} as User) // 类型断言 // reactiveconst obj = reactive({})const user3 = reactive<User>({ name: 'tang', age: 18 })const user4 = reactive({} as User) // computedconst msg3 = computed(() => msg1.value)const user5 = computed<User>(() => { return { name: 'tang', age: 18 }})</script>