FxBtn 按钮

常用的操作按钮。自实现、不依赖任何 UI 框架，额外内置点击防抖/节流与自动 loading。

FxBtn 属于 @fx/components（UI 框架无关的通用组件）。

基础用法

使用 type、plain、round、dashed 和 circle 来定义按钮的样式。

<template>
  <div class="flex flex-col gap-4">
    <div class="row">
      <FxBtn>Default</FxBtn>
      <FxBtn type="primary">Primary</FxBtn>
      <FxBtn type="success">Success</FxBtn>
      <FxBtn type="info">Info</FxBtn>
      <FxBtn type="warning">Warning</FxBtn>
      <FxBtn type="danger">Danger</FxBtn>
    </div>

    <div class="row">
      <FxBtn plain>Plain</FxBtn>
      <FxBtn type="primary" plain>Primary</FxBtn>
      <FxBtn type="success" plain>Success</FxBtn>
      <FxBtn type="info" plain>Info</FxBtn>
      <FxBtn type="warning" plain>Warning</FxBtn>
      <FxBtn type="danger" plain>Danger</FxBtn>
    </div>

    <div class="row">
      <FxBtn round>Round</FxBtn>
      <FxBtn type="primary" round>Primary</FxBtn>
      <FxBtn type="success" round>Success</FxBtn>
      <FxBtn type="info" round>Info</FxBtn>
      <FxBtn type="warning" round>Warning</FxBtn>
      <FxBtn type="danger" round>Danger</FxBtn>
    </div>

    <div class="row">
      <FxBtn dashed>Dashed</FxBtn>
      <FxBtn type="primary" dashed>Primary</FxBtn>
      <FxBtn type="success" dashed>Success</FxBtn>
      <FxBtn type="info" dashed>Info</FxBtn>
      <FxBtn type="warning" dashed>Warning</FxBtn>
      <FxBtn type="danger" dashed>Danger</FxBtn>
    </div>

    <div class="row">
      <FxBtn circle>
        <template #icon><FxIcon name="ep:search" /></template>
      </FxBtn>
      <FxBtn type="primary" circle>
        <template #icon><FxIcon name="ep:edit" /></template>
      </FxBtn>
      <FxBtn type="success" circle>
        <template #icon><FxIcon name="ep:check" /></template>
      </FxBtn>
      <FxBtn type="info" circle>
        <template #icon><FxIcon name="ep:message" /></template>
      </FxBtn>
      <FxBtn type="warning" circle>
        <template #icon><FxIcon name="ep:star-filled" /></template>
      </FxBtn>
      <FxBtn type="danger" circle>
        <template #icon><FxIcon name="ep:delete" /></template>
      </FxBtn>
    </div>
  </div>
</template>

<style scoped>
.row {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 1rem;
}
.row :deep(.fx-btn) {
  margin-left: 0;
}
</style>

禁用状态

按钮不可用状态。

使用 disabled 属性来定义按钮是否可用，它接受一个 Boolean 值。

<template>
  <div class="flex flex-col gap-4">
    <div class="row">
      <FxBtn disabled>Default</FxBtn>
      <FxBtn type="primary" disabled>Primary</FxBtn>
      <FxBtn type="success" disabled>Success</FxBtn>
      <FxBtn type="info" disabled>Info</FxBtn>
      <FxBtn type="warning" disabled>Warning</FxBtn>
      <FxBtn type="danger" disabled>Danger</FxBtn>
    </div>

    <div class="row">
      <FxBtn plain disabled>Plain</FxBtn>
      <FxBtn type="primary" plain disabled>Primary</FxBtn>
      <FxBtn type="success" plain disabled>Success</FxBtn>
      <FxBtn type="info" plain disabled>Info</FxBtn>
      <FxBtn type="warning" plain disabled>Warning</FxBtn>
      <FxBtn type="danger" plain disabled>Danger</FxBtn>
    </div>
  </div>
</template>

<style scoped>
.row {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 1rem;
}
.row :deep(.fx-btn) {
  margin-left: 0;
}
</style>

链接按钮

没有边框和背景色的链接样式按钮。使用 link 属性启用，配合 type 可设置链接按钮的主题色。

<template>
  <p>基础链接按钮</p>
  <div class="row mb-4">
    <FxBtn v-for="b in buttons" :key="b.text" :type="b.type" link>
      {{ b.text }}
    </FxBtn>
  </div>

  <p>禁用状态</p>
  <div class="row">
    <FxBtn v-for="b in buttons" :key="b.text" :type="b.type" link disabled>
      {{ b.text }}
    </FxBtn>
  </div>
