BrutxUI

简体中文

English

简体中文

English

外观

Button 按钮 ​

新粗野主义风格的按钮组件，支持 9 种变体、4 种尺寸 + icon 模式、加载状态和 asChild 组合支持。

预览 ​

Preview

变体

尺寸

状态

提交按钮

装饰形态（flair）

安装 ​

pnpm dlx brutx-vue@latest add button

用法 ​

vue
<script setup>
import { Button } from 'brutx-ui-vue'
</script>

<template>
    <Button variant="primary" size="default">
        Click me
    </Button>
</template>

加载状态 ​

vue
<script setup>
import { ref } from 'vue'
import { Button } from 'brutx-ui-vue'

const isLoading = ref(false)

async function handleSubmit() {
    isLoading.value = true
    await new Promise(resolve => setTimeout(resolve, 2000))
    isLoading.value = false
}
</script>

<template>
    <Button variant="primary" :loading="isLoading" @click="handleSubmit">
        Save Changes
    </Button>
</template>

禁用状态 ​

vue
<script setup>
import { Button } from 'brutx-ui-vue'
</script>

<template>
    <Button variant="primary" disabled>
        Disabled
    </Button>
</template>

提交按钮与等待文本 ​

通过 type="submit" 将按钮渲染为表单提交按钮。配合 loading 与 pendingText 可在提交期间显示等待文本（替换插槽内容），未传入 pendingText 时回退到 i18n 默认值（submitButton.submitting）：

vue
<script setup>
import { ref } from 'vue'
import { Button } from 'brutx-ui-vue'

const isLoading = ref(false)

async function handleSubmit() {
    isLoading.value = true
    await new Promise(resolve => setTimeout(resolve, 2000))
    isLoading.value = false
}
</script>

<template>
    <form @submit.prevent="handleSubmit">
        <Button type="submit" variant="primary" :loading="isLoading" pending-text="保存中...">
            保存
        </Button>
    </form>
</template>

仅当 type="submit" 且 loading=true 时才会显示等待文本并隐藏插槽内容；其他情况下插槽内容照常渲染，加载图标仍然显示。

asChild ​

使用 asChild 将按钮样式渲染到自定义元素上（例如路由链接）：

vue
<script setup>
import { Button } from 'brutx-ui-vue'
import { RouterLink } from 'vue-router'
</script>

<template>
    <Button as-child>
        <RouterLink to="/about">About</RouterLink>
    </Button>
</template>

故障效果 ​

Button 内置 effect="glitch"，可直接启用故障撕裂动画。

默认 effect="none" 不创建特效媒体监听、定时器或文本同步；glitch-trigger="autoplay" 和实例 play() 都受 effect 开关约束。设置为 glitch 后，禁用、loading 和减少动态效果会停止播放。KeepAlive 停用及卸载会释放资源，重新激活时读取当前系统偏好并按配置恢复。

vue
<template>
    <Button
        effect="glitch"
        variant="primary"
        glitch-trigger="click"
        glitch-speed="fast"
        glitch-direction="both"
        data-text="GLITCH"
    >
        GLITCH
    </Button>
</template>

提示：若直接使用导出的 buttonVariants({ effect: 'glitch' }) 构建 glitch 按钮，需显式传入 glitchSpeed 与 glitchDirection（medium/horizontal 默认值由 <Button> 组件提供，原始工具函数不注入默认 glitch 类）。

变体 ​

变体说明
default背景色，硬阴影
primaryPrimary（珊瑚色）背景
secondarySecondary（薄荷青）背景
accentAccent（黄色）背景
dangerDestructive（红色）背景，白色文字
successSuccess（绿色）背景
outline透明背景，悬停时反转
ghost无边框和阴影，柔和悬停效果
link无边框和阴影，悬停时显示下划线
vue
<template>
    <Button variant="primary">Primary 变体</Button>
</template>

装饰形态 ​

flair 与色系变体正交可组合，提供三种机械质感装饰形态：

形态说明
none默认，不输出任何额外装饰类
stacked多层彩虹硬投影，按压时同源位移（1.5x 盖影）
hazard外围警戒斜纹，中央黄色底板配黑字，悬停时保持文字对比
ticket票据撕口——左右中缝半圆缺口
vue
<template>
    <Button variant="primary" flair="stacked">多层投影</Button>
    <Button variant="accent" flair="hazard">警戒斜纹</Button>
    <Button variant="default" flair="ticket">票据撕口</Button>
</template>

尺寸 ​

