Skip to content

Button 按钮 ​

8:14

组件概况 ​

Button 按钮组件是用户交互中最常用的基础组件之一,用于触发特定操作或行为。该组件支持多种类型(主要、成功、信息、警告、危险、文本、图标)、三种尺寸(小、中、大),以及幽灵、圆角、细边框、块状等丰富的样式变体。同时提供加载状态、图标集成和完整的小程序开放能力支持,适用于各种业务场景下的用户交互需求。

核心功能描述 ​

  • 多种按钮类型:支持 primary(主要)、success(成功)、info(信息)、warning(警告)、error(危险)、text(文字)、icon(图标)共 7 种类型
  • 三种按钮尺寸:支持 small(28px 高,12px 字号)、medium(35px 高,14px 字号)、large(42px 高,16px 字号)
  • 幽灵按钮:通过 plain 属性切换为透明背景、带边框的幽灵样式
  • 细边框:通过 hairline 属性实现 0.5px 的细边框效果,提升视觉精致度
  • 圆角控制:默认 round 为 true,显示圆角按钮;设置为 false 显示小圆角按钮
  • 块状按钮:通过 block 属性使按钮宽度占满父容器,适用于底部操作栏等场景
  • 加载状态:通过 loading 属性展示加载动画,加载期间按钮自动禁用点击
  • 图标支持:通过 icon 属性集成图标,支持自定义类名前缀 classPrefix
  • 禁用状态:通过 disabled 属性禁用按钮,禁用状态下点击事件不会触发
  • 小程序开放能力:通过 openType 属性支持微信小程序的多种开放能力,如获取用户信息、联系客服、获取手机号等
  • 暗色模式支持:内置 dark 主题样式,自动跟随系统主题切换

适用业务场景 ​

  • 主要操作:表单提交、确认操作等核心交互,使用 primary 类型按钮
  • 辅助操作:取消、返回等次要操作,使用 info 类型或 plain 幽灵按钮
  • 成功/反馈操作:操作成功后的确认按钮,使用 success 类型
  • 警告/危险操作:删除、清除等需要用户谨慎操作的行为,使用 warning 或 error 类型
  • 文字链接式操作:列表内的展开、查看更多等操作,使用 text 类型按钮
  • 纯图标操作:工具栏内的功能按钮,使用 icon 类型按钮
  • 加载反馈:提交表单后显示加载状态,防止重复提交,使用 loading 属性
  • 小程序场景:获取用户信息、联系客服、获取手机号、打开 APP 等微信小程序特有场景
  • 底部固定操作:表单底部、弹窗底部等需要宽度占满的操作区域,使用 block 属性

API ​

Props ​

属性名称类型默认值是否必填说明
type'primary' | 'success' | 'info' | 'warning' | 'error' | 'default' | 'text' | 'icon''primary'否按钮类型
size'small' | 'medium' | 'large''medium'否按钮尺寸
plainbooleanfalse否是否为幽灵按钮,透明背景带边框
roundbooleantrue否是否为圆角按钮
hairlinebooleanfalse否是否显示 0.5px 细边框,仅幽灵按钮生效
blockbooleanfalse否是否为块状按钮,宽度 100%
disabledbooleanfalse否是否禁用按钮
loadingbooleanfalse否是否显示加载状态
loadingColorstring-否加载图标颜色,默认根据按钮类型自动匹配
iconstring-否图标类名
classPrefixstring'wd-icon'否图标类名前缀
openTypeButtonOpenType-否微信小程序开放能力类型,详见下方说明
hoverStopPropagationbooleanfalse否是否阻止本节点的祖先节点出现点击态
lang'zh_CN' | 'zh_TW' | 'en'-否指定返回用户信息的语言
sessionFromstring-否会话来源,open-type="contact" 时有效
sendMessageTitlestring-否会话内消息卡片标题,open-type="contact" 时有效
sendMessagePathstring-否会话内消息卡片点击跳转路径,open-type="contact" 时有效
sendMessageImgstring-否会话内消息卡片图片,open-type="contact" 时有效
appParameterstring-否打开 APP 时传递的参数,open-type="launchApp" 时有效
showMessageCardbooleanfalse否是否显示会话内消息卡片,open-type="contact" 时有效
buttonIdstring-否按钮唯一标识,可用于设置隐私同意授权按钮的 id
scope'phoneNumber' | 'userInfo'-否支付宝小程序授权作用域,open-type="getAuthorize" 时有效
customStylestring''否自定义根节点样式
customClassstring''否自定义根节点类名

