企业官网建设流程全解析

• 前端
• UI组件
• 小程序
• 设计系统
• 移动开发

TDesign 的 Button 按钮组件用于开启一个闭环的操作任务，例如“删除”对象、“购买”商品等，是表单提交、权限授权、客服会话等场景中最常用的基础组件之一。本文以 Button 按钮官方文档 为主体，结合本仓库 uniapp-components 版源码 与 示例代码，系统讲解 TDesign Button 在 Uniapp 项目中的引入方式、组件类型、状态与样式、完整 Props 与 Events API、插槽与外部样式类，以及基于 CSS Variables 的主题定制方法。读完本文，你将能够独立完成按钮组件的选型、配置、事件处理与视觉定制。

引入方式

推荐使用 easycom 模式引入组件，配置后无需手动import即可直接在模板中使用<t-button />。详细配置方式可参考 快速开始（本仓库中各组件文档均指向该快速开始指引）。

如需手动引入，可按如下方式导入：

import TButton from '@tdesign/uniapp/button/button.vue';

引入后在页面或组件的components中注册即可使用。示例代码（base/index.vue）展示了标准的引入与使用流程：

<script> import TButton from '@tdesign/uniapp/button/button.vue'; export default { components: { TButton, }, // ... }; </script>

组件类型

按钮组件提供了基础按钮、图标按钮、幽灵按钮、组合按钮、通栏按钮五种常见形态，覆盖从常规操作到强调型操作的大部分业务场景。

基础按钮

基础按钮是使用频率最高的形态，通过theme区分视觉强调程度，通过variant切换填充/描边/虚框/文字等表现形式。参考 基础按钮示例：

<t-button theme="primary" size="large"> 填充按钮 </t-button> <t-button theme="light" size="large"> 填充按钮 </t-button> <t-button size="large"> 填充按钮 </t-button> <!-- 同一主题下的不同 variant --> <t-button theme="primary" size="large" variant="outline"> 描边按钮 </t-button> <t-button theme="primary" size="large" variant="dashed"> 虚框按钮 </t-button> <t-button theme="primary" size="large" variant="text"> 文字按钮 </t-button>

其中variant可选值包括base（基础填充）、outline（线框）、dashed（虚线）、text（文字）四种，默认值为base。

图标按钮

图标按钮在按钮内渲染t-icon图标，图标名称通过icon属性传入。参考 图标按钮示例：

<t-button theme="primary" icon="app" content="填充按钮" size="large" /> <t-button theme="primary" icon="search" shape="square" size="large" aria-label="搜索" />

icon属性支持两种取值：

• 字符串：直接表示图标名称，如icon="search"；
• 对象：透传至t-icon组件，可携带name、size、color、prefix、style等配置。

从 组件源码 看，icon值会通过calcIcon(value, '')被解析为内部innerIcon对象，并据此渲染<t-icon>子组件；calcIcon的实现在 common/utils.js：当传入字符串时直接作为图标名，传入对象时原样透传，二者都不满足时返回null不渲染图标。

图标尺寸会跟随按钮尺寸自动适配：extra-small与small为36rpx，medium为40rpx，large为48rpx（见 button.vue 中的映射）。图标按钮在shape="circle"等场景下还常配合aria-label提供无障碍描述。

幽灵按钮

幽灵按钮为镂空（透明背景）样式，常用于深色背景或 Banner 场景。参考 幽灵按钮示例，该示例背景为深色（#181818）：

<t-button theme="primary" ghost size="large"> 幽灵按钮 </t-button> <t-button theme="danger" ghost size="large"> 幽灵按钮 </t-button> <t-button ghost size="large"> 幽灵按钮 </t-button>

ghost默认值为false，开启后背景透明、边框与文字使用对应主题色。在样式实现（button.less）中，幽灵按钮的优先级高于theme，固定透明背景，并分别为default、primary、danger提供了独立的边框色与 hover 色变量（如--td-button-ghost-primary-color、--td-button-ghost-danger-color）。

组合按钮

组合按钮通过多个block按钮横向拼接实现，常用于“上一步/下一步”等步骤型操作。参考 组合按钮示例：

<t-button theme="light" block size="large" :custom-style="'flex: 1; margin-right: 16px;'"> 填充按钮 </t-button> <t-button theme="primary" block size="large" :custom-style="'flex: 1;'"> 填充按钮 </t-button>

要点：

• 每个子按钮都设置block使宽度撑满父容器，再通过flex: 1均分宽度；
• 使用margin-right制造按钮间距；
• 示例中还通过canUseVirtualHost()判断环境是否支持虚拟宿主，以决定样式应写在custom-style还是原生style上。

通栏按钮

通栏按钮即宽度为 100% 的块级按钮，仅需设置block属性。参考 通栏按钮示例：

<t-button theme="primary" size="large" block> 填充按钮 </t-button>

样式层面对应 button.less 中的&--block { display: flex; width: 100%; }规则。

组件状态

按钮禁用态

通过disabled属性开启禁用态，禁用后按钮不可点击、视觉变为灰色并应用禁用配色。参考 禁用态示例：

<t-button theme="primary" size="large" disabled> 填充按钮 </t-button> <t-button theme="primary" size="large" variant="outline" disabled> 描边按钮 </t-button> <t-button theme="primary" size="large" variant="text" disabled> 文字按钮 </t-button>

关于disabled需要了解以下几点：

• 默认值为undefined，与表单组件配合时存在优先级规则：Button.disabled > Form.disabled（见 props.ts 的注释）；
• 禁用或加载状态下，open-type、form-type都会被置空，hover-class点击态也不会生效（见 button.vue）；
• handleTap中也会显式拦截：if (this.disabled || this.loading) return;（见 button.vue），确保禁用态不会派发click事件；
• 每个主题（default/primary/light/danger）及每种variant都通过 CSS 变量定义了独立的禁用配色，例如--td-button-primary-disabled-bg、--td-button-danger-disabled-color等。

加载状态

loading属性可将按钮切换为加载状态，此时按钮内部渲染t-loading组件，且同样拦截点击事件。参考 图标按钮示例 中的用法：

<t-button theme="primary" size="large" loading> 加载中 </t-button>

loading相关行为：

• 加载状态下open-type、form-type同样会被置空；
• loading-props属性可透传 Loading 组件全部属性，其 TS 类型为LoadingProps（见 type.ts），可配置delay、duration、indicator、size、theme、text等（见 button.vue）；
• 加载指示器默认尺寸为40rpx、主题为circular；
• 从 Skyline 渲染示例（_example/skyline/button.vue）可以看到，在 Skyline 渲染下可自定义<t-loading theme="spinner">展示“加载中...”文案，作为loading内置加载态的替代方案。

组件样式

按钮尺寸

size控制按钮尺寸，可选extra-small/small/medium/large，默认medium。各尺寸对应的高度与字号如下表（数据来自 button.less）：

| 尺寸 | 高度 | 水平内边距 | 图标尺寸 | 字号 | | -- | -- | -- | -- | -- | | extra-small | 56rpx | 16rpx | 36rpx | 中等（@font-mark-medium） | | small | 64rpx | 24rpx | 36rpx | 中等（@font-mark-medium） | | medium | 80rpx | 32rpx | 40rpx | 大（@font-mark-large） | | large | 96rpx | 40rpx | 48rpx | 大（@font-mark-large） |

参考 尺寸示例：

<t-button theme="primary" size="large"> 按钮48 </t-button> <t-button theme="primary"> 按钮40 </t-button> <t-button theme="primary" size="small"> 按钮32 </t-button> <t-button theme="primary" size="extra-small"> 按钮28 </t-button>

示例中“按钮48/按钮40/按钮32/按钮28”即对应各尺寸的高度（rpx）。

按钮形状

shape控制按钮形状，可选rectangle（长方形，默认）/square（正方形）/round（圆角长方形）/circle（圆形）。参考 形状示例：

<t-button theme="primary" size="large"> 填充按钮 </t-button> <t-button theme="primary" size="large" icon="search" shape="square" aria-label="搜索" /> <t-button theme="primary" size="large" shape="round"> 填充按钮 </t-button> <t-button theme="primary" size="large" icon="search" shape="circle" aria-label="搜索" />

各形状的样式实现（button.less）：

• round：圆角半径取当前尺寸高度的一半（calc(@button-*-height / 2)），且会同步调整::after伪元素圆角；
• square：padding: 0，宽高相等，宽度取当前尺寸高度值；
• circle：border-radius: 50%，宽高相等，适合纯图标按钮，此时务必配合aria-label提升无障碍可访问性。

按钮主题

theme控制按钮主题色，可选default/primary/danger/light，默认default，其中primary为品牌色、danger为危险色。参考 主题示例，每个主题均可与variant自由组合：

<!-- default --> <t-button size="large"> 填充按钮 </t-button> <t-button size="large" variant="outline"> 描边按钮 </t-button> <t-button size="large" variant="text"> 文字按钮 </t-button> <!-- primary --> <t-button size="large" theme="primary"> 填充按钮 </t-button> <t-button size="large" theme="primary" variant="outline"> 描边按钮 </t-button> <t-button size="large" theme="primary" variant="text"> 文字按钮 </t-button> <!-- danger --> <t-button size="large" theme="danger"> 填充按钮 </t-button> <t-button size="large" theme="danger" variant="outline"> 描边按钮 </t-button> <t-button size="large" theme="danger" variant="text"> 文字按钮 </t-button> <!-- light --> <t-button size="large" theme="light"> 填充按钮 </t-button> <t-button size="large" theme="light" variant="outline"> 描边按钮 </t-button> <t-button size="large" theme="light" variant="text"> 文字按钮 </t-button>

类名生成逻辑见 button.vue：setClass会根据variant、theme、shape、size以及block/disabled/ghost布尔值拼装出形如t-button--primary t-button--base t-button--rectangle t-button--size-large的类名；而 button.less 中的button-thememixin 为每个主题统一生成默认色、激活态（hover）色与禁用态配色规则。

API 详解

Button Props

组件全部属性及其说明如下（默认值与类型均以 props.ts 与 type.ts 为准）：

| 名称 | 类型 | 默认值 | 说明 | 必传 | | -- | -- | -- | -- | -- | | custom-style | Object | - | 自定义样式 | N | | activity-type | Number | - | 卡片 id。open-type设置为liveActivity时使用，可设置notify_type参数；用户点击按钮后可通过createliveactivity事件回调获取code| N | | app-parameter | String | '' | 打开 APP 时向 APP 传递的参数，open-type=launchApp时有效 | N | | block | Boolean | false | 是否为块级元素（宽度 100%） | N | | content | String | - | 按钮内容 | N | | custom-dataset | String / Number / Boolean / Object / Array | {} | 自定义 dataset，可通过event.currentTarget.dataset.custom获取 | N | | disabled | Boolean | undefined | 禁用状态。优先级：Button.disabled > Form.disabled | N | | entrance-path | String | '' | 从消息小程序入口打开小程序的路径，默认为聊天工具启动路径 | N | | ghost | Boolean | false | 是否为幽灵按钮（镂空按钮） | N | | hover-class | String | '' | 指定按钮按下去的样式类，按钮不为加载或禁用状态时有效；当hover-class="none"时没有点击态效果 | N | | hover-start-time | Number | 20 | 按住后多久出现点击态，单位毫秒 | N | | hover-stay-time | Number | 70 | 手指松开后点击态保留时间，单位毫秒 | N | | hover-stop-propagation | Boolean | false | 是否阻止本节点的祖先节点出现点击态 | N | | icon | String / Object | - | 图标名称；字符串表示图标名称，Object 表示透传至icon组件 | N | | lang | String | - | 指定返回用户信息的语言：en英文 /zh_CN简体中文 /zh_TW繁体中文 | N | | loading | Boolean | false | 是否显示为加载状态 | N | | loading-props | Object | {} | 透传 Loading 组件全部属性，TS 类型为LoadingProps| N | | need-show-entrance | Boolean | true | 转发的文本消息是否要带小程序入口 | N | | open-type | String | - | 微信开放能力，可选contact/share/getPhoneNumber/getUserInfo/launchApp/openSetting/feedback/chooseAvatar/agreePrivacyAuthorization| N | | phone-number-no-quota-toast | Boolean | true | 原生按钮属性，手机号快速验证或实时验证额度用尽时是否展示“暂时无法使用”提示，open-type="getPhoneNumber"或getRealtimePhoneNumber时有效 | N | | send-message-img | String | 截图 | 会话内消息卡片图片，open-type="contact"时有效 | N | | send-message-path | String | 当前分享路径 | 会话内消息卡片点击跳转小程序路径，open-type="contact"时有效 | N | | send-message-title | String | 当前标题 | 会话内消息卡片标题，open-type="contact"时有效 | N | | session-from | String | '' | 会话来源，open-type="contact"时有效 | N | | shape | String | rectangle | 按钮形状，可选rectangle/square/round/circle| N | | show-message-card | Boolean | false | 是否显示会话内消息卡片，open-type="contact"时有效 | N | | size | String | medium | 组件尺寸，可选extra-small/small/medium/large| N | | t-id | String | '' | 按钮标签 id | N | | theme | String | default | 组件风格，可选default/primary/danger/light| N | | type | String | - | 同小程序的 formType，可选submit/reset| N | | variant | String | base | 按钮形式，可选base/outline/dashed/text| N |

值得注意的实现细节：

• 多项枚举属性（lang、open-type、shape、size、theme、type、variant）在 props.ts 中都带有validator校验函数，传入非法值时会被拦截；
• icon、size、theme、variant、block、disabled、loading、shape、ghost均被watch监听并触发setClass重建类名（见 button.vue），因此动态切换这些属性会实时反映到样式上；
• 按钮根元素会通过:data-custom注入customDataset，事件回调中可经由event.currentTarget.dataset.custom取出。

open-type 微信开放能力详解

open-type对接微信原生按钮的开放能力，各取值含义如下（详见 props.ts）：

• contact：打开客服会话；用户在会话中点击消息卡片返回小程序时，可从bindcontact回调获取信息（鸿蒙 OS 暂不支持）；
• liveActivity：通过前端获取新的一次性订阅消息下发机制使用的code，需要配合activity-type使用；
• share：触发用户转发；
• getPhoneNumber：获取用户手机号，从bindgetphonenumber回调获取用户信息（小程序插件中不能使用）；
• getUserInfo：获取用户信息，从bindgetuserinfo回调获取（小程序插件中不能使用）；
• launchApp：打开 APP，可通过app-parameter属性传参；
• openSetting：打开授权设置页；
• feedback：打开“意见反馈”页面；
• chooseAvatar：获取用户头像，从bindchooseavatar回调获取头像信息；
• agreePrivacyAuthorization：用户同意隐私协议按钮，点击一次后所有隐私接口可正常调用，可通过bindagreeprivacyauthorization监听同意事件。

这些开放能力事件由 button.vue 在原生<button>上一一绑定并向上转发。

Button Events

组件事件列表如下：

| 名称 | 参数 | 描述 | | -- | -- | -- | | agreeprivacyauthorization | - | 用户同意隐私协议事件回调，open-type=agreePrivacyAuthorization时有效（如使用onNeedPrivacyAuthorization接口，需在触发后再调用resolve({ event: "agree", buttonId })） | | chooseavatar | - | 获取用户头像回调，open-type=chooseAvatar时有效，e.detail.avatarUrl为头像临时文件链接 | | click |(e: MouseEvent)| 点击时触发 | | contact | - | 客服消息回调，open-type="contact"时有效 | | createliveactivity | - | 新的一次性订阅消息下发机制回调，open-type=liveActivity时有效 | | error | - | 使用开放能力发生错误时的回调，open-type=launchApp时有效 | | getphonenumber | - | 手机号快速验证回调，open-type=getPhoneNumber时有效。提示：触发回调后应立即隐藏按钮或置为disabled，避免用户重复授权产生额外费用 | | getrealtimephonenumber | - | 手机号实时验证回调，open-type=getRealtimePhoneNumber时有效，处理方式同上 | | getuserinfo | - | 用户点击后返回获取到的用户信息，回调 detail 数据与wx.getUserInfo返回一致，open-type="getUserInfo"时有效 | | launchapp | - | 打开 APP 成功的回调，open-type=launchApp时有效 | | opensetting | - | 打开授权设置页后的回调，open-type=openSetting时有效 |

需要说明的是，getrealtimephonenumber与phoneoneclicklogin等事件在 button.vue 中同样被监听并转发，属于对原生按钮能力的完整透传。

Button Slots

| 名称 | 描述 | | -- | -- | | 默认插槽（-） | 按钮内容，作用同content插槽 | | content | 自定义content显示内容 | | suffix | 右侧内容，可用于定义右侧图标 |

在 button.vue 中，内容区按<slot name="content">→content文本 → 默认插槽<slot />的顺序渲染，且当同时存在图标/加载与文本时，会自动追加--content--has-icon类以控制间距。

Button External Classes

外部样式类用于在页面中覆写组件内部节点样式：

| 类名 | 描述 | | -- | -- | | t-class | 根节点样式类 | | t-class-icon | 图标样式类 | | t-class-loading | 加载样式类 |

外部类通过 button.vue 中的externalClasses声明为t-class、t-class-icon、t-class-loading三项。组合按钮示例与形状示例中均用到了t-class来追加自定义类；图标与加载指示器分别接收t-class-icon、t-class-loading。

CSS Variables

组件提供了完整的 CSS 变量体系用于自定义样式，所有变量均可被外部覆盖。以下按主题、形态与尺寸分组展示（默认值取自 button.less 与 README.md）：

通用变量

| 名称 | 默认值 | | -- | -- | | --td-button-border-radius | @radius-default | | --td-button-border-width | 4rpx | | --td-button-icon-border-radius | 8rpx | | --td-button-icon-spacer | @spacer |

default 主题

| 名称 | 默认值 | | -- | -- | | --td-button-default-color | @text-color-primary | | --td-button-default-bg-color | @bg-color-component | | --td-button-default-border-color | @bg-color-component | | --td-button-default-disabled-bg | @bg-color-component-disabled | | --td-button-default-disabled-border-color | @bg-color-component-disabled | | --td-button-default-disabled-color | @text-color-disabled | | --td-button-default-active-bg-color | @bg-color-component-active | | --td-button-default-active-border-color | @bg-color-component-active | | --td-button-default-outline-color | @text-color-primary | | --td-button-default-outline-border-color | @component-border | | --td-button-default-outline-disabled-color | @component-border | | --td-button-default-text-active-bg-color | @bg-color-container-active |

primary 主题

| 名称 | 默认值 | | -- | -- | | --td-button-primary-color | @text-color-anti | | --td-button-primary-bg-color | @brand-color | | --td-button-primary-border-color | @brand-color | | --td-button-primary-disabled-bg | @brand-color-disabled | | --td-button-primary-disabled-border-color | @brand-color-disabled | | --td-button-primary-disabled-color | @text-color-anti | | --td-button-primary-active-bg-color | @brand-color-active | | --td-button-primary-active-border-color | @brand-color-active | | --td-button-primary-outline-color | @brand-color | | --td-button-primary-outline-border-color | @button-primary-outline-color | | --td-button-primary-outline-disabled-color | @brand-color-disabled | | --td-button-primary-text-color | @brand-color | | --td-button-primary-text-disabled-color | @brand-color-disabled | | --td-button-primary-dashed-color | @brand-color | | --td-button-primary-dashed-border-color | @button-primary-dashed-color | | --td-button-primary-dashed-disabled-color | @brand-color-disabled |

light 主题

| 名称 | 默认值 | | -- | -- | | --td-button-light-color | @brand-color | | --td-button-light-bg-color | @brand-color-light | | --td-button-light-border-color | @brand-color-light | | --td-button-light-disabled-bg | @brand-color-light | | --td-button-light-disabled-border-color | @brand-color-light | | --td-button-light-disabled-color | @brand-color-disabled | | --td-button-light-active-bg-color | @brand-color-light-active | | --td-button-light-active-border-color | @brand-color-light-active | | --td-button-light-outline-color | @brand-color | | --td-button-light-outline-bg-color | @brand-color-light | | --td-button-light-outline-border-color | @button-light-outline-color | | --td-button-light-outline-disabled-color | @brand-color-disabled | | --td-button-light-text-color | @brand-color | | --td-button-light-text-active-bg-color | @bg-color-container-active |

danger 主题

| 名称 | 默认值 | | -- | -- | | --td-button-danger-color | @text-color-anti | | --td-button-danger-bg-color | @error-color | | --td-button-danger-border-color | @error-color | | --td-button-danger-disabled-bg | @error-color-3 | | --td-button-danger-disabled-border-color | @error-color-3 | | --td-button-danger-disabled-color | @font-white-1 | | --td-button-danger-active-bg-color | @error-color-active | | --td-button-danger-active-border-color | @error-color-active | | --td-button-danger-outline-color | @error-color | | --td-button-danger-outline-border-color | @button-danger-outline-color | | --td-button-danger-outline-disabled-color | @error-color-3 | | --td-button-danger-text-color | @error-color | | --td-button-danger-text-disabled-color | @button-danger-disabled-color | | --td-button-danger-dashed-color | @error-color | | --td-button-danger-dashed-border-color | @button-danger-dashed-color | | --td-button-danger-dashed-disabled-color | @button-danger-disabled-color |

ghost 相关变量

| 名称 | 默认值 | | -- | -- | | --td-button-ghost-color | @text-color-anti | | --td-button-ghost-border-color | @button-ghost-color | | --td-button-ghost-disabled-color | @font-white-4 | | --td-button-ghost-hover-color | @font-white-2 | | --td-button-ghost-primary-color | @brand-color | | --td-button-ghost-primary-border-color | @brand-color | | --td-button-ghost-primary-hover-color | @brand-color-active | | --td-button-ghost-danger-color | @error-color | | --td-button-ghost-danger-border-color | @error-color | | --td-button-ghost-danger-hover-color | @error-color-active |

尺寸变量

| 名称 | 默认值 | | -- | -- | | --td-button-extra-small-font | @font-mark-medium | | --td-button-extra-small-height | 56rpx | | --td-button-extra-small-padding-horizontal | 16rpx | | --td-button-extra-small-icon-size | 36rpx | | --td-button-small-font | @font-mark-medium | | --td-button-small-height | 64rpx | | --td-button-small-padding-horizontal | 24rpx | | --td-button-small-icon-size | 36rpx | | --td-button-medium-font | @font-mark-large | | --td-button-medium-height | 80rpx | | --td-button-medium-padding-horizontal | 32rpx | | --td-button-medium-icon-size | 40rpx | | --td-button-large-font | @font-mark-large | | --td-button-large-height | 96rpx | | --td-button-large-padding-horizontal | 40rpx | | --td-button-large-icon-size | 48rpx |

这些变量与 button.less 顶部的var(--td-button-*, fallback)声明一一对应，因此你可以在任意位置直接覆写同名 CSS 变量来改变按钮外观，例如全局统一按钮高度或品牌色：

:root { --td-button-primary-bg-color: #0052d9; --td-button-large-height: 104rpx; }

组件实现原理速览

从 button.vue 可以提炼出组件的核心实现思路，方便排查问题与二次开发：

1. 透传原生能力：组件根节点是原生<button>，通过:form-type、:open-type、:hover-*、:lang、客服卡片系列（send-message-*、session-from、show-message-card）、app-parameter、entrance-path等属性将配置原样透传给小程序原生按钮，最大化复用平台能力。
2. 条件透传：当disabled或loading为真时，form-type、open-type会被置为空字符串，防止禁用/加载状态误触发生开放能力调用。
3. 内部子组件：图标态使用t-icon，加载态使用t-loading，二者均接收独立的样式类（t-class-icon、t-class-loading）以便外部覆写。
4. 样式变量驱动：全部颜色、尺寸均通过 CSS 变量提供默认值（见 button.less），支持在页面级或全局覆盖，无需修改组件源码。
5. 多端适配：源码中针对 QQ 小程序（MP-QQ）补充了 outline 与 ghost 的实线边框规则，针对 H5 与微信小程序（MP-WEIXIN）补充了图标/加载与内容之间的间距规则（见 button.vue），保证不同端渲染一致。

结语

TDesign Button 按钮组件在保持原生<button>全部能力（客服、转发、手机号、头像、隐私授权等开放能力）的同时，通过variant×theme×shape×size的组合体系覆盖了从基础操作到强调型操作的绝大多数业务场景，并提供插槽、外部样式类与全套 CSS 变量三种定制途径。配合 组件源码、属性定义、类型定义 与 示例集合，开发者可以快速将其应用到实际的 Uniapp / 小程序项目中，并灵活适配品牌视觉体系。

• 前端
• UI组件
• 小程序
• 设计系统
• 移动开发