Button 按钮

常用的操作按钮，具有像素风格的视觉效果。

名称	分类	说明	类型	默认值
`type`	风格	按钮类型	`'primary' \| 'success' \| 'warning' \| 'danger' \| 'info'`	—
`plain`	风格	是否为朴素按钮	`boolean`	`false`
`round`	风格	是否为圆角按钮	`boolean`	`false`
`circle`	风格	是否为圆形按钮	`boolean`	`false`
`dash`	风格	是否为虚线边框按钮	`boolean`	`false`
`ghost`	风格	是否为幽灵按钮（无边框/背景）	`boolean`	`false`
`link`	风格	是否为链接按钮（下划线文字样式）	`boolean`	`false`
`block`	风格	是否为块级按钮（撑满父容器宽度）	`boolean`	`false`
`responsive`	风格	是否为响应式按钮（根据视口自适应尺寸）	`boolean`	`false`
`size`	尺寸	按钮尺寸	`'large' \| 'default' \| 'small'`	`'default'`
`color`	颜色	自定义按钮颜色（十六进制）	`string`	—
`loading`	状态	是否为加载状态	`boolean`	`false`
`disabled`	状态	是否禁用	`boolean`	`false`
`autofocus`	行为	是否自动聚焦	`boolean`	`false`
`native-type`	行为	原生 type 属性	`'button' \| 'submit' \| 'reset'`	`'button'`
`use-throttle`	行为	是否启用节流	`boolean`	`false`
`throttle-duration`	行为	节流时间（毫秒）	`number`	`500`
`loading-icon`	内容	自定义加载图标	`string`	`'spinner'`
`icon`	内容	图标名称	`string`	—
`tag`	内容	自定义元素标签	`string`	`'button'`
`aria-label`	内容	按钮的 ARIA 标签，用于无障碍访问	`string`	—
`click`	事件	点击按钮时触发	`(event: MouseEvent) => void`	—
`default`	插槽	按钮内容		—
`loading`	插槽	自定义加载图标		—
`ref`	暴露	按钮 HTML 元素	`Ref<HTMLButtonElement>`	—
`size`	暴露	按钮尺寸	`ComputedRef<string>`	—
`type`	暴露	按钮类型	`ComputedRef<string>`	—
`disabled`	暴露	是否禁用	`ComputedRef<boolean>`	—

基础用法

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

<template>
  <div class="demo-button">
    <div class="row">
      <px-button>Default</px-button>
      <px-button type="primary">Primary</px-button>
      <px-button type="success">Success</px-button>
      <px-button type="info">Info</px-button>
      <px-button type="warning">Warning</px-button>
      <px-button type="danger">Danger</px-button>
    </div>
    <div class="row">
      <px-button plain>Plain</px-button>
      <px-button type="primary" plain>Primary</px-button>
      <px-button type="success" plain>Success</px-button>
      <px-button type="info" plain>Info</px-button>
      <px-button type="warning" plain>Warning</px-button>
      <px-button type="danger" plain>Danger</px-button>
    </div>
    <div class="row">
      <px-button round>Round</px-button>
      <px-button type="primary" round>Primary</px-button>
      <px-button type="success" round>Success</px-button>
      <px-button type="info" round>Info</px-button>
      <px-button type="warning" round>Warning</px-button>
      <px-button type="danger" round>Danger</px-button>
    </div>
    <div class="row">
      <px-button icon="search" circle />
      <px-button type="primary" icon="edit" circle />
      <px-button type="success" icon="check" circle />
      <px-button type="info" icon="message" circle />
      <px-button type="warning" icon="alert" circle />
      <px-button type="danger" icon="trash" circle />
    </div>
  </div>
</template>

<style scoped>
.demo-button {
  display: flex;
  flex-direction: column;
  gap: 20px;
}
.row {
  display: grid;
  grid-template-columns: repeat(6, auto);
  justify-content: start;
  align-items: center;
  gap: 10px;
}
</style>

禁用状态

使用 disabled 属性来禁用按钮。

<template>
  <div class="demo-button">
    <div class="row">
      <px-button>Default</px-button>
      <px-button type="primary">Primary</px-button>
      <px-button type="success">Success</px-button>
      <px-button type="info">Info</px-button>
      <px-button type="warning">Warning</px-button>
      <px-button type="danger">Danger</px-button>
    </div>
    <div class="row">
      <px-button disabled>Default</px-button>
      <px-button type="primary" disabled>Primary</px-button>
      <px-button type="success" disabled>Success</px-button>
      <px-button type="info" disabled>Info</px-button>
      <px-button type="warning" disabled>Warning</px-button>
      <px-button type="danger" disabled>Danger</px-button>
    </div>
  </div>
</template>

<style scoped>
.demo-button {
  display: flex;
  flex-direction: column;
  gap: 20px;
}
.row {
  display: grid;
  grid-template-columns: repeat(6, auto);
  justify-content: start;
  align-items: center;
  gap: 12px;
}
</style>

不同尺寸