</template>

<script setup lang="ts">
const buttons = [
  { type: "", text: "plain" },
  { type: "primary", text: "primary" },
  { type: "success", text: "success" },
  { type: "info", text: "info" },
  { type: "warning", text: "warning" },
  { type: "danger", text: "danger" },
] as const
</script>

<style scoped>
.row {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 1rem;
}
.row :deep(.fx-btn) {
  margin-left: 0;
}
</style>

文字按钮

没有边框的文字按钮，hover 时显示浅色背景。使用 text 属性启用，配合 bg 可常驻背景色。

<template>
  <p>基础文字按钮</p>
  <div class="row mb-4">
    <FxBtn v-for="b in buttons" :key="b.text" :type="b.type" text>
      {{ b.text }}
    </FxBtn>
  </div>

  <p>背景色常驻</p>
  <div class="row mb-4">
    <FxBtn v-for="b in buttons" :key="b.text" :type="b.type" text bg>
      {{ b.text }}
    </FxBtn>
  </div>

  <p>禁用状态</p>
  <div class="row">
    <FxBtn v-for="b in buttons" :key="b.text" :type="b.type" text disabled>
      {{ b.text }}
    </FxBtn>
  </div>
</template>

<script setup lang="ts">
const buttons = [
  { type: "", text: "plain" },
  { type: "primary", text: "primary" },
  { type: "success", text: "success" },
  { type: "info", text: "info" },
  { type: "warning", text: "warning" },
  { type: "danger", text: "danger" },
] as const
</script>

<style scoped>
.row {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 1rem;
}
.row :deep(.fx-btn) {
  margin-left: 0;
}
</style>

图标按钮

带图标的按钮可增强辨识度（有文字）或节省空间（无文字）。

使用 icon 插槽（或 icon 属性）来添加图标。自定义图标同样适用。

<template>
  <div class="row">
    <FxBtn type="primary" icon="ep:edit"></FxBtn>
    <FxBtn type="primary" :icon="EditIcon"></FxBtn>
    <FxBtn type="primary">
      <template #icon><FxIcon name="ep:edit" /></template>
    </FxBtn>
    <FxBtn type="primary">
      <template #icon><FxIcon name="ep:share" /></template>
    </FxBtn>
    <FxBtn type="primary">
      <template #icon><FxIcon name="ep:delete" /></template>
    </FxBtn>
    <FxBtn type="primary">
      <template #icon><FxIcon name="ep:search" /></template>
      Search
    </FxBtn>
    <FxBtn type="primary">
      <template #icon><FxIcon name="ep:upload" /></template>
      Upload
    </FxBtn>
  </div>
</template>
<script setup lang="ts">
import { FxIcon } from "@fx-core/icon"
import { h } from "vue"
const EditIcon = () => h(FxIcon, { name: "ep:edit" })
</script>

<style scoped>
.row {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 1rem;
}
.row :deep(.fx-btn) {
  margin-left: 0;
}
</style>

按钮组

以按钮组的方式出现，可用于将一系列相似的操作组合在一起。

可以使用 direction 属性控制排列方向。

使用 <FxButtonGroup> 标签来分组你的按钮。

<template>
  <div>
    <FxButtonGroup class="mb-4">
      <FxBtn type="primary">
        <template #icon><FxIcon name="ep:arrow-left" /></template>
        Previous Page
      </FxBtn>
      <FxBtn type="primary">Next Page</FxBtn>
    </FxButtonGroup>

    <div class="mb-4">
      <FxRadioGroup v-model="direction">
        <FxRadio value="horizontal">Horizontal</FxRadio>
        <FxRadio value="vertical">Vertical</FxRadio>
      </FxRadioGroup>
    </div>

    <FxButtonGroup :direction="direction">
      <FxBtn type="primary">
        <template #icon><FxIcon name="ep:house" /></template>
      </FxBtn>
      <FxBtn type="primary">
        <template #icon><FxIcon name="ep:operation" /></template>
      </FxBtn>
      <FxBtn type="primary">
        <template #icon><FxIcon name="ep:bell" /></template>
      </FxBtn>
    </FxButtonGroup>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"

const direction = ref<"horizontal" | "vertical">("horizontal")
</script>

加载状态

点击按钮来加载数据，并向用户返回加载状态。

将 loading 属性设置为 true 即可显示加载状态。

TIP

你可以使用 loading 插槽或 loadingIcon 属性来自定义你的加载组件。

