uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
uni-app x
uni-app
uni-app x
uniCloud
HBuilder
uni 小程序 sdk
简体中文
组件
button
兼容性
属性
子组件
示例
参见
hover-class 属性值
button样式修改
button点击
tips
展示全部

# button

组件类型：UniButtonElement

按钮

# 兼容性

Web 微信小程序 Android iOS HarmonyOS
4.0 4.41 3.9 4.11 4.61

# 属性

名称 类型 默认值 兼容性 描述
disabled boolean false
是否禁用
hover-class string(string.ClassString) "button-hover"
指定按下去的样式类。当 hover-class="none" 时，没有点击态效果
hover-stop-propagation boolean -
指定是否阻止本节点的祖先节点出现点击态
hover-start-time number 20
按住后多久出现点击态，单位毫秒
hover-stay-time number 70
手指松开后点击态保留时间，单位毫秒
size string "default"
按钮的大小
合法值 兼容性 描述
default
默认大小
mini
小尺寸
type string "default"
按钮的样式类型
合法值 兼容性 描述
default
白色
primary
蓝色
warn
红色
plain boolean false
按钮是否镂空，背景色透明
loading boolean -
名称前是否带 loading 图标
form-type string -
用于 form 组件，点击分别会触发 form 组件的 submit/reset 事件
合法值 兼容性 描述
submit
提交表单
reset
重置表单
open-type string -
开放能力
合法值 兼容性 描述
agreePrivacyAuthorization
用户同意隐私协议按钮。用户点击一次此按钮后，所有已声明过的隐私接口可以正常调用。
feedback
打开“意见反馈”页面，用户可提交反馈内容并上传日志
share
触发用户转发
getUserInfo
获取用户信息，可以从getuserinfo回调中获取到用户信息
contact
打开客服会话，如果用户在会话中点击消息卡片后返回应用，可以从 contact 回调中获得具体信息
getPhoneNumber
获取用户手机号，可以从getphonenumber回调中获取到用户信息
launchApp
打开APP，可以通过app-parameter属性设定向APP传的参数
openSetting
打开授权设置页
chooseAvatar
获取用户头像，可以从chooseavatar回调中获取到头像信息
getAuthorize
支持小程序授权
lifestyle
关注生活号
contactShare
分享到通讯录好友
openGroupProfile
呼起QQ群资料卡页面，可以通过group-id属性设定需要打开的群资料卡的群号，同时manifest.json中必须配置groupIdList
openGuildProfile
呼起频道页面，可以通过guild-id属性设定需要打开的频道ID
openPublicProfile
打开公众号资料卡，可以通过public-id属性设定需要打开的公众号资料卡的号码，同时manifest.json中必须配置publicIdList
shareMessageToFriend
在自定义开放数据域组件中,向指定好友发起分享据
addFriend
添加好友，对方需要通过该小程序进行授权，允许被加好友后才能调用成功用户授权
addColorSign
添加彩签，点击后添加状态有用户提示，无回调
addGroupApp
添加群应用（只有管理员或群主有权操作），添加后给button绑定addgroupapp事件接收回调数据
addToFavorites
收藏当前页面，点击按钮后会触发Page.onAddToFavorites方法
chooseAddress
选择用户收货地址，可以从chooseaddress回调中获取到用户选择的地址信息
chooseInvoiceTitle
选择用户发票抬头，可以从chooseinvoicetitle回调中获取到用户选择发票抬头信息
login
登录，可以从login回调中确认是否登录成功
subscribe
订阅类模板消息，需要用户授权才可发送
favorite
触发用户收藏
watchLater
触发用户稍后再看
openProfile
触发打开用户主页
liveActivity
通过前端获取新的一次性订阅消息下发机制使用的 code
getRealtimePhoneNumber
手机号实时验证，向用户申请，并在用户同意后，快速填写和实时验证手机号。具体说明 （小程序插件中不能使用）
lang string -
指定返回用户信息的语言，zh_CN 简体中文，zh_TW 繁体中文，en 英文。
合法值 兼容性 描述
en
英文
zh_CN
简体中文
zh_TW
繁体中文
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 -
打开公众号资料卡时，传递的号码
@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 -
登录回调
phone-number-no-quota-toast boolean -
(boolean)
当手机号快速验证或手机号实时验证额度用尽时，是否对用户展示“申请获取你的手机号，但该功能使用次数已达当前小程序上限，暂时无法使用”的提示，默认展示，open-type="getPhoneNumber" 或 open-type="getRealtimePhoneNumber" 时有效
createliveactivity eventhandle -
(eventhandle)
新的一次性订阅消息下发机制回调，open-type=liveActivity时有效
@getrealtimephonenumber eventhandle -
(eventhandle)
手机号实时验证回调，open-type=getRealtimePhoneNumber 时有效。Tips：在触发 bindgetrealtimephonenumber 回调后应立即隐藏手机号按钮组件，或置为 disabled 状态，避免用户重复授权手机号产生额外费用。
@agreeprivacyauthorization eventhandle -
(eventhandle)
用户同意隐私协议事件回调，open-type=agreePrivacyAuthorization时有效 （Tips: 如果使用 onNeedPrivacyAuthorization 接口，需要在 bindagreeprivacyauthorization 触发后再调用 resolve({ event: "agree", buttonId })）
  • 在web平台，由于0.5px有兼容性问题，button的边框使用伪类实现。
  • 在app平台，HBuilderX4.02及以上版本调整为原生实现button组件，默认边框不占高度，解决button实际渲染宽高与Web端不一致的问题；HBuilderX4.01及以下版本封装text实现button组件，由于不支持伪类，默认边框使用 border 样式实现，会导致button的实际的渲染宽高在app端比web端多1px。
  • button的默认边框宽度为0.5px，当type属性为plain时，边框宽度是1px，此时在web平台button实际的渲染宽高会大于其他类型1px，在app平台button实际的渲染高度与其他类型一致。
  • button 的text区域文字，app平台HBuilderX4.02及以上版本支持 \n 方式换行，HBuilderX4.01及以下版本不支持 ，会直接显示 \n 字符；Web端 \n 会变成一个空格。
  • button按下后触发hover-class效果，在app平台，手指不松开、一直在屏幕上移动、离开button组件范围后，hover-class效果消失，同时也不会触发点击事件；在web平台，手指移动一点后，即便未离开button范围，hover-class效果也会消失，同时也不会触发点击事件。
  • 无论在哪个平台，hover-class消失后松开手指，都不会触发点击事件。
  • button 设置hover-class属性时需注意，app平台HBuilderX4.04及以下版本与web平台有差异，HBuilderX4.05版本统一为以下规则：
    • 如果hover-class属性值设置为none，在style样式里面设置了同名的none样式，none样式将不起作用，没有点击态效果
    • 如果hover-class属性值设置为button-hover或者不设置hover-class属性值，在style样式里面设置了同名的button-hover样式，点击效果将使用button-hover样式
    • 如果hover-class属性值设置为无效值（或非法值），没有点击态效果
  • open-type="agreePrivacyAuthorization"，用于开发者在让用户同意隐私协议时，放置“同意”按钮。它并非强制性的，它只是开发者和插件作者之间的一种通信方式。并不是没有点下这个按钮，技术上就拦截了涉及隐私的API的调用。详见

