组件概述

组件定义

• 组件是视图层的基本组成单元。
• 组件是一个单独且可复用的UI及配套功能模块的封装。

我们知道js逻辑可以封装为函数或类库。而对于页面上可视的元素，则可以将ui、样式、逻辑一起封装为组件。

组件涉及较多的概念，包括组件名称、开头和闭合标签、组件属性、组件属性值、组件事件、组件vue指令、组件text内容、子组件。

我们先看一个简单的例子：

<component-name property1="value" property2="value">
	content
</component-name>

上面的代码，是一个组件，组件名为component-name，这个组件有2个属性，property1和property2，这2个属性的属性值都是"value"，组件的text内容为"content"

然后我们看一个全面但有些复杂的示例，这段示例融合了组件的各种概念：

<template>
  <view></view>
	<view>
		<text v-if="titleShow" :style="'color:' + titleColor">{{title}}</text> <!-- text组件的text绑定了响应式变量title、v-if指令绑定了titleShow、style绑定了titleColor-->
	</view>
	<image src="http://www.noexit.jpg" @error="imgerror"/>
	<scroll-view >
		<button type="primary" @click="buttonClick_changeText">修改文字内容</button>
		<button @click="buttonClick_showHide">点击让文字组件显示或消失</button>
		<button @click="buttonClick_changeColor">修改文字颜色</button>
	</scroll-view>
</template>
<script setup>
  let title = ref("Hello world") //定义一个响应式变量title，默认赋值为hello world
	const buttonClick_changeText = () => {
		title.value = "新文字内容" //对响应式变量title的.value属性赋值，界面上文字会自动同步修改
	}

	let titleShow = ref(true) //决定标题文字是否显示
	const buttonClick_showHide = () => {
		titleShow.value = !titleShow.value //对响应式变量的.value属性赋值，界面上文字组件的v-if指令绑定了titleShow，所以会动态显示消失
	}

	let titleColor = ref("black") //定义一个响应式变量titleColor，默认为黑色
	const buttonClick_changeColor = () => {
		titleColor.value = "red" //对响应式变量的.value属性赋值，界面上文字组件的style属性绑定了titleColor，所以会变为红色
	}

	const imgerror = (event : ImageErrorEvent) => { // image组件加载失败时触发
		console.log(event.type, event.detail); //错误的详情
	}
</script>

所有组件，都写在template标签下面。

• 组件的名称和开始/结束标签 每个组件，都有开始和结束标签。
  标签由尖括号包裹，它有开始标签和结束标签。结束标签的<后面用/来表示结束。结束标签也称为闭合标签。 比如上面例子中template节点下第一个子节点 ，view 表示这个组件的名称，为开始标签，为闭合标签。这是一个空的view视图组件。

如果标签没有text内容或子组件，可以写成 自闭合标签，即只写 开始标签，并且 开始标签 以 /> 结尾。
比如上面例子中的 <image src="http://www.noexit.jpg" @error="imgerror"/>

• 组件内容text 指组件的内容区，即组件的开始标签和闭合标签之间的文字内容。
  比如上面例子中button组件中的“修改文字内容”。
  uni-app x中只有button、text组件等少数组件支持内容区，具体需查阅每个组件文档。

• 子组件 组件的内容区可以不是文字，而是下级组件。
  比如上面例子中view组件的子组件是text组件，而scroll-view组件下面有3个button子组件。
  并非所有组件都支持子组件，一般视图组件肯定是支持子组件的，其他组件需要查阅组件的文档说明。

• 组件属性 组件开始标签的组件名称后面，以空格分割的、以等号赋值的，不以v-或@开头的普通属性。
  比如上面例子中button组件的type属性，它定义了组件的一些控制参数，这是由组件作者给使用者提供的自定义参数。\

• 组件属性值 在属性名后面用=号赋值的内容。
  比如上面例子中button组件的type属性，其属性值为primary，type="primary"，即表示一个主按钮。\

• 事件 组件在发生某些事件后触发的函数。
  比如上面例子中button组件的click事件。@click="buttonClick_changeText"。
  buttonClick_changeText 是script里定义的一个函数。
  事件区别于普通属性名的特征是以@开头，事件值指向一个函数（选项式指向一个method）。
  很多事件还有event参数。
  比如上面例子中image组件的error事件，绑定到imgerror函数，它有一个参数event对象，类型是ImageErrorEvent。接下来的代码打印了event对象的2个属性。

• vue指令 vue提供的一批特殊写法的属性，它们以v-开头，比如上面例子中text组件的v-if指令，绑定了一个titleShow的响应式变量，根据变量的true或false可以决定text组件是否显示。详见vue指令
  有一种特殊指令v-bind，一种把属性值变成script以便绑定响应式变量的写法，它的完整写法是 v-bind:普通属性名 = "属性值"， 但它更常见的写法是简写为在普通属性前面加个冒号，比如上面例子中text组件的:style，:style="'color:' + titleColor"。
  这个写法的意思是，text组件的style样式中，color属性的值绑定到了script定义的响应式变量titleColor上，修改这个响应式变量的值，text组件的文字颜色就会跟着变化。
  绑定后属性值的内容变成了script，而不再是普通字符串。所以在属性值里写字符串需要再加单引号。

组件们，有公共的属性和事件，详见，也有组件特有的属性和事件，详见每个组件的文档。

每个组件可以有多个属性、指令、事件，用空格分割。它们赋值的=号，前后可以允许0个或1个空格。

所有组件与属性名都是小写，单词之间以连字符-连接。

组件的分类

uni-app x文档规范中有一批标准组件，同时也支持扩展自定义组件。

1. 标准组件

