开发预览更新于 2026-05-10

IconButton 图标按钮

仅图标的方形按钮，必须配 aria-label；常用于 toolbar、表头列操作、输入后缀。

基础用法

3 个 variant（default / primary / danger），3 档尺寸（sm / md / lg），形状 square / round。

pressed 用于 toggle 行为（pin / bookmark），自动设 aria-pressed。

背景

<script setup lang="ts">
import { CfIconButton } from '@chufix-design/vue';
</script>

<template>
  <div class="demo-row">
    <CfIconButton aria-label="刷新">
      <svg viewBox="0 0 16 16" fill="none"><path d="M3 8a5 5 0 1 1 1.5 3.5M3 8V5m0 3h3" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>
    </CfIconButton>
    <CfIconButton variant="primary" aria-label="保存">
      <svg viewBox="0 0 16 16" fill="none"><path d="M3 8.5l3.2 3.2L13 5" stroke="currentColor" stroke-width="2" stroke-linecap="round"/></svg>
    </CfIconButton>
    <CfIconButton variant="danger" aria-label="删除">
      <svg viewBox="0 0 16 16" fill="none"><path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>
    </CfIconButton>
    <CfIconButton :pressed="true" aria-label="固定">
      <svg viewBox="0 0 16 16" fill="none"><path d="M8 2v8m0 4v.01M5 5h6" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/></svg>
    </CfIconButton>
  </div>
</template>

<CfIconButton aria-label="保存" variant="primary"><Icon /></CfIconButton>
<CfIconButton aria-label="删除" variant="danger"><Icon /></CfIconButton>
<CfIconButton aria-label="固定" pressed><Icon /></CfIconButton>

尺寸与形状

3 档尺寸（sm 26 / md 32 / lg 38 px）。shape="round" 切到圆形（pill）。

背景

<script setup lang="ts">
import { CfIconButton } from '@chufix-design/vue';
const star = `<svg viewBox="0 0 16 16" fill="none"><path d="M8 2l1.9 4 4.4.4-3.3 3 .9 4.3L8 11.5 4.1 13.7l.9-4.3-3.3-3 4.4-.4z" stroke="currentColor" stroke-width="1.4" stroke-linejoin="round"/></svg>`;
</script>

<template>
  <div class="demo-row" style="align-items: center; gap: 16px;">
    <CfIconButton size="sm" aria-label="星标 (sm)"><span v-html="star" style="display: contents;"/></CfIconButton>
    <CfIconButton size="md" aria-label="星标 (md)"><span v-html="star" style="display: contents;"/></CfIconButton>
    <CfIconButton size="lg" aria-label="星标 (lg)"><span v-html="star" style="display: contents;"/></CfIconButton>
    <span style="width: 1px; height: 24px; background: var(--line-1); margin: 0 8px;" />
    <CfIconButton size="md" shape="round" aria-label="圆形"><span v-html="star" style="display: contents;"/></CfIconButton>
    <CfIconButton size="lg" shape="round" aria-label="圆形 lg"><span v-html="star" style="display: contents;"/></CfIconButton>
  </div>
</template>

<CfIconButton size="sm" aria-label="星标" />
<CfIconButton size="md" aria-label="星标" />
<CfIconButton size="lg" aria-label="星标" />
<CfIconButton shape="round" aria-label="圆形" />

状态

pressed 切换 toggle 状态（自动设 aria-pressed），loading 与 disabled 分别给出 spinner 与禁用样式。

背景

已固定

<script setup lang="ts">
import { ref } from 'vue';
import { CfIconButton } from '@chufix-design/vue';
const pinned = ref(true);
const liked = ref(false);
const star = `<svg viewBox="0 0 16 16" fill="none"><path d="M8 2l1.9 4 4.4.4-3.3 3 .9 4.3L8 11.5 4.1 13.7l.9-4.3-3.3-3 4.4-.4z" stroke="currentColor" stroke-width="1.4" stroke-linejoin="round"/></svg>`;
</script>

<template>
  <div class="demo-row" style="align-items: center; gap: 16px;">
    <CfIconButton :pressed="pinned" aria-label="固定" @click="pinned = !pinned">
      <span v-html="star" style="display: contents;"/>
    </CfIconButton>
    <CfIconButton :pressed="liked" variant="danger" aria-label="收藏" @click="liked = !liked">
      <span v-html="star" style="display: contents;"/>
    </CfIconButton>
    <CfIconButton loading aria-label="加载中">
      <span v-html="star" style="display: contents;"/>
    </CfIconButton>
    <CfIconButton disabled aria-label="禁用">
      <span v-html="star" style="display: contents;"/>
    </CfIconButton>
    <span v-if="pinned" style="font-size: 12px; color: var(--accent-1); font-family: var(--font-mono);">已固定</span>
    <span v-if="liked" style="font-size: 12px; color: var(--status-error); font-family: var(--font-mono);">已收藏</span>
  </div>
</template>

<CfIconButton pressed aria-label="固定" />
<CfIconButton variant="danger" pressed aria-label="收藏" />
<CfIconButton loading aria-label="加载中" />
<CfIconButton disabled aria-label="禁用" />

API

属性	类型	默认值	说明
`variant`	`'default' \| 'primary' \| 'danger'`	`'default'`	视觉变体
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	尺寸
`shape`	`'square' \| 'round'`	`'square'`	形状
`pressed`	`boolean`	`false`	toggle 状态，输出 `aria-pressed`
`loading`	`boolean`	`false`	显示 spinner
`disabled`	`boolean`	`false`	禁用
默认槽 / `children`	—	—	图标内容
`badge` 槽 / `badge` prop	—	—	右上角徽章

a11y：必须传 aria-label，否则屏幕阅读器无法识别按钮含义。