使用 size 属性来设置按钮的大小。

<template>
  <div class="demo-size">
    <div class="row">
      <px-button size="large">Large</px-button>
      <px-button>Default</px-button>
      <px-button size="small">Small</px-button>
      <px-button size="large" round>Large</px-button>
      <px-button round>Default</px-button>
      <px-button size="small" round>Small</px-button>
    </div>
    <div class="row">
      <px-button size="large" icon="search" circle />
      <px-button icon="search" circle />
      <px-button size="small" icon="search" circle />
    </div>
  </div>
</template>

<style scoped>
.demo-size {
  display: flex;
  flex-direction: column;
  gap: 10px;
}
.row {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
  gap: 10px;
}
.row :deep(.px-button + .px-button) {
  margin-left: 0;
}
</style>

图标按钮

使用 icon 属性来为按钮添加图标。

<template>
  <div class="row">
    <px-button type="primary" icon="edit" />
    <px-button type="primary" icon="link" />
    <px-button type="primary" icon="trash" />
    <px-button type="primary" icon="search">Search</px-button>
    <px-button type="primary">
      Upload<px-icon icon="upload" style="margin-left: 8px" />
    </px-button>
  </div>
</template>

<style scoped>
.row {
  display: flex;
  align-items: center;
  gap: 12px;
}
</style>

虚线边框

使用 dash 属性来应用虚线边框样式。像素 clip-path 边框将替换为 CSS 虚线边框，呈现手绘/剪纸风格。

<template>
  <div class="row">
    <px-button dash>Default</px-button>
    <px-button type="primary" dash>Primary</px-button>
    <px-button type="success" dash>Success</px-button>
    <px-button type="info" dash>Info</px-button>
    <px-button type="warning" dash>Warning</px-button>
    <px-button type="danger" dash>Danger</px-button>
  </div>
</template>

<style scoped>
.row {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
  gap: 10px;
}
.row :deep(.px-button + .px-button) {
  margin-left: 0;
}
</style>

幽灵按钮

使用 ghost 属性来创建无边框、无背景的按钮。仅文字可见，悬停时出现淡色填充。

<template>
  <div class="row">
    <px-button ghost>Default</px-button>
    <px-button type="primary" ghost>Primary</px-button>
    <px-button type="success" ghost>Success</px-button>
    <px-button type="info" ghost>Info</px-button>
    <px-button type="warning" ghost>Warning</px-button>
    <px-button type="danger" ghost>Danger</px-button>
  </div>
</template>

<style scoped>
.row {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
  gap: 10px;
}
.row :deep(.px-button + .px-button) {
  margin-left: 0;
}
</style>

链接按钮

使用 link 属性来创建下划线文字按钮，无边框、无背景、无阴影。适用于内联操作或超链接风格的交互。

<template>
  <div class="row">
    <px-button link>Default</px-button>
    <px-button type="primary" link>Primary</px-button>
    <px-button type="success" link>Success</px-button>
    <px-button type="info" link>Info</px-button>
    <px-button type="warning" link>Warning</px-button>
    <px-button type="danger" link>Danger</px-button>
  </div>
</template>

<style scoped>
.row {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
  gap: 10px;
}
.row :deep(.px-button + .px-button) {
  margin-left: 0;
}
</style>

块级按钮

使用 block 属性使按钮撑满父容器的宽度。

<template>
  <div class="column">
    <px-button block>Default Block</px-button>
    <px-button type="primary" block>Primary Block</px-button>
    <px-button type="success" block>Success Block</px-button>
  </div>
</template>

<style scoped>
.column {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 400px;
}
</style>

响应式按钮

使用 responsive 属性使按钮根据视口宽度自动调整尺寸。

断点	宽度	高度	字体大小
基础	< 640px	24px	超小
sm	≥ 640px	28px	小
md	≥ 768px	36px	基础
lg	≥ 1024px	44px	大
xl	≥ 1280px	44px	大（更宽内边距）

<template>
  <div class="row">
    <px-button responsive>Responsive</px-button>
    <px-button type="primary" responsive>Primary</px-button>
    <px-button type="success" responsive>Success</px-button>
  </div>
  <p class="hint">↔ Resize your browser window to see the button adapt.</p>
</template>

<style scoped>
.row {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
  gap: 10px;
}
.row :deep(.px-button + .px-button) {
  margin-left: 0;
}
.hint {
  margin-top: 12px;
  font-size: 12px;
  color: var(--px-text-color-secondary);
}
</style>

加载状态

使用 loading 属性来设置按钮的加载状态。

<template>
  <div class="row">
    <px-button type="primary" loading>Loading</px-button>
    <px-button type="primary" loading-icon="loader" loading
      >Loading</px-button
    >
    <px-button type="primary" loading>
      <template #loading>
        <px-icon style="margin-right: 6px" icon="bookmark" spin />
      </template>
      Loading
    </px-button>
  </div>
</template>

<style scoped>
.row {
  display: flex;
  align-items: center;
  gap: 12px;
}
</style>

