# button
组件类型：UniButtonElement
按钮
# 兼容性 ?
| Web | 微信小程序 | 支付宝小程序 | Android | iOS | HarmonyOS |
|---|---|---|---|---|---|
| 4.0 | 4.41 | 5.25 | 3.9 | 4.11 | 4.61 |
# 属性
| 名称 | 类型 | 默认值 | 兼容性 | 描述 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| disabled | boolean | false | 是否禁用 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hover-class | string(string.ClassString) | "button-hover" | 指定按下去的样式类。当 hover-class="none" 时，没有点击态效果 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hover-stop-propagation | boolean | false | 指定是否阻止本节点的祖先节点出现点击态 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hover-start-time | number | 20 | 按住后多久出现点击态，单位毫秒 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| hover-stay-time | number | 70 | 手指松开后点击态保留时间，单位毫秒 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| size | string | "default" | 按钮大小 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| type | string | "default" | 按钮类型 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| plain | boolean | false | 按钮是否镂空，背景色透明 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| loading | boolean | false | 名称前是否带 loading 图标 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| form-type | string | 用于 form 组件，点击分别会触发 form 组件的 submit/reset 事件 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| open-type | string | 开放能力 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lang | string | 指定返回用户信息的语言，zh_CN 简体中文，zh_TW 繁体中文，en 英文。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| session-from | string | 会话来源 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| send-message-title | string | 会话内消息卡片标题 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| send-message-path | string | 会话内消息卡片点击跳转应用路径 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| send-message-img | string | 会话内消息卡片图片 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| show-message-card | boolean | 显示会话内消息卡片 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| app-parameter | string | 打开 APP 时，向 APP 传递的参数 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| group-id | string | 打开群资料卡时，传递的群号 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| guild-id | string | 打开频道页面时，传递的频道号 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| public-id | string | 打开公众号资料卡时，传递的号码 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| phone-number-no-quota-toast | boolean | (boolean) 当手机号快速验证或手机号实时验证额度用尽时，是否对用户展示“申请获取你的手机号，但该功能使用次数已达当前小程序上限，暂时无法使用”的提示，默认展示，open-type="getPhoneNumber" 或 open-type="getRealtimePhoneNumber" 时有效 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| createliveactivity | eventhandle | (eventhandle) 新的一次性订阅消息下发机制回调，open-type=liveActivity时有效 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| loading-class | string(string.ClassString) | loading 图标的类名 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| loading-text-class | string(string.ClassString) | loading 文案的类名 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ios-loading-snow | boolean | false | iOS 雪花加载效果 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @getuserinfo | (event: UniEvent) => void | 用户点击该按钮时，会返回获取到的用户信息，回调的detail数据与uni.getUserInfo返回的一致 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @contact | (event: UniEvent) => void | 客服消息回调 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @getphonenumber | (event: UniEvent) => void | 获取用户手机号回调 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @error | (event: UniEvent) => void | 当使用开放能力时，发生错误的回调 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @opensetting | (event: UniEvent) => void | 在打开授权设置页后回调 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @launchapp | (event: UniEvent) => void | 打开 APP 成功的回调 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @chooseavatar | (event: UniEvent) => void | 获取用户头像回调 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @chooseaddress | (event: UniEvent) => void | 调起用户编辑并选择收货地址的回调 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @chooseinvoicetitle | (event: UniEvent) => void | 用户选择发票抬头的回调 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @addgroupapp | (event: UniEvent) => void | 添加群应用的回调 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @subscribe | (event: UniEvent) => void | 订阅消息授权回调 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @login | (event: UniEvent) => void | 登录回调 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @getrealtimephonenumber | eventhandle | (eventhandle) 手机号实时验证回调，open-type=getRealtimePhoneNumber 时有效。Tips：在触发 bindgetrealtimephonenumber 回调后应立即隐藏手机号按钮组件，或置为 disabled 状态，避免用户重复授权手机号产生额外费用。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| @agreeprivacyauthorization | eventhandle | (eventhandle) 用户同意隐私协议事件回调，open-type=agreePrivacyAuthorization时有效 （Tips: 如果使用 onNeedPrivacyAuthorization 接口，需要在 bindagreeprivacyauthorization 触发后再调用 resolve({ event: "agree", buttonId })） | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
# 子组件
不可以嵌套组件
# 示例
示例为hello uni-app x alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见
示例
<script setup lang="uts">
import { ItemType } from '@/components/enum-data/enum-data-types'
type DataType = {
plain_boolean: boolean;
disabled_boolean: boolean;
default_style: boolean;
size_enum: ItemType[];
size_enum_current: number;
type_enum: ItemType[];
type_enum_current: number;
count: number;
text: string;
loading: boolean;
}
// 使用reactive避免ref数据在自动化测试中无法访问
const data = reactive({
plain_boolean: false,
disabled_boolean: false,
default_style: false,
size_enum: [{ "value": 0, "name": "default" }, { "value": 1, "name": "mini" }],
size_enum_current: 0,
type_enum: [{ "value": 0, "name": "default" }, { "value": 1, "name": "primary" }, { "value": 2, "name": "warn" }],
type_enum_current: 0,
count: 0,
text: '',
loading: false,
} as DataType)
onReady(() => {
data.text = 'uni-app-x'
})
const button_click = () => {
console.log("组件被点击时触发")
data.count++
}
const button_touchstart = () => {
console.log("手指触摸动作开始")
}
const button_touchmove = () => {
console.log("手指触摸后移动")
}
const button_touchcancel = () => {
console.log("手指触摸动作被打断，如来电提醒，弹窗")
}
const button_touchend = () => {
console.log("手指触摸动作结束")
}
const button_tap = () => {
console.log("手指触摸后马上离开")
}
const button_longpress = () => {
console.log("如果一个组件被绑定了 longpress 事件，那么当用户长按这个组件时，该事件将会被触发。")
}
const change_plain_boolean = (checked: boolean) => {
data.plain_boolean = checked
}
const change_loading = (checked: boolean) => {
data.loading = checked
}
const change_disabled_boolean = (checked: boolean) => {
data.disabled_boolean = checked
}
const change_default_style = (checked: boolean) => {
data.default_style = checked
}
const radio_change_size_enum = (checked: number) => {
data.size_enum_current = checked
}
const radio_change_type_enum = (checked: number) => {
data.type_enum_current = checked
}
const confirm_text_input = (value: string) => {
data.text = value
}
const navigateToChild = () => {
uni.navigateTo({
url: 'buttonstatus',
})
}
const openPrivacyDialog = () => {
uni.openDialogPage({
url: '/pages/component/button/privacy',
})
}
//用于自动化测试
const checkUniButtonElement = (): boolean => {
const button = uni.getElementById("testButton")
if (button != null && button instanceof UniButtonElement) {
return true
}
return false
}
defineExpose({
data,
checkUniButtonElement
})
</script>
<template>
<view class="main">
<button id="testButton" :loading="data.loading" :disabled="data.disabled_boolean"
:size="data.size_enum[data.size_enum_current].name" :type="data.type_enum[data.type_enum_current].name"
:plain="data.plain_boolean" @touchstart="button_touchstart" @touchmove="button_touchmove"
@touchcancel="button_touchcancel" @touchend="button_touchend" @tap="button_tap" @click="button_click"
@longpress="button_longpress" class="btn"
:loading-text-class="data.loading ? (data.type_enum[data.type_enum_current].name == 'default' ? 'black-loading-text' : 'white-loading-text') : ''"
:class="data.default_style ? (data.disabled_boolean ? 'custom-btn-disable' : 'custom-btn') : ''"
:hover-class="data.default_style ? 'is-hover' : 'button-hover'">
{{ data.text }}
</button>
</view>
<scroll-view style="flex: 1">
<view class="content">
<boolean-data :defaultValue="false" title="按钮是否镂空，背景色透明" @change="change_plain_boolean"></boolean-data>
<boolean-data :defaultValue="false" title="是否禁用" @change="change_disabled_boolean"></boolean-data>
<boolean-data :defaultValue="false" title="修改默认样式和点击效果(高优先)" @change="change_default_style"></boolean-data>
<boolean-data :defaultValue="false" title="显示loading（限小程序和蒸汽模式的App）" @change="change_loading"></boolean-data>
<enum-data :items="data.size_enum" title="按钮的大小" @change="radio_change_size_enum"></enum-data>
<enum-data :items="data.type_enum" title="按钮的类型" @change="radio_change_type_enum"></enum-data>
<input-data :defaultValue="data.text" title="按钮的文案" type="text" @confirm="confirm_text_input"></input-data>
<view style="height: 10px;"></view>
<button @click="navigateToChild">更多button示例</button>
<view style="height: 10px;"></view>
<!-- #ifdef APP -->
<button @click="openPrivacyDialog">open-type实现App隐私政策弹框</button>
<view style="height: 10px;"></view>
<!-- #endif -->
</view>
<navigator url="/pages/template/button-100/button-100">
<button>组件性能测试</button>
</navigator>
</scroll-view>
</template>
<style>
.main {
padding: 5px 0;
border-bottom: 1px solid rgba(0, 0, 0, 0.06);
flex-direction: row;
justify-content: center;
}
.custom-btn {
color: #ffffff;
background-color: #1AAD19;
border-color: #1AAD19;
}
.custom-btn-disable {
color: rgba(255, 255, 255, 0.7);
background-color: rgba(26, 173, 25, 0.7);
border-color: rgba(26, 173, 25, 0.7);
}
.is-hover {
color: rgba(255, 255, 255, 0.6);
background-color: #179b16;
border-color: #179b16;
}
.button-hover {
color: rgba(0, 0, 0, 0.6);
background-color: #dedede;
}
.default-button {
color: #000000;
background-color: #f8f8f8;
border-color: rgba(0, 0, 0, 0.2);
}
.black-loading-text {
color: #000000
}
.white-loading-text {
color: #ffffff
}
</style>
# 参见
- 相关 Bug
- 参见uni-app相关文档
- 微信小程序文档
- 支付宝小程序文档
- 百度小程序文档
- 抖音小程序文档
- 飞书小程序文档
- 钉钉小程序文档
- QQ小程序文档
- 快手小程序文档
- 京东小程序文档
- 华为快应用文档
- 360小程序文档
# 样式修改
button 的 size、type 属性是预置样式，适合快速使用；如需修改文字、背景、边框、尺寸等样式，可直接在 button 组件上使用 style 或 class 覆盖。如需保持样式一致，建议不要依赖 type 的默认颜色。
APP 蒸汽模式不支持属性选择器，建议使用 class 或 style 自定义样式。
APP蒸汽模式、WEB 和微信小程序平台的 button 组件在 plain 为 true 时，通过 class 配置的 background-color 样式不生效，只能通过 style 设置。
<template>
<button class="custom-button" hover-class="custom-button-hover">按钮</button>
</template>
<style>
.custom-button {
color: #ffffff;
background-color: #1AAD19;
border-color: #1AAD19;
}
.custom-button-hover {
color: rgba(255, 255, 255, 0.6);
background-color: #179b16;
border-color: #179b16;
}
</style>
# hover-class 属性值
button 按下后触发 hover-class 效果。点击态取消后的触发规则如下：
- Android 平台：手指不松开并持续在屏幕上移动，离开 button 组件范围后，hover-class 效果消失。
- iOS 平台：手指按下后，hover-class 效果会保持到手指抬起时消失。
- 鸿蒙平台、Web 平台：手指移动一点后，即便未离开 button 范围，hover-class 效果也会消失。
button 设置 hover-class 属性规则如下：
- 如果 hover-class 属性值设置为 button-hover 或者不设置 hover-class 属性值，在 style 样式里面设置了同名的 button-hover 样式，点击效果将使用 button-hover 样式。
- 如果 hover-class 属性值设置为无效值（或非法值），没有点击态效果。
# 点击跳转
button 组件没有 url 属性，点击后需要跳转页面时，可在 @click 中调用路由 API，也可以使用 navigator 组件实现声明式跳转。
<template>
<view>
<button @click="gotoAbout">跳转到 about 页面</button>
<navigator url="/pages/about/about" open-type="navigate">
<button>使用 navigator 跳转到 about 页面</button>
</navigator>
</view>
</template>
<script setup lang="uts">
function gotoAbout() {
uni.navigateTo({
url: '/pages/about/about'
})
}
</script>
# 隐私协议授权
open-type="agreePrivacyAuthorization" 用于开发者在让用户同意隐私协议时，放置“同意”按钮。它不是强制拦截能力，只是开发者和插件作者之间的一种通信方式；未点击该按钮，并不代表技术上会拦截涉及隐私的 API 调用。详见
# 文本显示
- 如果 button 组件的文本内容包含
\n，非蒸汽模式 APP 和 web 会被渲染为字符，不会换行，微信小程序会移除换行符号。蒸汽模式 APP 会移除\n旁的文字。 - 非蒸汽模式 button 默认文字大小为 18px，文字行高为 2.5。自定义高度时，需要同步调整 line-height。
- APP 蒸汽模式下，button 的文字居中依赖 padding。调整 height 和 line-height 时，建议同时将 padding-top、padding-bottom 设置为 0。
<template>
<button style="height: 50px; line-height: 50px; padding-top: 0; padding-bottom: 0;">按钮</button>
</template>