尺寸高度内边距字体大小
smh-9px-3 py-1text-sm
defaulth-11px-5 py-2text-base
lgh-14px-8 py-3text-lg
xlh-16px-10 py-4text-xl
iconh-11 w-11p-0—

API 参考 ​

Button — 属性
名称类型默认值说明
variant
"accent" | "danger" | "default" | "ghost" | "link" | "outline" | "primary" | "secondary" | "success" | undefined
"default"
按钮的主视觉变体，控制配色和交互状态样式
详情

声明类型

NonNullable<"default" | "ghost" | "primary" | "secondary" | "success" | "danger" | "accent" | "outline" | "link" | null | undefined> | undefined

字面量

  • "accent"
  • "danger"
  • "default"
  • "ghost"
  • "link"
  • "outline"
  • "primary"
  • "secondary"
  • "success"

默认值详情

声明
'default'

来源: packages/ui/src/components/button/Button.vue

解析值
"default"

来源

Button.vue:21

packages/ui/src/components/button/Button.vue

size
"default" | "icon" | "lg" | "sm" | "xl" | undefined
"default"
按钮的尺寸；icon 用于方形图标按钮
详情

声明类型

NonNullable<"default" | "lg" | "sm" | "xl" | "icon" | null | undefined> | undefined

字面量

  • "default"
  • "icon"
  • "lg"
  • "sm"
  • "xl"

默认值详情

声明
'default'

来源: packages/ui/src/components/button/Button.vue

解析值
"default"

来源

Button.vue:23

packages/ui/src/components/button/Button.vue

flair
"none" | "stacked" | "hazard" | "ticket" | undefined
"none"
装饰形态：多层彩虹投影 / 警戒斜纹 / 票据撕口，与色系变体正交
详情

声明类型

"none" | "stacked" | "hazard" | "ticket" | undefined

字面量

  • "hazard"
  • "none"
  • "stacked"
  • "ticket"

默认值详情

声明
'none'

来源: packages/ui/src/components/button/Button.vue

解析值
"none"

来源

Button.vue:25

packages/ui/src/components/button/Button.vue

asChild
boolean | undefined
false
将按钮属性、样式和交互行为合并到唯一子元素上
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

声明
false

来源: packages/ui/src/components/button/Button.vue

解析值
false

来源

Button.vue:27

packages/ui/src/components/button/Button.vue

type
"button" | "submit" | "reset" | undefined
undefined
原生按钮类型；不传时由原生 button 的默认行为决定
详情

声明类型

"button" | "submit" | "reset" | undefined

字面量

  • "button"
  • "reset"
  • "submit"

默认值详情

声明
undefined

来源: packages/ui/src/components/button/Button.vue

解析值
undefined

来源

Button.vue:29

packages/ui/src/components/button/Button.vue

loading
boolean | undefined
false
显示加载图标并将按钮置为禁用状态
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

声明
false

来源: packages/ui/src/components/button/Button.vue

解析值
false

来源

Button.vue:31

packages/ui/src/components/button/Button.vue

disabled
boolean | undefined
false
禁止按钮的常规用户交互
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

声明
false

来源: packages/ui/src/components/button/Button.vue

解析值
false

来源

Button.vue:33

packages/ui/src/components/button/Button.vue

pendingText
string | undefined
undefined

运行时回退:当 `pendingText` 为 `undefined` 或 `null` 时读取 `submitButton.submitting`，简体中文文案为“提交中...”。

加载中显示的等待文本，作为默认插槽的回退内容；仅在 type="submit" 且 loading 时生效，未传入时回退到 i18n 默认值；提供插槽内容时优先显示插槽
详情

声明类型

string | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/button/Button.vue

解析值
undefined
运行时回退
当 `pendingText` 为 `undefined` 或 `null` 时读取 `submitButton.submitting`，简体中文文案为“提交中...”。

组件在说明的运行条件下采用此回退值。

来源

Button.vue:35

packages/ui/src/components/button/Button.vue

pressed
boolean | undefined
undefined
按钮是否处于按下状态（切换按钮）
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

声明
undefined

来源: packages/ui/src/components/button/Button.vue

解析值
undefined

来源

Button.vue:37

packages/ui/src/components/button/Button.vue

expanded
boolean | undefined
undefined
按钮控制的内容是否展开
详情

声明类型

boolean | undefined

字面量

  • false
  • true

默认值详情

声明
undefined

来源: packages/ui/src/components/button/Button.vue

解析值
undefined

来源

Button.vue:39

packages/ui/src/components/button/Button.vue

