# Button 按钮

该组件内部实现以uni-appbutton组件为基础，进行二次封装，主要区别在于：

  • 按钮type值有更多的主题颜色
  • 按钮size值有更多的尺寸可选

注意

  1. 此组件内部使用uni-appbutton组件为基础，除了开头中所说的增加的功能，另外暴露出来的props属性和官方组件的属性完全一致， uni-appbutton组件比较特殊，因为它有一些其他小程序平台的特定能力，请参考文档后面的参数列表，更详细说明请参uni-app方文档：
    uni-app方button组件 (opens new window)
  2. 由于微信小程序的限制，在微信小程序中设置了form-type的zx-button无法触发form组件的submit事件(H5和APP正常)，详见微信小程序文档Bug & Tip部分 (opens new window)

# 平台差异说明

App（vue） App（nvue） H5 小程序
√ √ √ √

# 基本使用

文字内容通过text传入

<zx-button text="月落"></zx-button>

# 设置按钮的多种形态

  • type值可选的有default(默认)、primary、success、info、warning、error
  • 通过plain值设置是否镂空
  • 通过hairline值设置是否细边
  • 通过disabled值设置是否禁用
  • 通过loading值设置是否开启加载图标，loadingText设置加载中文字
  • 通过icon值设置是否显示图标
  • 通过shape值设置按钮形状，circle为圆角
  • 通过color值设置按钮渐变颜色
  • 通过size值设置按钮的大小
<template>
	<view style="padding: 20px;">
		<zx-button type="primary" text="确定"></zx-button>
		<zx-button type="primary" :plain="true" text="镂空"></zx-button>
		<zx-button type="primary" :plain="true" :hairline="true" text="细边"></zx-button>
		<zx-button type="primary" :disabled="disabled" text="禁用"></zx-button>
		<zx-button type="primary" loading loadingText="加载中"></zx-button>
		<zx-button type="primary" icon="map" text="图标按钮"></zx-button>
		<zx-button type="primary" shape="circle" text="按钮形状"></zx-button>
		<zx-button text="渐变色按钮" color="linear-gradient(to right, rgb(66, 83, 216), rgb(213, 51, 186))"></zx-button>
		<zx-button type="primary" size="small" text="大小尺寸"></zx-button>
	</view>
</template>

<script>
export default {
	data() {
		return {
			disabled: true
		};
	}
};
</script>

# 定义需要用到的外部样式

  1. 针对非微信小程序平台，组件的根元素就是uni-appbutton组件，所以修改按钮的样式很容易，直接给组件定义类名或者嵌入内联样式即可。
  2. 如果是微信小程序，编译后页面会有组件同名的元素存在，导致样式传递有问题。
  3. 如果是为了修改按钮与其他元素之间的距离或者宽度等，可以给按钮外面套一个view元素，控制这个view与其他元素的距离或者宽度，即可达到同等效果。

所以：我们提供了一个custom-style参数，推荐用户可以用对象形式传递样式给组件内部，注意驼峰命名。

<template>
	<view style="padding: 20px;">
		 <!-- 以下形式在微信小程序会无效，APP和H5有效  -->
		<zx-button class="custom-style" text="雪月夜"></zx-button>
	</view>
</template>

<script>
export default {
	data() {
		return {
			disabled: true,
			customStyle: {
				marginTop: '20px', // 注意驼峰命名，并且值必须用引号包括，因为这是对象
				color: 'red'
			}
		};
	}
};
</script>

<style lang="scss" scoped>
	.custom-style {
		color: #ff0000;
		width: 400rpx;
	}
</style>

# API

# Props

属性名 说明 类型 默认值 可选值 平台差异说明
hairline 是否显示按钮的细边框 Boolean true false -
type 按钮的样式类型 String info info / primary / error/ warning / success -
size 按钮的大小 String normal large / mini -
shape 按钮外观形状，见上方说明 String square circle -
plain 按钮是否镂空，背景色透明 Boolean false true -
disabled 是否禁用 Boolean false true -
loading 按钮名称前是否带 loading 图标 Boolean false true App-nvue 平台，在 ios 上为雪花，Android上为圆圈
loadingText 加载中提示文字 String - - -
loadingMode 加载状态图标类型 String spinner - -
loadingSize 加载图标大小 String | Number 15 - -
openType 开放能力，具体请看uniapp稳定关于button组件部分说明 String - - -
formType 用于 <form> 组件，点击分别会触发 <form> 组件的 submit/reset 事件 String - - -
appParameter 打开 APP 时，向 APP 传递的参数，open-type=launchApp时有效 （注：只微信小程序、QQ小程序有效） String - - -
hoverStopPropagation 指定是否阻止本节点的祖先节点出现点击态，微信小程序有效（默认 true） Boolean true false -
lang 指定返回用户信息的语言，zh_CN 简体中文，zh_TW 繁体中文，en 英文 String en - -
sessionFrom 会话来源，openType="contact"时有效 String - - -
sendMessageTitle 会话内消息卡片标题，openType="contact"时有效 String - - -
sendMessagePath 会话内消息卡片点击跳转小程序路径，openType="contact"时有效 String - - -
sendMessageImg 会话内消息卡片图片，openType="contact"时有效 String - - -
showMessageCard 是否显示会话内消息卡片，设置此参数为 true，用户进入客服会话会在右下角显示"可能要发送的小程序"提示，用户点击后可以快速发送小程序消息，openType="contact"时有效 String - - -
dataName 额外传参参数，用于小程序的data-xxx属性，通过target.dataset.name获取 String - - -
throttleTime 节流，一定时间内只能触发一次，单位毫秒 String | Number 0 - -
hoverStartTime 按住后多久出现点击态，单位毫秒 String | Number 0 - -
hoverStayTime 手指松开后点击态保留时间，单位毫秒 String | Number 200 - -
text 按钮文字，之所以通过props传入，是因为slot传入的话（注：nvue中无法控制文字的样式） String | Number - - -
icon 按钮图标 String - - -
iconColor 按钮颜色 String 在plain=true镂空状态下，颜色与边框保持一致，否则为白色（主题为info时为黑色#000000） - -
color 按钮颜色，支持传入linear-gradient渐变色 String - - -
customStyle 定义需要用到的外部样式,详细见上方文档 Object - - -

# Events

说明：目前经测试(Hbuilder X 2.6.8)，在H5，APP，可以直接对组件监听tap事件，等同组件内部发出的click事件效果，某些HX版本上， 微信小程序对组件使用tap事件可能无效，故建议对按钮组件的点击事件监听统一使用组件内部发出的click事件。

属性名 说明 类型 默认值 可选值 平台差异说明
click 按钮点击，请勿使用@tap点击事件，微信小程序无效，返回值为点击事件及参数 Handler - - -
getphonenumber open-type="getPhoneNumber"时有效 Handler 微信小程序 - -
getuserinfo 用户点击该按钮时，会返回获取到的用户信息，从返回参数的detail中获取到的值同uni.getUserInfo Handler 微信小程序 - -
error 当使用开放能力时，发生错误的回调 Handler 微信小程序 - -
opensetting 在打开授权设置页并关闭后回调 Handler 微信小程序 - -
launchapp 打开 APP 成功的回调 Handler 微信小程序 - -