Vue3 组件命名

Vue3 的组件，即 SFC，单文件组件。

组件的文件名推荐采用首字母大写驼峰或者字母小写连字符的方式，例如：MyComponent.vue、my-component.vue。

每个 Vue3 组件，都应当设置 name 属性，这也是我们本文的重点。

name 属性的用途

组件的名字有以下几种用途：

在组件自己的模板中递归引用自己时。
在 Vue 开发者工具中的组件树显示时。
在组件抛出的警告追踪栈信息中显示时。
使用 KeepAlive，通过该属性来匹配需要缓存的组件时。

声明 name 属性

而当我们在 vue3 项目中采用组合式 API <script setup> 的写法，需要显示的声明 name 属性。

有以下几种方式来声明 name 属性：

defineOptions

vue 官方在 vue@3.3 及以上版本中推出了 defineOptions API，允许你直接在 <script setup> 中声明组件选项，无需额外的<script>标签或是第三方插件。

<script setup>
  defineOptions({ 
    name: 'MyComponent',
    inheritAttrs: false
  })
</script>

1
2
3
4
5
6

终于能愉快的设置组件的 name 属性了🎉

自动生成

如果项目使用的是 3.2.34 及以上版本的 vue，当你没有显式的定义组件的 name 属性时，使用 <script setup> 的组件会自动根据文件名生成对应的 name 属性，自动生成的 name 属性也能用于<KeepAlive>。

比如，当你的组件文件名为 MyComponent.vue 或者是 my-component.vue 时，对应组件的 name 属性则是 MyComponent。

使用 script 标签

我们可以在 <script setup> 标签外再定义一个 script 标签，用于声明 name 属性。

<script>
export default {
  name: 'MyComponent',
}
</script>

<script setup>
...
</script>

1
2
3
4
5
6
7
8
9

使用 `unplugin-vue-define-options`

安装 unplugin-vue-define-options

yarn install unplugin-vue-define-options @vue-macros/volar -D

配置 vite

配置 typescript 支持

为了提供类型声明，还需要在 tsconfig.json 文件中配置。

提示

正确配置之后，就可以解决在使用时 vscode 提示 defineOptions is not defined 的错误。

使用

安装配置完成后，就能使用其提供的 defineOptions API 来定义 name 属性。

<script setup lang="ts">
  // 无需手动 import defineOptions
  defineOptions({
    name: "MyComponent"  
  })
</script>

1
2
3
4
5
6

原理

unplugin-vue-define-options 插件的实现原理很简单，对于使用了 defineOptions 的代码：

<script setup lang="ts">
  import { useSlots } from 'vue'
    
  defineOptions({
    name: 'Foo',
    inheritAttrs: false,
  })
  const slots = useSlots()
</script>

1
2
3
4
5
6
7
8
9

编译后输出为：

<script lang="ts">
  export default {
    name: 'Foo',
    inheritAttrs: false,
    props: {
      msg: { type: String, default: 'bar' },
    },
    emits: ['change', 'update'],
  }
  </script>

  <script setup>
  const slots = useSlots()
  </script>

1
2
3
4
5
6
7
8
9
10
11
12
13
14

可以发现，这和我们在上文中书写 2 个 script 标签是一样的，也就是说，unplugin-vue-define-options 通过 vite 插件的方式，在编译阶段帮我们做了编写 2 个 script 这一步，简化了我们的开发。

提示

其他的 name 声明插件的实现方式也是大同小异，比如vite-plugin-vue-setup-extend，也是采用了 2 个 script 标签的做法，万变不离其宗。

最佳实践

对于使用 vue@3.3 及以上的版本，直接使用官方的 defineOptions API。

对于使用 vue@3.3 版本以下的，使用 unplugin-vue-define-options/vite 的方式来声明 name 属性，同时组件文件名遵循首字母大写驼峰或者字母小写连字符的方式。

Vue3 组件命名 #

name 属性的用途 #

声明 name 属性 #

defineOptions #

自动生成 #

使用 script 标签 #

使用 unplugin-vue-define-options #

最佳实践 #