.. _button:

:wx_comp:`button`
===========================

.. versionadded:: 1.0.0  低版本需做 :ref:`compatibility` 。

按钮。

+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
|          属性          |    类型     |    默认值    | 必填 |                                                                              说明                                                                              | 最低版本 |
+========================+=============+==============+======+================================================================================================================================================================+==========+
| size                   | string      | default      | 否   | 按钮的大小                                                                                                                                                     | 1.0.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| type                   | string      | default      | 否   | 按钮的样式类型                                                                                                                                                 | 1.0.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| plain                  | boolean     | false        | 否   | 按钮是否镂空，背景色透明                                                                                                                                       | 1.0.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| disabled               | boolean     | false        | 否   | 是否禁用                                                                                                                                                       | 1.0.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| loading                | boolean     | false        | 否   | 名称前是否带 loading 图标                                                                                                                                      | 1.0.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| form-type              | string      |              | 否   | 用于 <form> 组件，点击分别会触发 <form> 组件的 submit/reset 事件                                                                                               | 1.0.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| open-type              | string      |              | 否   | 微信开放能力                                                                                                                                                   | 1.1.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| hover-class            | string      | button-hover | 否   | 指定按钮按下去的样式类。当 hover-class="none" 时，没有点击态效果                                                                                               | 1.0.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| hover-stop-propagation | boolean     | false        | 否   | 指定是否阻止本节点的祖先节点出现点击态                                                                                                                         | 1.5.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| hover-start-time       | number      | 20           | 否   | 按住后多久出现点击态，单位毫秒                                                                                                                                 | 1.0.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| hover-stay-time        | number      | 70           | 否   | 手指松开后点击态保留时间，单位毫秒                                                                                                                             | 1.0.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| lang                   | string      | en           | 否   | 指定返回用户信息的语言，zh_CN 简体中文，zh_TW 繁体中文，en 英文。                                                                                              | 1.3.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| session-from           | string      |              | 否   | 会话来源，open-type="contact"时有效                                                                                                                            | 1.4.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| send-message-title     | string      | 当前标题     | 否   | 会话内消息卡片标题，open-type="contact"时有效                                                                                                                  | 1.5.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| send-message-path      | string      | 当前分享路径 | 否   | 会话内消息卡片点击跳转小程序路径，open-type="contact"时有效                                                                                                    | 1.5.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| send-message-img       | string      | 截图         | 否   | 会话内消息卡片图片，open-type="contact"时有效                                                                                                                  | 1.5.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| app-parameter          | string      |              | 否   | 打开 APP 时，向 APP 传递的参数，open-type=launchApp时有效                                                                                                      | 1.9.5    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| show-message-card      | boolean     | false        | 否   | 是否显示会话内消息卡片，设置此参数为 true，用户进入客服会话会在右下角显示"可能要发送的小程序"提示，用户点击后可以快速发送小程序消息，open-type="contact"时有效 | 1.5.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| bindgetuserinfo        | eventhandle |              | 否   | 用户点击该按钮时，会返回获取到的用户信息，回调的detail数据与wx.getUserInfo返回的一致，open-type="getUserInfo"时有效                                            | 1.3.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| bindcontact            | eventhandle |              | 否   | 客服消息回调，open-type="contact"时有效                                                                                                                        | 1.5.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| bindgetphonenumber     | eventhandle |              | 否   | 获取用户手机号回调，open-type=getPhoneNumber时有效                                                                                                             | 1.2.0    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| binderror              | eventhandle |              | 否   | 当使用开放能力时，发生错误的回调，open-type=launchApp时有效                                                                                                    | 1.9.5    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| bindopensetting        | eventhandle |              | 否   | 在打开授权设置页后回调，open-type=openSetting时有效                                                                                                            | 2.0.7    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+
| bindlaunchapp          | eventhandle |              | 否   | 打开 APP 成功的回调，open-type=launchApp时有效                                                                                                                 | 2.4.4    |
+------------------------+-------------+--------------+------+----------------------------------------------------------------------------------------------------------------------------------------------------------------+----------+

size 的合法值

+---------+----------+
|   值    |   说明   |
+=========+==========+
| default | 默认大小 |
+---------+----------+
| mini    | 小尺寸   |
+---------+----------+

type 的合法值

+---------+------+
|   值    | 说明 |
+=========+======+
| primary | 绿色 |
+---------+------+
| default | 白色 |
+---------+------+
| warn    | 红色 |
+---------+------+

form-type 的合法值

+--------+----------+
|   值   |   说明   |
+========+==========+
| submit | 提交表单 |
+--------+----------+
| reset  | 重置表单 |
+--------+----------+

open-type 的合法值

