外观
Button 按钮
约 1863 字大约 6 分钟
2025-10-31
按钮类型
按钮提供了多种类型，包括信息、成功、危险、主要和警告类型，每种类型都有不同的颜色主题。
<un-button text="信息按钮" type="info"></un-button>
<un-button text="成功按钮" type="success"></un-button>
<un-button text="危险按钮" type="error"></un-button>
<un-button text="主要按钮" type="primary"></un-button>
<un-button text="警告按钮" type="warning"></un-button>镂空按钮
通过设置plain属性，可以创建镂空按钮，背景色透明，保留边框颜色。
<un-button text="镂空按钮" type="info" plain></un-button>
<un-button text="镂空按钮" type="success" plain></un-button>
<un-button text="镂空按钮" type="error" plain></un-button>
<un-button text="镂空按钮" type="primary" plain></un-button>
<un-button text="镂空按钮" type="warning" plain></un-button>细边按钮
在镂空按钮的基础上，通过设置hairline属性，可以创建更细的边框按钮。
<un-button text="细边按钮" type="info" plain hairline></un-button>
<un-button text="细边按钮" type="success" plain hairline></un-button>
<un-button text="细边按钮" type="error" plain hairline></un-button>
<un-button text="细边按钮" type="primary" plain hairline></un-button>
<un-button text="细边按钮" type="warning" plain hairline></un-button>加载中按钮
通过设置loading属性，可以显示加载状态，适用于异步操作场景。
<un-button text="加载中" type="success" plain loading></un-button>
<un-button text="加载中" type="error" loading></un-button>禁用按钮
通过设置disabled属性，可以禁用按钮，禁用状态下按钮不可点击。
<un-button text="禁用按钮" type="info" disabled></un-button>
<un-button text="禁用按钮" type="success" disabled></un-button>
<un-button text="禁用按钮" type="error" disabled></un-button>
<un-button text="禁用按钮" type="primary" disabled></un-button>
<un-button text="禁用按钮" type="warning" disabled></un-button>按钮图标和形状
通过设置icon属性可以添加图标，通过iconPosition可以控制图标位置，通过shape可以设置按钮形状。
<un-button text="按钮图标" icon="map" type="primary"></un-button>
<un-button text="图标在右侧" icon="map" iconPosition="right" type="warning"></un-button>自定义颜色
通过设置color属性，可以自定义按钮颜色，支持渐变色。
<un-button text="渐变色按钮" color="linear-gradient(to right, rgb(66, 83, 216), rgb(213, 51, 186))"></un-button>
<un-button text="渐变色按钮" color="linear-gradient(to right, rgb(220, 194, 11), rgb(4, 151, 99))"></un-button>
<un-button text="青绿色按钮" color="rgb(10, 185, 156)"></un-button>自定义大小和形状
通过设置size属性可以调整按钮大小，通过设置shape属性可以改变按钮形状。
<un-button text="超大尺寸" size="large" type="success"></un-button>
<un-button text="普通尺寸" size="normal" type="error"></un-button>
<un-button text="小型尺寸" size="small" type="primary"></un-button>
<un-button text="超小尺寸" size="mini" type="warning"></un-button>
<un-button text="普通尺寸" size="normal" type="error" shape="circle"></un-button>
<un-button text="小型尺寸" size="small" type="primary" shape="circle"></un-button>
<un-button text="超小尺寸" size="mini" type="warning" shape="circle"></un-button>Button Props
| 参数 | 说明 | 类型 | 默认值 |
|---|---|---|---|
| hairline | 是否显示按钮的细边框 | boolean | true |
| type | 按钮的样式类型 | Enum | default |
| size | 按钮的大小 | Enum | normal |
| block | 按钮是否为块级元素 | boolean | false |
| shape | 按钮外观形状，见上方说明 | Enum | square |
| plain | 按钮是否镂空，背景色透明 | boolean | false |
| disabled | 是否禁用 | boolean | false |
| round | 设置圆角值 | string | number | 3px |
| loading | 按钮名称前是否带 loading 图标 | boolean | false |
| loadingMode | 加载状态图标类型 | Enum | spinner |
| loadingSize | 加载图标大小 | string | number | 15 |
| loadingIcon 4.1.0 | 自定义图标名称，参考 un-icon 组件, 支持图片, mode为custom时有效 | string | - |
| openType | 开放能力，具体请看uniapp稳定关于button组件部分说明 | string | - |
| formType | 用于 <form> 组件，点击分别会触发 <form> 组件的 submit/reset 事件 | string | - |
| appParameter | 打开 APP 时，向 APP 传递的参数，open-type=launchApp时有效 （注：只微信小程序、QQ小程序有效） | string | - |
| hoverStopPropagation | 指定是否阻止本节点的祖先节点出现点击态，微信小程序有效（默认 true） | boolean | true |
| 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"时有效 | boolean | false |
| dataName | 额外传参参数，用于小程序的data-xxx属性，通过target.dataset.name获取 | string | - |
| throttleTime | 节流，一定时间内只能触发一次，单位毫秒 | string | number | 0 |
| hoverStartTime | 按住后多久出现点击态，单位毫秒 | string | number | 0 |
| hoverStayTime | 手指松开后点击态保留时间，单位毫秒 | string | number | 200 |
| hoverClass 4.1.0 | 点击态类名，当 hover-class="none" 时，没有点击态效果 | string | un-button--hover |
| text | 按钮文字，之所以通过props传入，是因为slot传入的话（注：nvue中无法控制文字的样式） | string | number | - |
| icon | 按钮图标 | string | - |
| iconColor | 按钮颜色 | string | - |
| iconPosition | 按钮图标位置 | string | left |
| color | 按钮颜色，支持传入linear-gradient渐变色 | string | - |
| customStyle | 自定义样式 | string | object | {} |
Button Events
| 事件名 | 说明 | 回调参数 |
|---|---|---|
| click | 按钮点击 | - |
| getphonenumber | open-type="getPhoneNumber"时有效 | - |
| getuserinfo | 用户点击该按钮时，会返回获取到的用户信息，从返回参数的detail中获取到的值同uni.getUserInfo | - |
| error | 当使用开放能力时，发生错误的回调 | - |
| opensetting | 在打开授权设置页并关闭后回调 | - |
| launchapp | 打开 APP 成功的回调 | - |
| agreeprivacyauthorization | 用户同意隐私协议事件回调 | - |
Css 变量
组件内部默认使用 css 变量，如需修改，请查看 css 变量使用 文档
| 变量名 | 默认值 | 说明 |
|---|---|---|
| --un-button-text-base-font-size | $text-base | 按钮基础文字大小 |
| --un-button-large-text-size | $text-lg | 按钮大尺寸文字大小 |
| --un-button-small-text-size | $text-sm | 按钮小尺寸文字大小 |
| --un-button-mini-text-size | $text-xs | 按钮迷你尺寸文字大小 |
| --un-button-color-info | $color-info | 信息按钮颜色 |
| --un-button-color-info-light | $color-info-light | 信息按钮亮色 |
| --un-button-color-primary | $color-primary | 主要按钮颜色 |
| --un-button-color-success | $color-success | 成功按钮颜色 |
| --un-button-color-warning | $color-warning | 警告按钮颜色 |
| --un-button-color-error | $color-error | 危险按钮颜色 |
| --un-button-active-opacity | 0.5 | 按钮点击时透明度 |
| --un-button-disabled-opacity | 0.5 | 按钮禁用时透明度 |
| --un-button-circle-radius | $radius-circle | 圆形按钮圆角 |
| --un-button-square-radius | $radius-base | 方形按钮圆角 |
| --un-button-large-height | 50px | 大尺寸按钮高度 |
| --un-button-large-padding | 0 15px | 大尺寸按钮内边距 |
| --un-button-height | 40px | 普通尺寸按钮高度 |
| --un-button-padding | 0 12px | 普通尺寸按钮内边距 |
| --un-button-small-height | 30px | 小尺寸按钮高度 |
| --un-button-small-padding | 0px 8px | 小尺寸按钮内边距 |
| --un-button-mini-height | 22px | 迷你尺寸按钮高度 |
| --un-button-mini-min-width | 50px | 迷你尺寸按钮最小宽度 |
| --un-button-mini-padding | 0px 8px | 迷你尺寸按钮内边距 |
| --un-button-hairline-border-width | 0.5px | 细边框按钮边框宽度 |
| --un-button-icon-margin | 2px | 按钮图标与文字间距 |