# 子组件

不可以嵌套组件

# 示例

示例为hello uni-app x alpha分支，与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

扫码体验（手机浏览器跳转到App直达页）

示例

<script>
  import { ItemType } from '@/components/enum-data/enum-data-types'
  export default {
    data() {
      return {
        plain_boolean: false,
        disabled_boolean: false,
        default_style: false,
        size_enum: [{ "value": 0, "name": "default" }, { "value": 1, "name": "mini" }] as ItemType[],
        size_enum_current: 0,
        type_enum: [{ "value": 0, "name": "default" }, { "value": 1, "name": "primary" }, { "value": 2, "name": "warn" }] as ItemType[],
        type_enum_current: 0,
        count: 0,
        text: ''
      }
    },
    onReady() {
      this.text = 'uni-app-x'
    },
    methods: {
      button_click() {
        console.log("组件被点击时触发")
        this.count++
      },
      button_touchstart() { console.log("手指触摸动作开始") },
      button_touchmove() { console.log("手指触摸后移动") },
      button_touchcancel() { console.log("手指触摸动作被打断，如来电提醒，弹窗") },
      button_touchend() { console.log("手指触摸动作结束") },
      button_tap() { console.log("手指触摸后马上离开") },
      button_longpress() { console.log("如果一个组件被绑定了 longpress 事件，那么当用户长按这个组件时，该事件将会被触发。") },
      change_plain_boolean(checked : boolean) { this.plain_boolean = checked },
      change_disabled_boolean(checked : boolean) { this.disabled_boolean = checked },
      change_default_style(checked : boolean) { this.default_style = checked },
      radio_change_size_enum(checked : number) { this.size_enum_current = checked },
      radio_change_type_enum(checked : number) { this.type_enum_current = checked },
      confirm_text_input(value : string) { this.text = value },
      navigateToChild() {
        uni.navigateTo({
          url: 'buttonstatus',
        })
      },
      openPrivacyDialog() {
        uni.openDialogPage({
          url: '/pages/component/button/privacy',
        })
      },
      //用于自动化测试
      checkUniButtonElement() : boolean {
        const button = uni.getElementById("testButton")
        if (button != null && button instanceof UniButtonElement) {
          return true
        }
        return false
      }
    }
  }