openType 可选值 ​

ButtonOpenType 类型支持以下微信小程序开放能力:

值说明
feedback打开小程序意见反馈面板
share触发用户转发
getUserInfo获取用户信息
contact打开客服会话
getPhoneNumber获取用户手机号
launchApp打开 APP
openSetting打开授权设置页
chooseAvatar选择用户头像
getAuthorize支付宝小程序授权
lifestyle支付宝小程序生活号授权
contactShare分享到微信好友
openGroupProfile展示群信息
openGuildProfile打开群设置页
openPublicProfile打开公众号主页
shareMessageToFriend转发消息给好友
addFriend添加好友
addColorSign添加彩色签名
addGroupApp添加到群应用
addToFavorites加入收藏
chooseAddress选择收货地址
chooseInvoiceTitle选择发票抬头
login用户登录
subscribe订阅消息
favorite收藏
watchLater稍后再看
openProfile打开个人页
agreePrivacyAuthorization同意隐私授权

Events ​

事件名称回调参数说明
clickevent按钮点击事件,禁用和加载状态下不会触发
getuserinfoevent.detail获取用户信息回调,open-type="getUserInfo" 时有效
contactevent.detail客服消息回调,open-type="contact" 时有效
getphonenumberevent.detail获取用户手机号回调,open-type="getPhoneNumber" 时有效
getrealtimephonenumberevent.detail获取用户实时手机号回调
errorevent.detail使用开放能力发生错误时的回调
launchappevent.detail打开 APP 成功回调,open-type="launchApp" 时有效
opensettingevent.detail打开授权设置页回调,open-type="openSetting" 时有效
chooseavatarevent.detail选择头像回调,open-type="chooseAvatar" 时有效
agreeprivacyauthorizationevent.detail同意隐私授权回调

Methods ​

组件不对外暴露任何方法。

Slots ​

插槽名称作用域参数使用场景
default-按钮内容,可放置文字、图标或其他组件

使用示例 ​

示例 1:基本用法 ​

展示不同类型的按钮以及圆角/方角的切换效果。

vue
<template>
  <view>
    <!-- 默认圆角按钮 -->
    <wd-button>主要按钮</wd-button>
    <wd-button type="success">成功按钮</wd-button>
    <wd-button type="info">信息按钮</wd-button>
    <wd-button type="warning">警告按钮</wd-button>
    <wd-button type="error">危险按钮</wd-button>

    <!-- 方角按钮 -->
    <wd-button :round="false">主要按钮</wd-button>
    <wd-button :round="false" type="success">成功按钮</wd-button>
    <wd-button :round="false" type="info">信息按钮</wd-button>
    <wd-button :round="false" type="warning">警告按钮</wd-button>
    <wd-button :round="false" type="error">危险按钮</wd-button>
  </view>
</template>
<script lang="ts" setup>
</script>

round 属性默认为 true,显示大圆角按钮;设置为 false 时显示小圆角按钮。按钮类型通过 type 属性控制,默认为 primary 主要按钮。

示例 2:幽灵按钮与细边框 ​

展示幽灵按钮效果,以及叠加细边框的精致样式。

vue
<template>
  <view>
    <!-- 幽灵按钮 -->
    <wd-button plain>主要按钮</wd-button>
    <wd-button type="success" plain>成功按钮</wd-button>
    <wd-button type="info" plain>信息按钮</wd-button>
    <wd-button type="warning" plain>警告按钮</wd-button>
    <wd-button type="error" plain>危险按钮</wd-button>

    <!-- 细边框幽灵按钮 -->
    <wd-button plain hairline>主要按钮</wd-button>
    <wd-button type="success" plain hairline>成功按钮</wd-button>
    <wd-button type="info" plain hairline>信息按钮</wd-button>
    <wd-button type="warning" plain hairline>警告按钮</wd-button>
    <wd-button type="error" plain hairline>危险按钮</wd-button>
  </view>
</template>
<script lang="ts" setup>
</script>

通过 plain 属性将按钮切换为幽灵样式(透明背景,边框颜色与按钮类型一致)。在 plain 基础上添加 hairline 属性,可显示 0.5px 的细边框效果。

示例 3:禁用状态 ​

展示不同类型按钮的禁用效果。

vue
<template>
  <view>
    <wd-button disabled>主要按钮</wd-button>
    <wd-button type="success" disabled>成功按钮</wd-button>
    <wd-button type="info" disabled>信息按钮</wd-button>
    <wd-button type="warning" disabled>警告按钮</wd-button>
    <wd-button type="error" disabled>危险按钮</wd-button>
    <wd-button :round="false" disabled>主要按钮</wd-button>
  </view>
