xtf-linkui

Appearance

xtf-button ​

组件说明 ​

xtf-button 是按钮组件，支持多种类型（实心、柔和、描边、幽灵、玻璃、渐变、拟物）、主题色、尺寸、按压动效、涟漪效果、加载状态和开放能力。配合 xtf-button-group 可组合按钮组，配合 xtf-form 可作为表单提交/重置按钮，是 UI 交互的核心组件。

基础用法 ​

1. 最简示例 ​

通过 label 设置按钮文字，type 控制按钮类型，theme 控制主题色：

vue
<template>
  <view style="display: flex; gap: 16rpx; flex-wrap: wrap">
    <xtf-button label="主要按钮" type="solid" theme="primary" />
    <xtf-button label="成功按钮" type="solid" theme="success" />
    <xtf-button label="警告按钮" type="solid" theme="warning" />
    <xtf-button label="危险按钮" type="solid" theme="danger" />
  </view>
</template>

2. 按钮类型 ​

通过 type 切换按钮视觉类型：'solid' / 'light' / 'outline' / 'ghost' / 'glass' / 'gradient' / 'neo'：

vue
<template>
  <view style="display: flex; gap: 16rpx; flex-wrap: wrap">
    <xtf-button label="实心" type="solid" />
    <xtf-button label="柔和" type="light" />
    <xtf-button label="描边" type="outline" />
    <xtf-button label="幽灵" type="ghost" />
    <xtf-button label="玻璃" type="glass" />
    <xtf-button label="渐变" type="gradient" />
    <xtf-button label="拟物" type="neo" />
  </view>
</template>

3. 尺寸与形状 ​

通过 size 控制尺寸，通过 shape / round / block 控制形状和布局：

vue
<template>
  <view>
    <view style="display: flex; gap: 16rpx; align-items: center; margin-bottom: 24rpx">
      <xtf-button label="超小" size="xs" />
      <xtf-button label="小" size="sm" />
      <xtf-button label="中" size="md" />
      <xtf-button label="大" size="lg" />
      <xtf-button label="超大" size="xl" />
    </view>
    <view style="display: flex; gap: 16rpx; margin-bottom: 24rpx">
      <xtf-button label="圆角" round />
      <xtf-button label="方形" shape="square" />
      <xtf-button label="圆形" shape="circle" icon="add" />
    </view>
    <xtf-button label="块级按钮" block />
  </view>
</template>

4. 加载与禁用 ​

通过 loading 显示加载状态，通过 disabled 禁用按钮：

vue
<template>
  <view style="display: flex; gap: 16rpx; flex-wrap: wrap">
    <xtf-button label="加载中" loading />
    <xtf-button label="禁用" disabled />
    <xtf-button label="禁用描边" type="outline" disabled />
    <xtf-button label="提交" :loading="submitting" @click="handleSubmit" />
  </view>
</template>

<script>
export default {
  data() {
    return {
      submitting: false
    }
  },
  methods: {
    async handleSubmit() {
      this.submitting = true
      await new Promise((resolve) => setTimeout(resolve, 2000))
      this.submitting = false
      uni.showToast({ title: '提交成功', icon: 'none' })
    }
  }
}
</script>

5. 自定义颜色与按压效果 ​

通过 color / gradientEndColor 自定义颜色，通过 pressEffect 切换按压动效：

vue
<template>
  <view style="display: flex; gap: 16rpx; flex-wrap: wrap">
    <xtf-button label="自定义色" type="solid" color="#8B5CF6" gradient-end-color="#EC4899" />
    <xtf-button label="缩放" press-effect="scale" />
    <xtf-button label="下沉" press-effect="down" />
    <xtf-button label="内凹" press-effect="inset" />
    <xtf-button label="光环" press-effect="ring" />
    <xtf-button label="无效果" press-effect="none" />
  </view>
</template>

6. 前缀/后缀插槽与开放能力 ​

通过 prefix / suffix 插槽添加图标，通过 openType 使用微信开放能力：

vue
<template>
  <view style="display: flex; gap: 16rpx; flex-wrap: wrap">
    <xtf-button label="搜索" type="solid">
      <template #prefix>
        <xtf-icon name="search" size="sm" />
      </template>
    </xtf-button>
    <xtf-button label="下一步" type="solid">
      <template #suffix>
        <xtf-icon name="arrow-forward" size="sm" />
      </template>
    </xtf-button>
    <xtf-button
      label="获取手机号"
      type="solid"
      open-type="getPhoneNumber"
      @getphonenumber="onGetPhone"
    />
  </view>
</template>

<script>
export default {
  methods: {
    onGetPhone(e) {
      console.log('手机号信息:', e.detail)
    }
  }
}
</script>