</script>

<template>
  <view class="main">
    <button id="testButton" :disabled="disabled_boolean" :size="size_enum[size_enum_current].name"
      :type="type_enum[type_enum_current].name" :plain="plain_boolean" @click="button_click"
      @touchstart="button_touchstart" @touchmove="button_touchmove" @touchcancel="button_touchcancel"
      @touchend="button_touchend" @tap="button_tap" @longpress="button_longpress" class="btn"
      :class="default_style ? (disabled_boolean ? 'custom-btn-disable' : 'custom-btn') : ''"
      :hover-class="default_style ? 'is-hover' : 'button-hover'">
      {{ 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>
      <enum-data :items="size_enum" title="按钮的大小" @change="radio_change_size_enum"></enum-data>
      <enum-data :items="type_enum" title="按钮的类型" @change="radio_change_type_enum"></enum-data>
      <input-data :defaultValue="text" title="按钮的文案" type="text" @confirm="confirm_text_input"></input-data>
      <view style="height: 10px;"></view>
      <button @click="navigateToChild">更多示例</button>
      <view style="height: 10px;"></view>
      <!-- #ifdef APP -->
      <button @click="openPrivacyDialog">open-type实现App隐私政策弹框</button>
      <view style="height: 10px;"></view>
      <!-- #endif -->
    </view>
  </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);
  }
</style>

# 参见

# hover-class 属性值

# button样式修改

button在元素的text区域直接写文字，和text组件一样。可以这么理解，button是一个特殊的text组件，文字样式可以直接写在button组件的style或class上。

button组件属性中的size和type，属于预置样式，方便开发者使用。开发者也可以通过style和class来自定义样式。但它们在不同平台，覆盖方式需要注意：

- App和Web平台style和class的优先级，高于size和type属性
- 小程序平台，取决于不同小程序平台的button的实现方式。在微信小程序上，type和size属性的样式通过属性选择器设置，开发者设置的class，想要覆盖这2个属性的样式，需要加`!important`。而通过style设置样式，则优先级高于属性选择器，所以可以覆盖2个属性设置的样式。

如果开发者要自定义button样式，最好不要使用type和size。包括type的颜色在不同小程序平台不一样，甚至在微信小程序的v1和v2的样式中也不一样。如果一定要用type，那么用style而不是class覆盖属性样式，也可以跨端兼容。

button虽然可以内嵌text组件，但不建议通过text组件来修改button样式，因为会导致hove-class不生效。尤其是uvue中样式不继承。建议button组件text区域直接写文字，然后在button组件的style或class属性编写样式。

<template>
	<button size="default" type="default"
	style="color:#ffffff;backgroundColor:#1AAD19;borderColor:#1AAD19"
	hover-class="is-hover">按钮</button>
</template>
<style>
.is-hover {
	color: rgba(255, 255, 255, 0.6);
	background-color: #179b16;
	border-color: #179b16;
  }
</style>

# button点击

button 组件的点击遵循 vue 标准的 @click事件。

button 组件没有 url 属性，如果要跳转页面，可以在@click中编写，也可以在button组件外面套一层 navigator 组件。举例，如需跳转到about页面，可按如下几种代码写法执行：

<template>
	<view>
		<navigator url="/pages/about/about"><button>通过navigator组件跳转到about页面</button></navigator>
		<button @click="goto('/pages/about/about')">通过方法跳转到about页面</button>
	</view>
</template>
<script>
	export default {
		methods: {
			goto(url:string) {
				uni.navigateTo({
					url:url
				})
			}
		}
	}
</script>

# tips

  • button 的默认文字大小为18px，文字行高为2.5。如果指定了按钮高度，要注意手动调整文字行高

# 样式冲突

使用属性选择器定义css存在平台兼容性，差异点如下：

  • Web 因页面样式作用域隔离机制编译后会在 class 上增加属性选择器，会覆盖组件属性选择器样式
  • App 暂不支持属性选择器
  • 微信小程序 普通 class 不能直接覆盖组件的属性选择器，因为属性选择器样式优先级更高
本页导读
button
兼容性
属性
子组件
示例
参见
hover-class 属性值
button样式修改
button点击
tips
样式冲突