uniapp常用组件
写在前面
今天将uniapp中的组件都过了一遍,上手难度不大,但是还是遇到了一些问题:
- HBuilder实在是太难用,不管是插件生态还是设计之类的,总之就是用的哪哪不顺手
- 虽然打开内置浏览器是挺方便的,但是不知道是不是其热重载什么的,当你配置路由或者跨页修改时它会出现乱码之类的情况,建议关掉重开
- 不支持自定义属性……
- git插件不是很好用……
- 虽然设置了失去焦点自动保存但是就是很鸡肋感受很不好,建议ctrl+s焊手上
- 报错功能不完善,像是个别单词拼写错误什么的不报错很难受
- 我发现各类ai对小程序开发貌似都不太感冒,有点冒傻
关于我写的练习demo
涵盖所有常用组件与常用方法,已上传至github:https://github.com/ZhengxuanYe/uniapp_component_test.git

还有还有
- 如有纰漏请谅解,以官方文档为准
- 后面这段时间我会学习小程序开发的知识,会持续更新
- 可以查看我的github,后续我会上传我的uniapp相关练习代码
- 有兴趣的话可以浏览我的个人网站,我会在上面持续更新内容,我新配置了评论功能,可以留下一个友善的评论,这对我有很大帮助
text
文本组件。用于包裹文本内容。
在app-uvue和app-nvue中,文本只能写在text中,而不能写在view的text区域。
虽然app-uvue中写在view的text区域的文字,也会被编译器自动包裹一层text组件,看起来也可以使用。但这样会造成无法修改该text文字的样式
属性说明
属性名 | 类型 | 默认值 | 说明 | 平台差异说明 |
---|---|---|---|---|
selectable | Boolean | false | 文本是否可选 | |
user-select | Boolean | false | 文本是否可选 | 微信小程序 |
space | String | 显示连续空格 | 钉钉小程序不支持 | |
decode | Boolean | false | 是否解码 | 百度、钉钉小程序不支持 |
space 值说明
值 | 说明 |
---|---|
ensp | 中文字符空格一半大小 |
emsp | 中文字符空格大小 |
nbsp | 根据字体设置的空格大小 |
子组件
text组件在web浏览器渲染(含浏览器、小程序webview渲染模式、app-vue)和uvue中,可以并只能嵌套text组件。
在nvue中,text组件不能嵌套。
Tips
- 支持
\n
方式换行。 - 在app-nvue下,只有
<text>
才能包裹文本内容。无法在<view>
组件包裹文本。 - decode 可以解析的有
<
>
&
'
- 各个操作系统的空格标准并不一致。
- 除了文本节点以外的其他节点都无法长按选中。
- 如果使用
<span>
组件编译时会被转换为<text>
。 - nvue 样式
word-wrap
在 Android 平台暂不支持
scroll-view
可滚动视图区域。用于区域滚动。
需注意在webview渲染的页面中,区域滚动的性能不及页面滚动。
主要特性
- 竖向滚动:通过设置
scroll-y="true"
来启用垂直方向上的滚动。 - 横向滚动:通过设置
scroll-x="true"
来启用水平方向上的滚动。 - 固定高度/宽度:对于竖向滚动,需要给
<scroll-view>
设置一个固定的高度;对于横向滚动,则通常需要设置一个固定的宽度。 - 样式控制:可以通过 CSS 控制滚动视图的样式,比如隐藏滚动条等。
注意事项
- 在使用竖向滚动时,必须为
<scroll-view>
设置一个明确的高度。 - 对于横向滚动,需要确保子元素不会换行(即
white-space: nowrap
),并且每个子元素都设置了display: inline-block
。 - 当内容较少不足以触发滚动时,滚动条不会出现。
- 不要在
<scroll-view>
中放置原生组件如map
或video
,特别是在小程序端。 - 避免将过长的数据列表放入
<scroll-view>
中,这可能会导致性能问题。对于长列表,请考虑使用分页加载或虚拟列表技术。
一键回到顶部
总结你提供的方法,可以将实现点击按钮返回顶部功能的关键步骤和代码解释如下:
数据绑定
- 在 Vue 组件的
data()
函数中定义了一个名为scrollTop
的变量。这个变量与<scroll-view>
组件的:scroll-top
属性绑定,意味着当scrollTop
变量值变化时,滚动视图会自动更新其垂直滚动位置。
事件监听
- 使用
@scroll
事件监听器来捕获滚动事件,并在事件处理函数中更新组件实例中的一个属性(例如old.scrollTop
),用于保存当前滚动位置。这使得可以在需要的时候访问或修改滚动位置。
返回顶部方法
goTop
方法是实现返回顶部的核心逻辑:- 首先,它设置
scrollTop
为当前滚动位置。 - 然后使用
$nextTick
方法确保 DOM 更新完成后,再次将scrollTop
设置为0
,以触发滚动到顶部的动作。 - 此外,还使用了
uni.showToast
来显示一条消息提示用户滚动位置已经被重置为顶部。
- 首先,它设置
1 | goTop: function(e) { |
- 在模板中,有一个带有
@tap="goTop"
属性的<view>
标签,这意味着当用户点击该区域时,将会调用goTop
方法来执行返回顶部的操作。
swiper
滑块视图容器。
一般用于左右滑动或上下滑动,比如banner轮播图。
注意滑动切换和滚动的区别,滑动切换是一屏一屏的切换。swiper下的每个swiper-item是一个滑动切换区域,不能停留在2个滑动区域之间。
属性说明
indicator-dots
: 是否显示面板指示点,默认为false
。autoplay
: 是否自动切换,默认为false
。interval
: 自动切换时间间隔,默认为5000ms
。duration
: 滑动动画时长,默认为500ms
。circular
: 是否采用衔接滑动,默认为false
。如果设置为true
,则可以实现无缝滚动效果。vertical
: 是否纵向模式,默认为false
。如果设置为true
,则变为上下滑动。current
: 当前所在滑块的索引值,默认为0
。
事件监听
@change
: 轮播图切换时触发,可以通过此事件获取当前索引。示例:
1
2
3<swiper @change="swiperChange">
<!-- ... -->
</swiper>1
2
3
4
5methods: {
swiperChange(e) {
console.log('当前索引:', e.detail.current);
}
}
注意事项
- 性能优化:当轮播图中的图片较多或者较大时,建议进行图片懒加载处理,以提高页面加载速度。
- 样式调整:根据实际需求调整
<swiper>
和<swiper-item>
的样式,比如高度、宽度等。 - 兼容性:确保在不同平台(如微信小程序、H5等)上测试轮播图的表现,因为各平台可能存在细微差异。
通过上述配置和属性设置,你可以轻松创建一个功能齐全且美观的轮播图组件。此外,结合其他自定义样式或交互逻辑,可以让轮播图更加符合你的项目需求。
movable-view
可移动的视图容器,在页面中可以拖拽滑动或双指缩放。
movable-view
必须在movable-area
组件中,并且必须是直接子节点,否则不能移动。
以下是 movable-view
组件的属性说明,根据你提供的信息整理而成:
属性名 | 类型 | 默认值 | 说明 | 平台差异说明 |
---|---|---|---|---|
direction | String | none | 定义 movable-view 的移动方向。可选值有 all(任意方向)、vertical(垂直方向)、horizontal(水平方向)、none(不可移动) |
- |
inertia | Boolean | false | 是否带有惯性,即在拖动结束后是否还会继续滑动一小段距离。 | - |
out-of-bounds | Boolean | false | 当超过可移动区域后,movable-view 是否还可以继续移动。 |
- |
x | Number / String | - | 定义 x 轴方向的偏移量。如果设置的值不在可移动范围内,则会自动调整到可移动范围,并且改变此值会触发动画效果。 | - |
y | Number / String | - | 定义 y 轴方向的偏移量。如果设置的值不在可移动范围内,则会自动调整到可移动范围,并且改变此值会触发动画效果。 | - |
damping | Number | 20 | 阻尼系数,用于控制 x 或 y 方向改变时动画的速度和过界回弹的效果。数值越大,移动速度越快。 | 360小程序不支持 |
friction | Number | 2 | 摩擦系数,影响惯性滑动的停止速度。数值越大,摩擦力越大,滑动越快停止。必须大于 0,否则会被设置成默认值。 | 360小程序不支持 |
disabled | Boolean | false | 是否禁用 movable-view 。当为 true 时,组件将无法被用户操作。 |
- |
scale | Boolean | false | 是否支持双指缩放。默认情况下,缩放手势生效区域是在 movable-view 内部。 |
360小程序不支持 |
scale-min | Number | 0.1/0.5 | 定义缩放倍数的最小值。对于 0.1 倍的缩放,需要 App(4.51+)、H5(4.51+)、微信小程序(4.51+) 版本的支持。 | - |
scale-max | Number | 10 | 定义缩放倍数的最大值。 | - |
scale-value | Number | 1 | 定义当前的缩放倍数,取值范围通常为 0.1/0.5 至 10。对于 0.1 倍的缩放,同样需要特定版本的支持。 | - |
animation | Boolean | true | 是否使用动画效果。当改变 x 或 y 的值时,是否以动画形式过渡。 |
- |
@change | EventHandle | - | 拖动过程中触发的事件,event.detail 包含 {x: x, y: y, source: source},其中 source 可能的值包括 touch(拖动)、touch-out-of-bounds(超出移动范围)、out-of-bounds(超出移动范围后的回弹)、friction(惯性)以及空字符串(setData)。 | - |
@scale | EventHandle | - | 缩放过程中触发的事件,event.detail 包含 {x: x, y: y, scale: scale}。主要用于监听缩放动作的发生。 | - |
icon
属性说明
属性名 | 类型 | 默认值 | 说明 |
---|---|---|---|
type | String | icon的类型 | |
size | Number | 23 | icon的大小,单位px |
color | Color | icon的颜色,同css的color |
各平台 type 有效值说明:
平台 | type 有效值 |
---|---|
App、H5、微信小程序、QQ小程序 | success, success_no_circle, info, warn, waiting, cancel, download, search, clear |
支付宝小程序 | info, warn, waiting, cancel, download, search, clear, success, success_no_circle,loading |
百度小程序 | success, info, warn, waiting, success_no_circle, clear, search, personal, setting, top, close, cancel, download, checkboxSelected, radioSelected, radioUnselect |
rich-text
富文本。
支持默认事件,包括:click、touchstart、touchmove、touchcancel、touchend、longpress.
属性名 | 类型 | 默认值 | 说明 | 平台兼容 |
---|---|---|---|---|
nodes | Array / String | [] | 节点列表 / HTML String | |
space | string | 显示连续空格 | App、H5、微信基础库2.4.1+详见、QQ小程序、抖音小程序、快手小程序详见 | |
selectable | Boolean | true | 富文本是否可以长按选中,可用于复制,粘贴等场景 | 百度小程序(仅真机支持,基础库 3.150.1 以下版本默认为 false) |
image-menu-prevent | Boolean | false | 阻止长按图片时弹起默认菜单(将该属性设置为image-menu-prevent或image-menu-prevent=”true”),只在初始化时有效,不能动态变更;若不想阻止弹起默认菜单,则不需要设置此属性 | 百度小程序 |
preview | Boolean | 富文本中的图片是否可点击预览。在不设置的情况下,若 rich-text 未监听点击事件,则默认开启。未显示设置 preview 时会进行点击默认预览判断,建议显示设置 preview | 百度小程序 | |
@itemclick | EventHandle | 拦截点击事件(只支持 a 、img 标签),返回当前node信息 event.detail={node} |
H5 (3.2.13+)、App-Vue (3.2.13+) |
progress
属性名 | 类型 | 默认值 | 说明 | 平台差异说明 |
---|---|---|---|---|
percent | Number | 无 | 百分比0~100 | |
show-info | Boolean | false | 在进度条右侧显示百分比 | |
border-radius | Number/String | 0 | 圆角大小 | app-nvue、微信基础库2.3.1+、QQ小程序、快手小程序、京东小程序 |
font-size | Number/String | 16 | 右侧百分比字体大小 | app-nvue、微信基础库2.3.1+、QQ小程序、京东小程序 |
stroke-width | Number | 6 | 进度条线的宽度,单位px | |
activeColor | Color | #09BB07(百度为#E6E6E6) | 已选择的进度条的颜色 | |
backgroundColor | Color | #EBEBEB | 未选择的进度条的颜色 | |
active | Boolean | false | 进度条从左往右的动画 | |
active-mode | String | backwards | 动画从头播;forwards:动画从上次结束点接着播 | App、H5、微信小程序、QQ小程序、快手小程序、京东小程序 |
duration | Number | 30 | 进度增加1%所需毫秒数 | App-nvue2.6.1+、微信基础库2.8.2+、H5 3.1.11+、App-Vue 3.1.11+、快手小程序、京东小程序 |
@activeend | EventHandle | 动画完成事件 | 微信小程序、京东小程序 |
checkbox-group
属性说明
属性名 | 类型 | 默认值 | 说明 |
---|---|---|---|
@change | EventHandle | <checkbox-group> 中选中项发生改变是触发 change 事件,detail = {value:[选中的checkbox的value的数组]} |
checkbox
多选项。在1组check-group中可选择多个
属性说明
属性名 | 类型 | 默认值 | 说明 | 平台差异说明 |
---|---|---|---|---|
value | String | <checkbox> 标识,选中时触发 <checkbox-group> 的 change 事件,并携带 <checkbox> 的 value。 |
||
disabled | Boolean | false | 是否禁用 | |
checked | Boolean | false | 当前是否选中,可用来设置默认选中 | |
color | Color | checkbox的颜色,同css的color | ||
backgroundColor | Color | #ffffff | checkbox默认的背景颜色 | H5(3.99+)、App-Vue(3.99+) |
borderColor | Color | #d1d1d1 | checkbox默认的边框颜色 | H5(3.99+)、App-Vue(3.99+) |
activeBackgroundColor | Color | #ffffff | checkbox选中时的背景颜色,优先级大于color属性 | H5(3.99+)、App-Vue(3.99+) |
activeBorderColor | Color | #d1d1d1 | checkbox选中时的边框颜色 | H5(3.99+)、App-Vue(3.99+) |
iconColor | Color | #007aff | checkbox的图标颜色 | H5(3.99+)、App-Vue(3.99+) |
Button
在UniApp中,<button>
组件是一个非常基础且重要的组件,用于创建按钮。它不仅支持文本内容,还可以嵌套其他组件,如图片、图标等,并提供了丰富的属性和事件来增强交互性。
基本用法
1 | <template> |
属性说明
type
: 按钮的样式类型,可选值包括primary
(主色调)、default
(默认样式)、warn
(警告色)。默认为default
。示例:
1
2
3<button type="primary">主要按钮</button>
<button type="default">默认按钮</button>
<button type="warn">警告按钮</button>size
: 按钮大小,可选值有default
(默认大小)、mini
(小尺寸)。示例:
1
2<button size="default">默认大小</button>
<button size="mini">小型按钮</button>plain
: 是否镂空,即背景透明,默认为false
。示例:
1
<button plain>镂空按钮</button>
disabled
: 是否禁用,默认为false
。示例:
1
<button disabled>禁用按钮</button>
loading
: 是否显示加载图标,默认为false
。示例:
1
<button loading>加载中</button>
事件监听
@click
: 点击事件。示例:
1
<button @click="handleClick">点击事件</button>
1
2
3
4
5methods: {
handleClick() {
console.log('按钮被点击');
}
}
样式自定义
尽管 <button>
组件提供了多种预设样式,但你也可以通过自定义类名或内联样式来进一步定制按钮的外观。
1 | <template> |
注意事项
- 平台差异:不同平台(如微信小程序、H5等)对
<button>
的渲染可能存在细微差别,请务必进行跨平台测试。 - 嵌套限制:虽然
<button>
支持嵌套其他组件,但在某些平台上可能会有限制或不一致的行为。建议尽量保持简单的内容结构。 - 用户体验:考虑使用不同的
type
和状态(如disabled
或loading
)来提供更好的用户反馈。
通过合理利用 <button>
组件的属性和事件,你可以创建出功能强大且美观的按钮,从而提升应用的交互体验。
#在UniApp中,<switch>
、<input>
和 <textarea>
组件用于处理用户输入。它们各自有特定的用途和属性,下面将分别介绍这些组件的基本使用方法及其重要属性。
Switch
<switch>
组件用于切换选择器(开关),允许用户在两种状态之间进行选择。
基本用法
1 | <template> |
属性说明
checked
: 开关是否被选中,默认为false
。type
: 样式类型,可选值switch
或checkbox
,默认是switch
。color
: switch 打开时的背景色。disabled
: 是否禁用,默认为false
。
Input
<input>
组件用于接收文本输入或其它类型的输入(如数字、密码等)。
基本用法
1 | <template> |
属性说明
type
: 输入框类型,支持text
,number
,idcard
,digit
,password
等。placeholder
: 输入框为空时占位符文本。value
: 输入框的初始值,可通过v-model
实现双向绑定。disabled
: 是否禁用输入框,默认为false
。maxlength
: 最大输入长度,设置为-1
表示不限制长度。
Textarea
<textarea>
组件用于多行文本输入。
基本用法
1 | <template> |
属性说明
placeholder
: 文本区域为空时显示的提示信息。value
: 文本区域的初始值,同样可以通过v-model
实现双向数据绑定。auto-height
: 是否自动增高,默认为false
。如果设置为true
,则可以根据输入内容自动调整高度。disabled
: 是否禁用文本区域,默认为false
。maxlength
: 最大输入长度,设置为-1
表示无限制。
uniapp组件的显示类型
在UniApp中,组件的显示类型(行内、块级等)和HTML标准元素类似,但也有其特定的组件库。
块级组件
这些组件默认情况下占据父容器的整个宽度,并且独占一行。
组件名称 | 描述 |
---|---|
<view> |
类似于HTML中的<div> ,是最常用的布局容器组件。 |
<scroll-view> |
提供滚动功能的容器组件,可以设置竖向或横向滚动。需要设定固定的高度或宽度来实现滚动效果。 |
<swiper> |
轮播图组件,用于实现图片或内容的轮播切换。 |
行内组件
这些组件不会独占一行,而是与其他行内组件并排显示。
组件名称 | 描述 |
---|---|
<text> |
类似于HTML中的<span> ,用于包裹文本内容。支持文本换行等特性。 |
<rich-text> |
用于展示富文本内容。 |
行内块级组件
这些组件既具有行内元素的特点又具备块级元素的一些特性,比如可以设置宽高。
组件名称 | 描述 |
---|---|
<button> |
按钮组件,可直接使用或嵌套其他组件。 |
<input> |
输入框组件,包括文本输入框、密码输入框等。 |
<image> |
图片组件,用于展示图像。 |
特殊组件
还有一些组件因其特殊用途而不能简单归类为上述任意一种显示类型。
组件名称 | 描述 |
---|---|
<navigator> |
页面导航组件,用于页面之间的跳转。 |
<video> |
视频播放组件。 |