按钮组

使用 <px-button-group> 组件来嵌套多个按钮。

<template>
  <div class="demo-button">
    <div class="row">
      <px-button-group disabled>
        <px-button type="primary" icon="arrow-left">Previous Page</px-button>
        <px-button type="primary">
          Next Page<px-icon icon="arrow-right" style="margin-left: 8px" />
        </px-button>
      </px-button-group>
    </div>
    <div class="row">
      <px-button-group type="warning" size="small">
        <px-button type="primary" icon="edit" round />
        <px-button type="primary" icon="link" />
        <px-button type="primary" icon="trash" round />
      </px-button-group>
    </div>
  </div>
</template>

<style scoped>
.demo-button {
  display: flex;
  flex-direction: column;
  gap: 20px;
}
.row {
  display: flex;
  align-items: center;
  gap: 12px;
}
</style>

自定义颜色

使用 color 属性来设置按钮的自定义颜色。文字颜色、悬停状态、激活状态和禁用状态会根据提供的颜色自动生成。

<template>
  <div class="demo-button">
    <div class="row">
      <px-button color="#626aef">Indigo</px-button>
      <px-button color="#ff6b9d">Pink</px-button>
      <px-button color="#36cfc9">Teal</px-button>
      <px-button color="#fac858">Gold</px-button>
      <px-button color="#ee6666">Coral</px-button>
      <px-button color="#3ba272">Emerald</px-button>
    </div>
    <div class="row">
      <px-button color="#626aef" plain>Indigo</px-button>
      <px-button color="#ff6b9d" plain>Pink</px-button>
      <px-button color="#36cfc9" plain>Teal</px-button>
      <px-button color="#fac858" plain>Gold</px-button>
      <px-button color="#ee6666" plain>Coral</px-button>
      <px-button color="#3ba272" plain>Emerald</px-button>
    </div>
    <div class="row">
      <px-button color="#626aef" disabled>Indigo</px-button>
      <px-button color="#ff6b9d" disabled>Pink</px-button>
      <px-button color="#36cfc9" disabled>Teal</px-button>
      <px-button color="#fac858" disabled>Gold</px-button>
      <px-button color="#ee6666" disabled>Coral</px-button>
      <px-button color="#3ba272" disabled>Emerald</px-button>
    </div>
    <div class="row">
      <px-button color="#626aef" icon="edit" circle />
      <px-button color="#ff6b9d" icon="heart" circle />
      <px-button color="#36cfc9" icon="check" circle />
      <px-button color="#fac858" icon="bookmark" circle />
      <px-button color="#ee6666" icon="trash" circle />
      <px-button color="#3ba272" icon="link" circle />
    </div>
  </div>
</template>

<style scoped>
.demo-button {
  display: flex;
  flex-direction: column;
  gap: 20px;
}
.row {
  display: grid;
  grid-template-columns: repeat(6, auto);
  justify-content: start;
  align-items: center;
  gap: 12px;
}
</style>

登录按钮

结合 icon 和 color 属性来创建社交登录按钮。所有 486 个 pixelarticons 图标已内置，github 和 mail 等图标开箱即用。

<template>
  <div class="login-demo">
    <px-button icon="mail" color="#000000">Login with Email</px-button>
    <px-button icon="github" color="#24292f">Login with GitHub</px-button>
  </div>
</template>

<style scoped>
.login-demo {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-width: 320px;
}
.login-demo :deep(.px-button) {
  width: 100%;
  justify-content: center;
}
.login-demo :deep(.px-button + .px-button) {
  margin-left: 0;
}
</style>

像素 3D 效果

按钮带有自动斜面高光效果——左上方的亮色内嵌和右下方的暗色内嵌——营造出凸起的像素表面，灵感来自经典 RPG UI 和 Windows 95。点击时斜面翻转，产生按下的手感。扁平样式（ghost、link、dash）和禁用按钮没有斜面效果。

自定义标签

使用 tag 属性来自定义按钮的 HTML 标签。

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

<style scoped>
.row {
  display: flex;
  align-items: center;
  flex-wrap: wrap;
  gap: 10px;
}
</style>

节流模式

使用 use-throttle 和 throttle-duration 属性来启用节流模式。

<script setup>
function handleBtnClick() {}
</script>

<template>
  <div class="row">
    <px-button @click="handleBtnClick">with throttle</px-button>
    <px-button :use-throttle="false" @click="handleBtnClick"
      >without throttle</px-button
    >
  </div>
</template>

<style scoped>
.row {
  display: flex;
  align-items: center;
  gap: 12px;
}
</style>

Button 按钮 ​

基础用法 ​

禁用状态 ​

不同尺寸 ​

图标按钮 ​

虚线边框 ​

幽灵按钮 ​

链接按钮 ​

块级按钮 ​

响应式按钮 ​

加载状态 ​

按钮组 ​

自定义颜色 ​

登录按钮 ​

像素 3D 效果 ​

自定义标签 ​

节流模式 ​