全部属性 ​

属性类型默认值作用描述适用范围
labelString''按钮文字设置按钮文案
localeKeyString''国际化 key，配合 xtfLocaleProvider 使用多语言场景
typeString'solid'按钮类型：'solid' / 'light' / 'outline' / 'outlined' / 'ghost' / 'glass' / 'gradient' / 'neo'切换视觉类型
themeString'primary'主题色：'primary' / 'success' / 'warning' / 'danger' / 'info' / 'secondary' / 'error' / 'hazard'切换主题色
presetString''预设样式：'primary-fill' / 'error-fill' / 'warning-fill' / 'hazard-fill' / 'success-fill' / 'secondary-soft'快速应用预设
colorString''自定义主色，设置后 theme 失效精确控制颜色
softColorString''自定义柔和背景色（light 类型）精确控制柔和色
gradientEndColorString''自定义渐变结束色（gradient 类型）精确控制渐变
sizeString''尺寸：'xs' / 'sm' / 'md' / 'lg' / 'xl'，默认继承 buttonGroup / form / configProvider控制按钮大小
shapeString''形状：'round' / 'square' / 'circle'切换形状
roundBooleanfalse是否圆角（等同于 shape="round"）快捷设置圆角
blockBooleanfalse是否块级宽度占满整行
disabledBooleanfalse是否禁用禁用交互
loadingBooleanfalse是否加载中，加载时显示旋转动画并禁用点击异步操作
throttleString | Number0节流时间（毫秒），0 为不节流防重复点击
rippleBoolean | Stringnull是否显示涟漪效果，默认跟随 configProvider点击涟漪
pressEffectString'scale'按压动效：'scale' / 'shrink' / 'down' / 'dim' / 'fade' / 'inset' / 'ring' / 'tilt' / 'none'切换按压效果
plainBooleanfalse是否朴素模式，solid 自动降级为 outline朴素风格
openTypeString''微信开放能力类型微信能力
formTypeString''表单类型：'submit' / 'reset'，配合 xtf-form 使用表单提交
appParameterString''小程序 app-parameter小程序场景
hairlineBooleanfalse是否细边框（1rpx）细线风格
customClassString''自定义类名样式覆盖
customStyleString | Object''自定义样式动态样式覆盖

事件 ​

事件名称触发时机回调参数参数说明
click点击按钮时触发（disabled / loading 不触发）(event)原生点击事件对象
tap同 click(event)原生点击事件对象
longpress长按按钮时触发(event)原生长按事件对象
long-press同 longpress(event)原生长按事件对象
getphonenumberopenType="getPhoneNumber" 回调(event)微信获取手机号回调
getuserinfoopenType="getUserInfo" 回调(event)微信获取用户信息回调
opensettingopenType="openSetting" 回调(event)微信打开设置回调
launchappopenType="launchApp" 回调(event)微信启动 App 回调
contactopenType="contact" 回调(event)微信客服回调
error开放能力错误回调(event)错误信息
chooseavataropenType="chooseAvatar" 回调(event)微信选择头像回调

事件使用示例 ​

vue
<template>
  <xtf-button label="保存" @click="onClick" @tap="onTap" @longpress="onLongPress" />
</template>

<script>
export default {
  methods: {
    onClick(event) {
      console.log('click', event)
    },
    onTap(event) {
      console.log('tap', event)
    },
    onLongPress(event) {
      console.log('longpress', event)
    }
  }
}
</script>

插槽 ​

插槽名说明
默认插槽替换 label 按钮文案。
prefix按钮文案前的内容。
suffix按钮文案后的内容。

主题说明 ​

  • 实心按钮背景使用 var(--xtf-button-instance-color)，文字色使用 var(--xtf-button-solid-text)
  • 柔和按钮背景使用 var(--xtf-button-instance-soft-bg)，文字色使用主色
  • 描边按钮边框使用主色，背景透明
  • 玻璃按钮背景使用 var(--xtf-color-glass)，边框使用 var(--xtf-card-border)
  • 渐变按钮使用 linear-gradient(135deg, 主色, var(--xtf-button-instance-gradient-end))
  • 拟物按钮背景使用 var(--xtf-color-surface)，阴影使用 var(--xtf-shadow-neo)
  • 涟漪效果使用 var(--xtf-button-ripple)
  • 圆角使用 var(--xtf-radius-lg)，全圆角使用 var(--xtf-radius-full)
  • 禁用状态不透明度为 0.56

如需全局调整主题，请在 xtf-config-provider 或主题配置中覆盖上述 CSS 变量。

MIT Licensed

Copyright © 2026 xtf-linkui