按钮 Button
一个常见的按钮，是用于触发功能的控件。
按钮主题
按钮有 'primary'（默认）、'success'、'warning'、'danger'、'info'、'sakura' 六种主题。
<template>
<px-space>
<px-button>Primary</px-button>
<px-button theme="success">Success</px-button>
<px-button theme="warning">Warning</px-button>
<px-button theme="danger">Danger</px-button>
<px-button theme="info">Info</px-button>
<px-button theme="sakura">Sakura</px-button>
</px-space>
</template>按钮变体
按钮有 'primary'（默认）、'plain'、'outline'、'text' 四种样式变体。
<template>
<px-space direction="vertical">
<px-space v-for="variant in variants" :key="variant" style="margin-bottom: 8px">
<px-button
v-for="theme in themes"
:key="theme"
:variant="variant !== 'default' ? variant : undefined"
:theme="theme !== 'default' ? theme : undefined"
style="margin-right: 8px"
>
{{ variantLabels[variant] }}
</px-button>
</px-space>
</px-space>
</template>
<script setup>
const variants = ['default', 'plain', 'outline', 'text']
const themes = ['default', 'success', 'warning', 'danger', 'info', 'sakura']
const variantLabels = {
default: 'Primary',
plain: 'Plain',
outline: 'Outline',
text: 'Text'
}
</script>按钮形状
按钮有 'default'（默认）、'round'、'circle'、'square' 四种形状。
<template>
<px-space>
<px-button>Default</px-button>
<px-button shape="round">Round</px-button>
<px-button shape="circle">C</px-button>
<px-button shape="square">S</px-button>
</px-space>
</template>按钮尺寸
可以设置 size 属性改变按钮的样式，有 'default'（默认）、'small'、'large' 三种。
<template>
<px-space>
<px-button size="small">Small</px-button>
<px-button>Default</px-button>
<px-button size="large">Large</px-button>
</px-space>
</template>禁用状态
disabled 设置按钮禁用。
<template>
<px-button disabled>No Allow</px-button>
</template>加载状态
loading 设置按钮是否处于加载状态，加载状态时按钮的原生属性 disabled="true"，不会响应 click 事件。
<template>
<px-space>
<px-button style="margin-right: 8px" loading>Loading</px-button>
<px-button loading disabled>Loading</px-button>
</px-space>
</template>按钮图标
icon 插槽设置按钮图标。
<template>
<px-button>
<template #icon>
<IconMinds></IconMinds>
</template>
Icon
</px-button>
</template>
<script setup lang="ts">
import { IconMinds } from '@pixelium/web-vue/icon-hn/es'
</script>占据整行
设置 block 属性可以使得按钮占据整行。
<template>
<px-button block>Block</px-button>
</template>自定义颜色
自定义主色，内部基于此生成完整色板，该色板优先级高于 theme 提供的预设色版。支持类似 CSS 的 'rgb(r, g, b)' 和 'rgba(r, g, b, a)'字符串和 3、4、6、8位长度的十六位数字表示。
<template>
<px-space>
<px-button color="#409EFF">#409EFF</px-button>
<px-button color="#FAE13C">#FAE13C</px-button>
<px-button color="#E956AE">#E956AE</px-button>
<px-button color="#909399">#909399</px-button>
</px-space>
</template>圆角边框
borderRadius 设置按钮圆角，优先级高于 shape，与 CSS border-radius 行为一致。
精力和技术力不太充足，自定义圆角还有需要优化的地方，但整体不影响使用。
- 单值或长度为 1 的数组 → 四角同时生效；
- 长度为 2 的数组 → [左上 & 右下, 右上 & 左下]；
- 长度为 3 的数组 → [左上, 右上 & 左下, 右下]；
- 长度为 4 的数组 → 按顺时针顺序依次作用于四角。
<template>
<px-space>
<px-button :border-radius="12">12</px-button>
<px-button :border-radius="[12, 8]">[12, 8]</px-button>
<px-button :border-radius="[12, 8, 20]">[12, 8, 20]</px-button>
<px-button :border-radius="[20, 8, 20, 16]">[20, 8, 20, 16]</px-button>
</px-space>
</template>按钮组
使用 ButtonGroup 组件可以像这样子把按钮放在一起。
<template>
<px-space direction="vertical">
<px-button-group>
<px-button>Primary</px-button>
<px-button theme="sakura">Sakura</px-button>
<px-button color="#E956AE" variant="plain">#E956AE</px-button>
<px-button loading>Loading</px-button>
</px-button-group>
<px-button-group shape="round">
<px-button>Primary</px-button>
<px-button theme="sakura">Sakura</px-button>
<px-button color="#E956AE" variant="plain">#E956AE</px-button>
<px-button loading>Loading</px-button>
</px-button-group>
<px-button-group loading>
<px-button>Primary</px-button>
<px-button theme="sakura">Sakura</px-button>
<px-button color="#E956AE" variant="plain">#E956AE</px-button>
<px-button disabled>Loading</px-button>
</px-button-group>
<px-button-group variant="outline">
<px-button>Primary</px-button>
<px-button theme="sakura">Sakura</px-button>
<px-button color="#E956AE" variant="plain">#E956AE</px-button>
<px-button loading>Loading</px-button>
</px-button-group>
<px-button-group :border-radius="[20, 16, 20, 16]">
<px-button>Primary</px-button>
<px-button theme="sakura">Sakura</px-button>
<px-button color="#E956AE" variant="plain">#E956AE</px-button>
<px-button loading>Loading</px-button>
</px-button-group>
</px-space>
</template>API
ButtonProps
| 属性 | 类型 | 可选 | 默认值 | 描述 | 版本 |
|---|---|---|---|---|---|
| borderRadius | NumberOrPercentage | NumberOrPercentage[] | 是 | | 圆角半径，优先级高于 shape，与 CSS border-radius 行为一致；单值或长度为 1 的数组 → 四角同时生效；长度为 2 的数组 → [左上 & 右下, 右上 & 左下]；长度为 3 的数组 → [左上, 右上 & 左下, 右下]；长度为 4 的数组 → 按顺时针顺序依次作用于四角。 | 0.0.0-beta |
| shape | 'default' | 'round' | 'circle' | 'square' | 是 | 'default' | 按钮形状。 | 0.0.0-beta |
| size | 'medium' | 'large' | 'small' | 是 | 'medium' | 按钮尺寸。 | 0.0.0-beta |
| disabled | boolean | 是 | false | 是否禁用。 | 0.0.0-beta |
| loading | boolean | 是 | false | 是否加载状态。 | 0.0.0-beta |
| variant | 'primary' | 'plain' | 'text' | 'outline' | 是 | 'primary' | 按钮样式变体。 | 0.0.0-beta |
| theme | 'primary' | 'sakura' | 'success' | 'warning' | 'danger' | 'info' | 是 | 'primary' | 按钮主题。 | 0.0.0-beta |
| color | string | 是 | | 自定义主色，内部基于此生成完整色板，该色板优先级高于 theme 提供的预设色版。支持类似 CSS 的 'rgb(r, g, b)' 和 'rgba(r, g, b, a)' 字符串和 3、4、6、8 位长度的十六位数字表示。 | 0.0.0-beta |
| block | boolean | 是 | false | 是否占据整行。 | 0.0.0-beta |
| nativeType | 'button' | 'submit' | 'reset' | 是 | 'button' | HTML <button> 原生 type 属性。 | 0.0.0-beta |
| autofocus | boolean | 是 | false | HTML <button> 原生 autofocus 属性。 | 0.0.0-beta |
ButtonEvents
| 事件 | 参数 | 描述 | 版本 |
|---|---|---|---|
| click | e: MouseEvent | 点击事件。 | 0.0.0-beta |
ButtonSlots
| 插槽 | 参数 | 描述 | 版本 |
|---|---|---|---|
| default | | 按钮内容。 | 0.0.0-beta |
| icon | | 按钮图标。 | 0.0.0-beta |
ButtonGroupProps
| 属性 | 类型 | 可选 | 默认值 | 描述 | 版本 |
|---|---|---|---|---|---|
| borderRadius | NumberOrPercentage | NumberOrPercentage[] | 是 | | 圆角半径，优先级高于 shape，将覆盖 Button 子组件的 borderRadius，圆角仅作用于两侧 Button 子组件的外侧边框。与 CSS border-radius 行为一致；单值或长度为 1 的数组 → 四角同时生效；长度为 2 的数组 → [左上 & 右下, 右上 & 左下]；长度为 3 的数组 → [左上, 右上 & 左下, 右下]；长度为 4 的数组 → 按顺时针顺序依次作用于四角。 | 0.0.0-beta |
| shape | 'default' | 'round' | 是 | 'default' | 按钮形状，将覆盖 Button 子组件的 shape，圆角仅作用于两侧 Button 子组件的外侧边框。 | 0.0.0-beta |
| size | 'medium' | 'large' | 'small' | 是 | 'medium' | 按钮尺寸，将覆盖 Button 子组件的 size。 | 0.0.0-beta |
| disabled | boolean | 是 | false | 是否禁用，Button 子组件的 disabled 和当前属性取或，决定该子组件是否禁用。 | 0.0.0-beta |
| loading | boolean | 是 | false | 是否加载状态，Button 子组件的 loading 和当前属性取或，决定该子组件是否加载状态。 | 0.0.0-beta |
| variant | 'primary' | 'plain' | 'text' | 'outline' | 是 | | 按钮样式变体，Button 子组件的 variant 和当前属性取或，决定该子组件的样式变体。 | 0.0.0-beta |
ButtonGroupSlots
| 插槽 | 参数 | 描述 | 版本 |
|---|---|---|---|
| default | | 子按钮。 | 0.0.0-beta |
NumberOrPercentage
ts
export type NumberOrPercentage = number | `${number}%`1