</template>
<script lang="ts" setup>
</script>

通过 disabled 属性禁用按钮,禁用状态下按钮透明度降低至 0.6,且点击事件不会触发。

示例 4:按钮尺寸 ​

展示三种尺寸的按钮效果。

vue
<template>
  <view>
    <wd-button size="small">小型按钮</wd-button>
    <wd-button size="medium">普通按钮</wd-button>
    <wd-button size="large">大型按钮</wd-button>
  </view>
</template>
<script lang="ts" setup>
</script>

各尺寸的规格如下:

尺寸高度内边距字号圆角Loading 图标大小
small28px0 12px12px3px14px
medium35px0 15px14px4px18px
large42px0 30px16px5px24px

示例 5:加载状态 ​

展示按钮的加载状态效果。

vue
<template>
  <view>
    <wd-button loading>加载中</wd-button>
    <wd-button type="success" loading>加载中</wd-button>
    <wd-button type="warning" loading>加载中</wd-button>
    <wd-button type="error" loading>加载中</wd-button>
    <wd-button type="info" plain loading>加载中</wd-button>
    <wd-button :round="false" loading>加载中</wd-button>
  </view>
</template>
<script lang="ts" setup>
</script>

通过 loading 属性展示加载动画,加载期间按钮自动禁用点击交互。加载图标颜色会根据按钮类型自动匹配(未设置 loadingColor 时):primary 为 #4D80F0,success 为 #34d19d,info/default 为 #333,warning 为 #f0883a,error 为 #fa4350。

示例 6:文字按钮与图标按钮 ​

展示文字按钮和纯图标按钮的使用方式。

vue
<template>
  <view>
    <!-- 文字按钮 -->
    <wd-button type="text">按钮</wd-button>
    <wd-button type="text" disabled>按钮</wd-button>

    <!-- 图标按钮 -->
    <wd-button type="icon" plain icon="delete"></wd-button>
    <wd-button type="icon" icon="delete"></wd-button>
    <wd-button :round="false" type="icon" plain icon="add" disabled></wd-button>
    <wd-button type="icon" icon="add" disabled></wd-button>
  </view>
</template>
<script lang="ts" setup>
</script>

type="text" 创建文字按钮样式(无背景、无边框,hover 时透明度变为 0.7)。type="icon" 创建纯图标按钮,默认尺寸为 40px,支持 plain 属性添加边框背景。

示例 7:带图标的按钮 ​

在按钮中集成图标,增强视觉识别性。

vue
<template>
  <view>
    <wd-button icon="download" size="small">下载</wd-button>
    <wd-button icon="download">下载</wd-button>
    <wd-button icon="download" size="large">下载</wd-button>
    <wd-button icon="setting" size="small">设置</wd-button>
    <wd-button icon="setting">设置</wd-button>
    <wd-button icon="setting" size="large">设置</wd-button>
  </view>
</template>
<script lang="ts" setup>
</script>

通过 icon 属性设置图标类名,图标默认显示在按钮文字左侧,间距为 6px,图标大小为 18px。使用 classPrefix 属性可自定义图标类名前缀,默认为 wd-icon。

示例 8:块状按钮 ​

展示宽度占满父容器的块状按钮。

vue
<template>
  <view>
    <wd-button block size="large">主要按钮</wd-button>
    <wd-button type="success" block size="large">成功按钮</wd-button>
    <wd-button type="info" block size="large">信息按钮</wd-button>
    <wd-button type="warning" block size="large">警告按钮</wd-button>
    <wd-button type="error" block size="large">危险按钮</wd-button>
  </view>
</template>
<script lang="ts" setup>
</script>

通过 block 属性使按钮以块级元素渲染,宽度占满 100% 父容器,适用于表单底部操作栏、弹窗底部按钮等场景。

示例 9:常用组合 ​

展示表单提交场景中常见的主次操作按钮组合。