ps：loading 插槽的优先级比 loadingIcon 更高。

<template>
  <div class="row">
    <FxBtn type="primary" loading>Loading</FxBtn>
    <FxBtn type="primary" loading loading-duration="0.5">Loading</FxBtn>
    <FxBtn type="primary" loading loading-duration="0.5s">Loading</FxBtn>
    <FxBtn type="primary" loading loading-duration="500ms">Loading</FxBtn>
    <FxBtn type="primary" loading>
      <template #loading>
        <FxIcon name="ep:loading" />
      </template>
      Loading
    </FxBtn>
    <FxBtn type="primary" loading>
      <template #loading>
        <FxIcon name="ep:eleme" />
      </template>
      Loading
    </FxBtn>
  </div>
</template>

<style scoped>
.row {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 1rem;
}

.row :deep(.fx-btn) {
  margin-left: 0;
}
</style>

不同尺寸

除了默认大小外，Button 组件还提供了几种额外的尺寸，以便在不同场景下使用。

使用 size 属性来设置 large、small 等额外尺寸。

<template>
  <div class="flex flex-col gap-4">
    <div class="row">
      <FxBtn size="large">Large</FxBtn>
      <FxBtn>Default</FxBtn>
      <FxBtn size="small">Small</FxBtn>
      <FxBtn size="large">
        <template #icon><FxIcon name="ep:search" /></template>
        Search
      </FxBtn>
      <FxBtn>
        <template #icon><FxIcon name="ep:search" /></template>
        Search
      </FxBtn>
      <FxBtn size="small">
        <template #icon><FxIcon name="ep:search" /></template>
        Search
      </FxBtn>
    </div>
    <div class="row">
      <FxBtn size="large" round>Large</FxBtn>
      <FxBtn round>Default</FxBtn>
      <FxBtn size="small" round>Small</FxBtn>
      <FxBtn size="large" round>
        <template #icon><FxIcon name="ep:search" /></template>
        Search
      </FxBtn>
      <FxBtn round>
        <template #icon><FxIcon name="ep:search" /></template>
        Search
      </FxBtn>
      <FxBtn size="small" round>
        <template #icon><FxIcon name="ep:search" /></template>
        Search
      </FxBtn>
    </div>
    <div class="row">
      <FxBtn size="large" circle>
        <template #icon><FxIcon name="ep:search" /></template>
      </FxBtn>
      <FxBtn circle>
        <template #icon><FxIcon name="ep:search" /></template>
      </FxBtn>
      <FxBtn size="small" circle>
        <template #icon><FxIcon name="ep:search" /></template>
      </FxBtn>
    </div>
  </div>
</template>

<style scoped>
.row {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 1rem;
}
.row :deep(.fx-btn) {
  margin-left: 0;
}
</style>

自定义标签

你可以自定义组件的元素标签，例如 button、div、a、router-link、nuxt-link。

<template>
  <div class="row">
    <FxBtn>button</FxBtn>
    <FxBtn tag="div" role="button" tabindex="0">div</FxBtn>
    <FxBtn
      type="primary"
      tag="a"
      href="https://github.com/"
      target="_blank"
      rel="noopener noreferrer"
    >
      a
    </FxBtn>
  </div>
</template>

<style scoped>
.row {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 1rem;
}
.row :deep(.fx-btn) {
  margin-left: 0;
}
</style>

自定义颜色

你可以自定义按钮颜色。

我们会自动计算 hover 颜色与 active 颜色。

color 属性可以用于 link 与 text 按钮。

<template>
  <div class="flex flex-col gap-4">
    <div class="row">
      <FxBtn color="#626aef">Default</FxBtn>
      <FxBtn color="#626aef" plain>Plain</FxBtn>
      <FxBtn color="#626aef" link>Link</FxBtn>
      <FxBtn color="#626aef" text>Text</FxBtn>
      <FxBtn color="#626aef" text bg>Text BG</FxBtn>
    </div>
    <div class="row">
      <FxBtn color="#626aef" disabled>Disabled</FxBtn>
      <FxBtn color="#626aef" disabled plain>Disabled Plain</FxBtn>
      <FxBtn color="#626aef" disabled link>Disabled Link</FxBtn>
      <FxBtn color="#626aef" disabled text>Disabled Text</FxBtn>
      <FxBtn color="#626aef" disabled text bg>Disabled Text BG</FxBtn>
    </div>
  </div>
</template>

<style scoped>
.row {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  gap: 1rem;
}
.row :deep(.fx-btn) {
  margin-left: 0;
}
</style>