+----------------+----------------------------------------------------------+----------+
|       值       |                           说明                           | 最低版本 |
+================+==========================================================+==========+
| contact        | 打开客服会话，如果用户在会话中点击消息卡片后返回小程序， |          |
|                | 可以从 bindcontact 回调中获得具体信息，具体说明          | 1.1.0    |
+----------------+----------------------------------------------------------+----------+
| share          | 触发用户转发，使用前建议先阅读使用指引                   | 1.2.0    |
+----------------+----------------------------------------------------------+----------+
| getPhoneNumber | 获取用户手机号，可以从bindgetphonenumber                 |          |
|                | 回调中获取到用户信息，具体说明                           | 1.2.0    |
+----------------+----------------------------------------------------------+----------+
| getUserInfo    | 获取用户信息，可以从bindgetuserinfo                      |          |
|                | 回调中获取到用户信息                                     | 1.3.0    |
+----------------+----------------------------------------------------------+----------+
| launchApp      | 打开APP，可以通过app-parameter                           |          |
|                | 属性设定向APP传的参数具体说明                            | 1.9.5    |
+----------------+----------------------------------------------------------+----------+
| openSetting    | 打开授权设置页                                           | 2.0.7    |
+----------------+----------------------------------------------------------+----------+
| feedback       | 打开“意见反馈”页面，用户可提交反馈内容并上传日志，       |          |
|                | 开发者可以登录小程序管理后台后进入                       |          |
|                | 左侧菜单“客服反馈”页面获取到反馈内容                     | 2.1.0    |
+----------------+----------------------------------------------------------+----------+

lang 的合法值

=====  ========
 值      说明
=====  ========
en     英文
zh_CN  简体中文
zh_TW  繁体中文
=====  ========

.. tip:: button-hover 默认为{background-color: rgba(0, 0, 0, 0.1); opacity: 0.7;}

.. tip:: bindgetphonenumber 从1.2.0  但是在1.5.3以下版本中无法使用wx.canIUse进行检测，建议使用基础库版本进行判断。

.. tip:: 在bindgetphonenumber 等返回加密信息的回调中调用 wx.login 登录，可能会刷新登录态。此时服务器使用 code 换取的 sessionKey 不是加密时使用的 sessionKey，导致解密失败。建议开发者提前进行 login；或者在回调中先使用 checkSession 进行登录态检查，避免 login 刷新登录态。

.. tip:: 从 2.1.0 起，button 可作为原生组件的子节点嵌入，以便在原生组件上使用 open-type 的能力。

.. tip:: 目前设置了 form-type 的 button 只会对当前组件中的 form 有效。因而，将 button 封装在自定义组件中，而 from 在自定义组件外，将会使这个 button 的 form-type 失效。

示例代码

:download:`在开发者工具中预览效果 <https://developers.weixin.qq.com/s/ZHrWZqm66cZy>`

.. code:: css

  .button-hover {
    background-color: red;
  }
  .other-button-hover {
    background-color: blue;
  }

.. code:: html

  <button
    type="default"
    size="{{defaultSize}}"
    loading="{{loading}}"
    plain="{{plain}}"
    disabled="{{disabled}}"
    bindtap="default"
    hover-class="other-button-hover"
  >
    default
  </button>
  <button
    type="primary"
    size="{{primarySize}}"
    loading="{{loading}}"
    plain="{{plain}}"
    disabled="{{disabled}}"
    bindtap="primary"
  >
    primary
  </button>
  <button
    type="warn"
    size="{{warnSize}}"
    loading="{{loading}}"
    plain="{{plain}}"
    disabled="{{disabled}}"
    bindtap="warn"
  >
    warn
  </button>
  <button bindtap="setDisabled">点击设置以上按钮disabled属性</button>
  <button bindtap="setPlain">点击设置以上按钮plain属性</button>
  <button bindtap="setLoading">点击设置以上按钮loading属性</button>
  <button open-type="contact">进入客服会话</button>
  <button open-type="getUserInfo" lang="zh_CN" bindgetuserinfo="onGotUserInfo">
    获取用户信息
  </button>
  <button open-type="openSetting">打开授权设置页</button>

.. code:: js

  const types = ['default', 'primary', 'warn']
  const pageObject = {
    data: {
      defaultSize: 'default',
      primarySize: 'default',
      warnSize: 'default',
      disabled: false,
      plain: false,
      loading: false
    },
    setDisabled(e) {
      this.setData({
        disabled: !this.data.disabled
      })
    },
    setPlain(e) {
      this.setData({
        plain: !this.data.plain
      })
    },
    setLoading(e) {
      this.setData({
        loading: !this.data.loading
      })
    },
    onGotUserInfo(e) {
      console.log(e.detail.errMsg)
      console.log(e.detail.userInfo)
      console.log(e.detail.rawData)
    },
  }

  for (let i = 0; i < types.length; ++i) {
    (function (type) {
      pageObject[type] = function (e) {
        const key = type + 'Size'
        const changedData = {}
        changedData[key] =
          this.data[key] === 'default' ? 'mini' : 'default'
        this.setData(changedData)
      }
    }(types[i]))
  }

  Page(pageObject)