• 1.1 内置组件 内置在uni-app x引擎中，开发者无需在代码中引用和注册的，可以直接使用。比如view、text、button...
• 1.2 ext组件 在app平台，对于不太常用、体积又大的官方基础组件，虽然其文档在uni-app x的官方文档中，但并没有内置到uni-app x引擎中。需要开发者下载ext组件到项目下才能使用。
  出现这种情况一般是由于小程序规范里内置了该组件，而App端又不常用。（为了多端兼容，uni的组件规范是参考小程序组件规范制定的）
  比如animation-view组件。
  除了ext组件，还有ext api，它们情况类似，详细介绍：ext插件

2. 自定义组件

标准组件只是一些基础组件。开发者还可以自行扩展组件，封装UI和逻辑，称为自定义组件。

这类组件需要手动下载到项目中，或者自行在项目下编写。

自定义组件，按开发方式分类，又有2种：前端uvue组件 和 原生uts组件

• 2.1 前端uvue组件 即开发者自己按照vue组件规范编写的uvue文件。这种组件一般由前端工程师编写。详见uvue组件模型介绍
• 2.2 原生uts组件 这是一种App平台专用的扩展机制。 由Android或iOS的原生开发者，按照uts插件的组件规范编写，把原生的view嵌入到uvue页面上，它在编写时贴近但不完全是vue组件开发规范。
  不过对于组件的使用者来讲，用法就是标准的uvue组件了。详见uts组件开发指南
  uts原生组件，下载组件到项目后（或自己按规范编写），在页面template里直接引用即可。无需导入注册组件。

对于前端uvue组件，又有2种引用方式。

1. 传统vue组件： 需要先import、注册，然后再在页面template中使用。详见
2. easycom组件 easycom组件是uni-app提供的一种易用方式，它通过一个路径规范让编译器知道组件的位置，实现自动的import和注册。详见easycom组件规范

在uni插件市场（https://ext.dcloud.net.cn/），下载的组件基本都是easycom组件规范或uts原生组件规范，都是在页面里可以直接引用的。

插件市场的功能较多，可以看介绍了解：详见

其他组件概念

• datacom datacom是一种数据驱动的组件，只需要给出符合格式的数据就可以使用。它是uvue组件的子类，尤其适合云端一体组件。详见：datacom介绍

• uni_modules uni_modules是uni-app生态的包管理方案。非内置组件，可以放在项目下任意位置，也可以封装在uni_modules下。一般对外提供的成熟组件都应该封装在uni_modules下。
  如果还不了解uni_modules，那务必需要阅读：uni_modules介绍

组件的编写

• 前端uvue组件的开发指南：详见
• uts原生组件的开发指南：详见

组件开发完毕后可发布到插件市场，插件作者指南：详见

调用组件方法

需要把组件分为 内置组件、easycom组件、非easycom组件，这3种组件有不同的方法调用方式。详情

内置组件的方法调用或设置属性

3.93+ 支持

使用 this.$refs 获取组件并as转换为组件对应的element类型，通过 .操作符 调用组件方法或设置属性。详情

easycom组件调用方法或设置属性

3.97+ 支持 uni_modules 目录下的组件

easycom组件，用法和内置组件一样。也是使用 this.$refs 获取组件并转换为组件的类型，通过 .操作符 调用组件方法或设置属性。详情

其它自定义组件的方法调用使用callMethod

如果不是内置组件，也不是easycom组件，那么无法使用.操作符了。

此时需使用 this.$refs 获取组件实例，然后通过 $callMethod 调用组件的方法。也就是把组件的方法名、参数，当做callMethod的参数来传递。此时也就没有.操作符那样的代码提示和校验了。详情

如何开发同时兼容 uni-app x 和 uni-app 的组件

目前有两种方案：

• 目录下同时提供uvue，vue文件，分别适配 uni-app x 和 uni-app

组件作者在 uvue 和 vue 文件中可以自由使用各自的特性，比如 vue 中可以任意使用 js 或 ts 来书写代码，

如果部分组件逻辑被抽离为单独的文件，需要分别命名为各自环境支持的文件类型，导入时不同平台支持的文件类型也不同，

比如 uvue 文件目前不支持引入js或ts，而 vue 文件不能引入 uts 文件

对于现有的 uni-app 组件，通过新建 uvue 文件来渐进式支持 uni-app x，可以避免对已有 uni-app 项目造成影响

• 仅提供一个vue文件，同时适配 uni-app x 和 uni-app

该方案，需要script节点配置lang="ts"，这样才可以在 uni-app 项目中正常书写带有类型的代码，而在 uni-app x 项目中，则会忽略 lang="ts"，当做 uts 代码编译。

当需要区分平台或项目类型时，可以使用对应的条件编译。

比如通过 UNI-APP-X 来区分项目类型，更多条件编译见：详情

vue 与 uvue 不同文件后缀的优先级

新建组件时(注意不是新建页面)，默认组件的后缀名为.uvue，但也支持.vue。

.vue里面写uvue的语法，可以正常被.uvue页面引用和编译。

.vue里写条件编译，可以制作同时满足uni-app和uni-app x的组件。

.vue中适用于uni-app x的条件编译区域内的代码，必须符合uni-app x的规范。如果使用uni-app x不支持的、uni-app js引擎版特有的功能，会报错。

当你手动import或easycom手动配置规则，可以指定文件名后缀。比如import PageHead from '@/components/page-head.uvue'

但如果未明确指定组件后缀名的情况，且同一个组件目录下即存在.vue文件、又存在.uvue文件， 此时 vue 组件和 uvue 组件的优先级如下：

• 在 uni-app x 中，优先使用 uvue 组件，如果不存在 uvue 组件，则使用 vue 组件。
• 在 uni-app 中，只支持使用 vue 组件。