防抖 / 节流

设置 throttle（毫秒）启用点击防抖/节流，防止重复提交（FxBtn 特有能力）。连续快速点击下面的按钮体验差异：

<template>
  <div class="space-y-4">
    <div class="flex flex-wrap items-center gap-3">
      <FxBtn type="primary" :throttle="500" @click="debounceCount++">
        防抖 500ms
      </FxBtn>
      <span class="text-sm" style="color: var(--fx-text-color-secondary)">
        点击计数：{{ debounceCount }}
      </span>
    </div>
    <div class="flex flex-wrap items-center gap-3">
      <FxBtn
        type="primary"
        :throttle="1000"
        mode="throttle"
        @click="throttleCount++"
      >
        节流 1000ms
      </FxBtn>
      <span class="text-sm" style="color: var(--fx-text-color-secondary)">
        点击计数：{{ throttleCount }}
      </span>
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue"

const debounceCount = ref(0)
const throttleCount = ref(0)
</script>

• mode="debounce"（默认）：连续点击只在停止 throttle ms 后触发最后一次
• mode="throttle"：第一次点击立即触发，等待时间内再次点击不会触发
• throttle=0（默认）：不启用防抖/节流

触发期间按钮自动进入 loading，冷却后恢复，与外部 :loading 取或合并。

模式	Loading 表现
throttle=0	不产生内部 loading，完全由外部 :loading 控制
节流模式	点击后立即 loading，冷却期结束后自动取消
防抖模式	连续点击期间不 loading，最后一次实际执行时才 loading

Button API

FxBtn Attributes

属性	说明	类型	默认值
size	按钮尺寸	'large' | 'default' | 'small'	—
type	按钮类型，设置 color 时以 color 为准	'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info' | ''	—
plain	是否为朴素按钮	boolean	false
text	是否为文字按钮	boolean	false
bg	是否显示文字按钮的背景色	boolean	false
link	是否为链接按钮	boolean	false
round	是否为圆角按钮	boolean	false
circle	是否为圆形按钮	boolean	false
dashed	是否为虚线按钮	boolean	false
loading	是否为加载中状态	boolean	false
loading-icon	自定义加载图标。字符串为 IconString 类型（即 FxIcon 图标名，如 ep:edit、ant-design:home、svg:xxx），亦可传组件	string / Component	Loading
loading-duration	加载图标旋转一圈时长，number 与纯数字字符串（如 "0.5"）按秒、其余 string 原样作 CSS 时长（如 "0.5s"、"500ms"），对三种 loading 来源统一生效	number / string	1.7
disabled	是否禁用	boolean	false
icon	图标。字符串为 IconString 类型（即 FxIcon 图标名，如 ep:edit、ant-design:home、svg:xxx），亦可传组件	string / Component	—
autofocus	原生 button 的 autofocus 属性	boolean	false
native-type	原生 button 的 type 属性	'button' | 'submit' | 'reset'	button
auto-insert-space	自动在两个中文字符之间插入空格（仅在文本长度为 2 且都是中文时生效）	boolean	false
color	自定义按钮颜色，自动计算 hover 和 active 颜色。支持 link/text	string	—
dark	暗色模式，自动将 color 转换为暗色模式颜色	boolean	false
tag	自定义元素标签	string / Component	button
throttle	防抖/节流等待时间（毫秒），0 表示不启用（FxBtn 特有）	number	0
mode	防抖/节流模式（FxBtn 特有）	'debounce' | 'throttle'	debounce

FxBtn Slots

名称	说明
default	自定义默认内容
loading	自定义加载组件
icon	自定义图标组件

FxBtn Exposes

名称	说明	类型
ref	按钮 html 元素	Ref<HTMLButtonElement>
size	按钮尺寸	ComputedRef<'' | 'small' | 'default' | 'large'>
type	按钮类型	ComputedRef<'' | 'default' | 'primary' | 'success' | 'warning' | 'info' | 'danger'>
disabled	按钮是否禁用	ComputedRef<boolean>
shouldAddSpace	是否在两个中文字符之间加空格	ComputedRef<boolean>

ButtonGroup API

FxButtonGroup Attributes

属性	说明	类型	默认值
size	控制组内按钮尺寸	'large' | 'default' | 'small'	—
type	控制组内按钮类型	'primary' | 'success' | 'warning' | 'danger' | 'info'	—
direction	排列方向	'horizontal' | 'vertical'	horizontal

FxButtonGroup Slots

名称	说明	子标签
default	自定义按钮组内容	Button