effect
"none" | "glitch" | undefined
"none"
是否启用故障撕裂视觉效果
详情

声明类型

"none" | "glitch" | undefined

字面量

  • "glitch"
  • "none"

默认值详情

声明
'none'

来源: packages/ui/src/components/button/Button.vue

解析值
"none"

来源

Button.vue:41

packages/ui/src/components/button/Button.vue

glitchTrigger
GlitchTrigger | undefined
"hover"
故障效果的触发方式；仅在 effect="glitch" 时生效
详情

声明类型

GlitchTrigger | undefined

字面量

  • "autoplay"
  • "click"
  • "hover"
  • "none"

关联类型

GlitchTrigger
类型定义 — GlitchTrigger
export type GlitchTrigger = 'hover' | 'click' | 'autoplay' | 'none'

默认值详情

声明
'hover'

来源: packages/ui/src/components/button/Button.vue

解析值
"hover"

来源

Button.vue:43

packages/ui/src/components/button/Button.vue

glitchInterval
number | undefined
3000
自动播放故障效果时的触发间隔，单位为毫秒
详情

声明类型

number | undefined

默认值详情

声明
DEFAULT_AUTOPLAY_INTERVAL_MS

来源: packages/ui/src/components/button/Button.vue

解析值
3000

来源

Button.vue:45

packages/ui/src/components/button/Button.vue

glitchSpeed
ButtonGlitchSpeed | undefined
"medium"
故障动画的播放速度
详情

声明类型

ButtonGlitchSpeed | undefined

字面量

  • "fast"
  • "medium"
  • "slow"

关联类型

ButtonGlitchSpeed
类型定义 — ButtonGlitchSpeed
type ButtonGlitchSpeed = NonNullable<ButtonVariantProps['glitchSpeed']>

默认值详情

声明
'medium'

来源: packages/ui/src/components/button/Button.vue

解析值
"medium"

来源

Button.vue:47

packages/ui/src/components/button/Button.vue

glitchDirection
ButtonGlitchDirection | undefined
"horizontal"
故障动画的撕裂方向
详情

声明类型

ButtonGlitchDirection | undefined

字面量

  • "both"
  • "horizontal"
  • "vertical"

关联类型

ButtonGlitchDirection
类型定义 — ButtonGlitchDirection
type ButtonGlitchDirection = NonNullable<ButtonVariantProps['glitchDirection']>

默认值详情

声明
'horizontal'

来源: packages/ui/src/components/button/Button.vue

解析值
"horizontal"

来源

Button.vue:49

packages/ui/src/components/button/Button.vue

class
string | undefined
undefined
合并到按钮根元素上的补充 CSS 类名。
详情

声明类型

string | undefined

默认值详情

声明
undefined

来源: packages/ui/src/components/button/Button.vue

解析值
undefined

来源

Button.vue:50

packages/ui/src/components/button/Button.vue

Button — 事件
名称签名或类型说明
@click
MouseEvent
渲染根元素的原生点击事件通过 Vue 属性透传交给使用方监听；Button 本身不声明同名自定义事件。
  • 当 disabled 或 loading 为真时，组件内部点击处理器会调用 preventDefault() 和 stopPropagation()；原生按钮模式同时设置 disabled，asChild 模式使用 aria-disabled 与 pointer-events-none。
详情

声明类型

MouseEvent

来源

Button.vue

packages/ui/src/components/button/Button.vue

Button — 插槽
名称签名或类型说明
#default
{}
按钮主体内容。未提供插槽内容时，只有在 type="submit" 且 loading 为真时才显示等待文本；显式插槽内容优先。
详情

声明类型

{}

来源

Button.vue

packages/ui/src/components/button/Button.vue

Button — 暴露成员
名称签名或类型说明
play
() => void
手动激活故障动画。仅在 effect="glitch" 时生效；此方法绕过触发方式和禁用状态的检查，但减少动态效果偏好仍会隐藏动画。
详情

声明类型

() => void

来源

Button.vue:211

packages/ui/src/components/button/Button.vue

stop
() => void
立即关闭故障动画状态。
详情

声明类型

() => void

来源

Button.vue:212

packages/ui/src/components/button/Button.vue

可访问性 ​

  • 键盘操作：支持 Space / Enter 触发点击
  • ARIA 属性：禁用状态自动设置 disabled 属性（非 asChild 模式）或 aria-disabled="true"（asChild 模式）；加载状态自动设置 aria-busy="true"
  • 焦点管理：支持键盘导航和焦点样式（focus:outline）

蛮力铸就。

© 2026 BrutxUI · MIT License