★ FEATURED ARTICLE 前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载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 themeprimary sizelarge 填充按钮 /t-button t-button themelight sizelarge 填充按钮 /t-button t-button sizelarge 填充按钮 /t-button !-- 同一主题下的不同 variant -- t-button themeprimary sizelarge variantoutline 描边按钮 /t-button t-button themeprimary sizelarge variantdashed 虚框按钮 /t-button t-button themeprimary sizelarge varianttext 文字按钮 /t-button其中variant可选值包括base基础填充、outline线框、dashed虚线、text文字四种默认值为base。图标按钮图标按钮在按钮内渲染t-icon图标图标名称通过icon属性传入。参考 图标按钮示例t-button themeprimary iconapp content填充按钮 sizelarge / t-button themeprimary iconsearch shapesquare sizelarge aria-label搜索 /icon属性支持两种取值字符串直接表示图标名称如iconsearch对象透传至t-icon组件可携带name、size、color、prefix、style等配置。从 组件源码 看icon值会通过calcIcon(value, )被解析为内部innerIcon对象并据此渲染t-icon子组件calcIcon的实现在 common/utils.js当传入字符串时直接作为图标名传入对象时原样透传二者都不满足时返回null不渲染图标。图标尺寸会跟随按钮尺寸自动适配extra-small与small为36rpxmedium为40rpxlarge为48rpx见 button.vue 中的映射。图标按钮在shapecircle等场景下还常配合aria-label提供无障碍描述。幽灵按钮幽灵按钮为镂空透明背景样式常用于深色背景或 Banner 场景。参考 幽灵按钮示例该示例背景为深色#181818t-button themeprimary ghost sizelarge 幽灵按钮 /t-button t-button themedanger ghost sizelarge 幽灵按钮 /t-button t-button ghost sizelarge 幽灵按钮 /t-buttonghost默认值为false开启后背景透明、边框与文字使用对应主题色。在样式实现button.less中幽灵按钮的优先级高于theme固定透明背景并分别为default、primary、danger提供了独立的边框色与 hover 色变量如--td-button-ghost-primary-color、--td-button-ghost-danger-color。组合按钮组合按钮通过多个block按钮横向拼接实现常用于“上一步/下一步”等步骤型操作。参考 组合按钮示例t-button themelight block sizelarge :custom-styleflex: 1; margin-right: 16px; 填充按钮 /t-button t-button themeprimary block sizelarge :custom-styleflex: 1; 填充按钮 /t-button要点每个子按钮都设置block使宽度撑满父容器再通过flex: 1均分宽度使用margin-right制造按钮间距示例中还通过canUseVirtualHost()判断环境是否支持虚拟宿主以决定样式应写在custom-style还是原生style上。通栏按钮通栏按钮即宽度为 100% 的块级按钮仅需设置block属性。参考 通栏按钮示例t-button themeprimary sizelarge block 填充按钮 /t-button样式层面对应 button.less 中的--block { display: flex; width: 100%; }规则。组件状态按钮禁用态通过disabled属性开启禁用态禁用后按钮不可点击、视觉变为灰色并应用禁用配色。参考 禁用态示例t-button themeprimary sizelarge disabled 填充按钮 /t-button t-button themeprimary sizelarge variantoutline disabled 描边按钮 /t-button t-button themeprimary sizelarge varianttext disabled 文字按钮 /t-button关于disabled需要了解以下几点默认值为undefined与表单组件配合时存在优先级规则Button.disabled Form.disabled见 props.ts 的注释禁用或加载状态下open-type、form-type都会被置空hover-class点击态也不会生效见 button.vuehandleTap中也会显式拦截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 themeprimary sizelarge loading 加载中 /t-buttonloading相关行为加载状态下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 themespinner展示“加载中...”文案作为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 themeprimary sizelarge 按钮48 /t-button t-button themeprimary 按钮40 /t-button t-button themeprimary sizesmall 按钮32 /t-button t-button themeprimary sizeextra-small 按钮28 /t-button示例中“按钮48/按钮40/按钮32/按钮28”即对应各尺寸的高度rpx。按钮形状shape控制按钮形状可选rectangle长方形默认/square正方形/round圆角长方形/circle圆形。参考 形状示例t-button themeprimary sizelarge 填充按钮 /t-button t-button themeprimary sizelarge iconsearch shapesquare aria-label搜索 / t-button themeprimary sizelarge shaperound 填充按钮 /t-button t-button themeprimary sizelarge iconsearch shapecircle aria-label搜索 /各形状的样式实现button.lessround圆角半径取当前尺寸高度的一半calc(button-*-height / 2)且会同步调整::after伪元素圆角squarepadding: 0宽高相等宽度取当前尺寸高度值circleborder-radius: 50%宽高相等适合纯图标按钮此时务必配合aria-label提升无障碍可访问性。按钮主题theme控制按钮主题色可选default/primary/danger/light默认default其中primary为品牌色、danger为危险色。参考 主题示例每个主题均可与variant自由组合!-- default -- t-button sizelarge 填充按钮 /t-button t-button sizelarge variantoutline 描边按钮 /t-button t-button sizelarge varianttext 文字按钮 /t-button !-- primary -- t-button sizelarge themeprimary 填充按钮 /t-button t-button sizelarge themeprimary variantoutline 描边按钮 /t-button t-button sizelarge themeprimary varianttext 文字按钮 /t-button !-- danger -- t-button sizelarge themedanger 填充按钮 /t-button t-button sizelarge themedanger variantoutline 描边按钮 /t-button t-button sizelarge themedanger varianttext 文字按钮 /t-button !-- light -- t-button sizelarge themelight 填充按钮 /t-button t-button sizelarge themelight variantoutline 描边按钮 /t-button t-button sizelarge themelight varianttext 文字按钮 /t-button类名生成逻辑见 button.vuesetClass会根据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-typelaunchApp时有效 | 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-classnone时没有点击态效果 | 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-typegetPhoneNumber或getRealtimePhoneNumber时有效 | N | | send-message-img | String | 截图 | 会话内消息卡片图片open-typecontact时有效 | N | | send-message-path | String | 当前分享路径 | 会话内消息卡片点击跳转小程序路径open-typecontact时有效 | N | | send-message-title | String | 当前标题 | 会话内消息卡片标题open-typecontact时有效 | N | | session-from | String | | 会话来源open-typecontact时有效 | N | | shape | String | rectangle | 按钮形状可选rectangle/square/round/circle| N | | show-message-card | Boolean | false | 是否显示会话内消息卡片open-typecontact时有效 | 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.tscontact打开客服会话用户在会话中点击消息卡片返回小程序时可从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-typeagreePrivacyAuthorization时有效如使用onNeedPrivacyAuthorization接口需在触发后再调用resolve({ event: agree, buttonId }) | | chooseavatar | - | 获取用户头像回调open-typechooseAvatar时有效e.detail.avatarUrl为头像临时文件链接 | | click |(e: MouseEvent)| 点击时触发 | | contact | - | 客服消息回调open-typecontact时有效 | | createliveactivity | - | 新的一次性订阅消息下发机制回调open-typeliveActivity时有效 | | error | - | 使用开放能力发生错误时的回调open-typelaunchApp时有效 | | getphonenumber | - | 手机号快速验证回调open-typegetPhoneNumber时有效。提示触发回调后应立即隐藏按钮或置为disabled避免用户重复授权产生额外费用 | | getrealtimephonenumber | - | 手机号实时验证回调open-typegetRealtimePhoneNumber时有效处理方式同上 | | getuserinfo | - | 用户点击后返回获取到的用户信息回调 detail 数据与wx.getUserInfo返回一致open-typegetUserInfo时有效 | | launchapp | - | 打开 APP 成功的回调open-typelaunchApp时有效 | | opensetting | - | 打开授权设置页后的回调open-typeopenSetting时有效 |需要说明的是getrealtimephonenumber与phoneoneclicklogin等事件在 button.vue 中同样被监听并转发属于对原生按钮能力的完整透传。Button Slots| 名称 | 描述 | | -- | -- | | 默认插槽- | 按钮内容作用同content插槽 | | content | 自定义content显示内容 | | suffix | 右侧内容可用于定义右侧图标 |在 button.vue 中内容区按slot namecontent→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 可以提炼出组件的核心实现思路方便排查问题与二次开发透传原生能力组件根节点是原生button通过:form-type、:open-type、:hover-*、:lang、客服卡片系列send-message-*、session-from、show-message-card、app-parameter、entrance-path等属性将配置原样透传给小程序原生按钮最大化复用平台能力。条件透传当disabled或loading为真时form-type、open-type会被置为空字符串防止禁用/加载状态误触发生开放能力调用。内部子组件图标态使用t-icon加载态使用t-loading二者均接收独立的样式类t-class-icon、t-class-loading以便外部覆写。样式变量驱动全部颜色、尺寸均通过 CSS 变量提供默认值见 button.less支持在页面级或全局覆盖无需修改组件源码。多端适配源码中针对 QQ 小程序MP-QQ补充了 outline 与 ghost 的实线边框规则针对 H5 与微信小程序MP-WEIXIN补充了图标/加载与内容之间的间距规则见 button.vue保证不同端渲染一致。结语TDesign Button 按钮组件在保持原生button全部能力客服、转发、手机号、头像、隐私授权等开放能力的同时通过variant×theme×shape×size的组合体系覆盖了从基础操作到强调型操作的绝大多数业务场景并提供插槽、外部样式类与全套 CSS 变量三种定制途径。配合 组件源码、属性定义、类型定义 与 示例集合开发者可以快速将其应用到实际的 Uniapp / 小程序项目中并灵活适配品牌视觉体系。赞分享前端UI组件小程序设计系统移动开发【免费下载链接】tdesign-miniprogramWechat MiniProgram and Uniapp UI components lib for TDesign项目地址https://gitcode.com/gh_mirrors/tde/tdesign-miniprogram点击查看免费下载相关推荐Shoelace sl-icon-button 图标按钮组件完全指南属性、事件与样式定制Shoelace sl icon button 图标按钮组件完全指南属性、事件与样式定制 sl icon button 是 Shoelace 提供的一种纯图标UI组件前端Makepad 按钮控件Button完整指南属性、样式与状态机制详解Makepad 按钮控件Button完整指南属性、样式与状态机制详解 本篇技术指南以 examples/uizoo/resources/button.md前端UI组件3D渲染跨平台游戏开发HTML Standard入门答疑DOCTYPE到底写什么、为什么标准没有版本号8个高频疑问一次讲透HTML Standard入门答疑DOCTYPE到底写什么、为什么标准没有版本号8个高频疑问一次讲透 如果你刚接触 HTML Standard HT前端UI组件小程序设计系统移动开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