vue
<template>
  <view>
    <!-- 禁用状态 -->
    <wd-button disabled>主操作</wd-button>
    <wd-button size="small" disabled>主操作</wd-button>

    <!-- 正常状态 -->
    <wd-button>主操作</wd-button>
    <wd-button size="small">主操作</wd-button>

    <!-- 次要操作 -->
    <wd-button type="info" disabled>次操作</wd-button>
    <wd-button type="info" size="small" disabled>次操作</wd-button>
    <wd-button type="info">次操作</wd-button>
    <wd-button type="info" size="small">次操作</wd-button>

    <!-- 幽灵按钮 -->
    <wd-button plain disabled>幽灵按钮</wd-button>
    <wd-button size="small" plain disabled>幽灵按钮</wd-button>
    <wd-button plain>幽灵按钮</wd-button>
    <wd-button size="small" plain>幽灵按钮</wd-button>

    <!-- 次要幽灵按钮 -->
    <wd-button type="info" plain disabled>次操作</wd-button>
    <wd-button type="info" size="small" plain disabled>次操作</wd-button>
    <wd-button type="info" plain>次操作</wd-button>
    <wd-button type="info" size="small" plain>次操作</wd-button>
  </view>
</template>
<script lang="ts" setup>
</script>

在表单提交等场景中,通常主操作用 primary 默认类型(蓝色填充),次操作用 info 类型或 plain 幽灵按钮,形成视觉层级区分。

示例 10:小程序开放能力 ​

展示微信小程序常见开放能力的用法。

vue
<template>
  <view>
    <!-- 获取用户信息 -->
    <wd-button open-type="getUserInfo" @getuserinfo="handleGetuserinfo">
      获取用户信息
    </wd-button>

    <!-- 获取手机号 -->
    <wd-button open-type="getPhoneNumber" @getphonenumber="handleGetPhone">
      获取手机号
    </wd-button>

    <!-- 打开客服 -->
    <wd-button
      open-type="contact"
      session-from="weapp"
      send-message-title="欢迎咨询"
      send-message-path="/pages/index/index"
      send-message-img="/static/logo.png"
      :show-message-card="true"
      @contact="handleContact"
    >
      联系客服
    </wd-button>

    <!-- 打开 APP -->
    <wd-button open-type="launchApp" app-parameter="wechat" @launchapp="handleLaunchApp">
      打开 APP
    </wd-button>

    <!-- 打开授权设置 -->
    <wd-button open-type="openSetting" @opensetting="handleOpenSetting">
      授权设置
    </wd-button>

    <!-- 选择头像 -->
    <wd-button open-type="chooseAvatar" @chooseavatar="handleChooseAvatar">
      选择头像
    </wd-button>
  </view>
</template>
<script lang="ts" setup>
  function handleGetuserinfo(event: any) {
    console.log('用户信息', event)
  }

  function handleGetPhone(event: any) {
    console.log('手机号', event)
  }

  function handleContact(event: any) {
    console.log('客服消息', event)
  }

  function handleLaunchApp(event: any) {
    console.log('打开APP', event)
  }

  function handleOpenSetting(event: any) {
    console.log('授权设置', event)
  }

  function handleChooseAvatar(event: any) {
    console.log('选择头像', event)
  }
</script>

使用 openType 属性触发微信小程序的开放能力,对应的事件通过 @事件名 监听。注意:当按钮处于 disabled 或 loading 状态时,openType 不会生效。

注意事项 ​

  1. 禁用与加载状态自动阻止交互:当 disabled 或 loading 为 true 时,按钮的点击事件不会触发,同时 openType 开放能力也不会生效
  2. hairline 仅对幽灵按钮生效:hairline 属性需要配合 plain 属性使用,非幽灵按钮状态下设置 hairline 不会产生细边框效果
  3. 加载图标颜色自动匹配:未设置 loadingColor 时,加载图标颜色会根据 type 自动匹配对应主题色;幽灵按钮的加载图标颜色会与实心按钮相反(使用白色)
  4. icon 类型按钮尺寸固定:type="icon" 的按钮默认尺寸为 40px,内边距为 0,且默认不显示边框伪元素
  5. text 类型按钮无背景:type="text" 的按钮默认无背景、无边框,hover/active 时通过透明度变化提供视觉反馈,而非背景色变化
  6. 圆角模式下的特殊处理:当 round 为 true 且 type 为 icon 时,按钮会呈现圆形效果;type 为 text 时,圆角设置为 0
  7. openType 在禁用时不生效:当按钮 disabled 或 loading 为 true 时,openType 属性会被设置为 undefined,不会触发任何小程序开放能力
  8. customStyle 与 customClass 的使用:通过 customStyle 和 customClass 可以进行自定义样式扩展,例如添加 Material Design 风格的 box-shadow 阴影效果
  9. 暗色模式自动适配:组件已内置暗色主题样式,包括 info、text、icon 等类型在暗色模式下的背景和颜色都会自动调整,无需额外配置

📖 Released under the MIT License