Button 按钮

用于触发操作，如提交表单、保存内容或删除记录。

基础用法

solid 适合主要操作，outline 使用白底、正文色和细边框，适合次要操作，ghost 适合低优先级操作，link 使用主题色文字，无内边距、边框和固定控件高度。页面跳转使用 Link 组件。

主按钮和描边按钮点击时，外缘波纹快速扩散后缓慢淡出，按钮与文字保持稳定；文字和链接按钮不展示波纹。主按钮悬停时提亮、按下时加深；描边按钮保持底色，通过文字和边框变色反馈。危险操作使用红色，波纹跟随主题；关闭动效或启用系统减少动态效果后不展示波纹。

variants.tsx

import { Button, Space } from '@ifhover/leaf-ui';

export function ButtonVariants() {
  return (
    <Space wrap>
      <Button>主要按钮</Button>
      <Button variant="outline">描边按钮</Button>
      <Button variant="ghost">文字按钮</Button>
      <Button variant="link">链接按钮</Button>
    </Space>
  );
}

组件样式会自动加载，接入步骤见快速开始。

危险操作

为删除、清空、撤销等操作使用 danger。所有样式、图标和加载状态都会使用独立的红色语义主题。

danger.tsx

import { Button, Space } from '@ifhover/leaf-ui';

import { Trash2 } from 'lucide-react';

export function ButtonDanger() {
  return (
    <Space wrap>
      <Button danger startIcon={<Trash2 />}>
        删除项目
      </Button>
      <Button danger variant="outline">
        撤销授权
      </Button>
      <Button danger variant="ghost">
        清空
      </Button>
      <Button danger disabled>
        禁止删除
      </Button>
      <Button danger loading>
        正在删除
      </Button>
    </Space>
  );
}

尺寸

提供小、中、大三种尺寸，适配不同密度的操作区。外观可通过主题变量定制。

sizes.tsx

import { Button, Space } from '@ifhover/leaf-ui';

export function ButtonSizes() {
  return (
    <Space wrap>
      <Button size="sm">小按钮</Button>
      <Button size="md">默认按钮</Button>
      <Button size="lg">大按钮</Button>
    </Space>
  );
}

禁用与加载

加载时会显示旋转指示器，自动禁用按钮，并设置 aria-busy。原有文字保留，帮助用户理解正在进行的操作。

states.tsx

import { Button, Space } from '@ifhover/leaf-ui';

export function ButtonStates() {
  return (
    <Space wrap>
      <Button disabled>暂不可用</Button>
      <Button loading>加载中</Button>
      <Button variant="outline" disabled>
        已禁用
      </Button>
    </Space>
  );
}

实际交互

通过应用状态控制 loading。下面的示例会在 1.2 秒后完成保存；实际使用时，把计时器替换成你的异步业务操作。

点击试试保存操作。

loading.tsx

import { Button, Space } from '@ifhover/leaf-ui';

import { useEffect, useRef, useState } from 'react';

export function ButtonLoading() {
  const [status, setStatus] = useState<'idle' | 'loading' | 'saved'>('idle');
  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);

  useEffect(() => () => clearTimeout(timer.current), []);

  function save() {
    clearTimeout(timer.current);
    setStatus('loading');
    // 示例模拟一次异步保存；实际使用时替换成你的业务请求。
    timer.current = setTimeout(() => setStatus('saved'), 1200);
  }

  return (
    <Space wrap>
      <Button loading={status === 'loading'} onClick={save}>
        {status === 'loading' ? '正在保存' : status === 'saved' ? '再次保存' : '保存更改'}
      </Button>
      <span role="status">{status === 'saved' ? '更改已保存。' : '点击试试保存操作。'}</span>
    </Space>
  );
}

图标

示例使用 lucide-react 的按需导入图标。startIcon 和 endIcon 接受 React 节点。图标容器默认对辅助技术隐藏，按钮文字提供名称；只有图标时请设置 aria-label。

icons.tsx

import { Button, Space } from '@ifhover/leaf-ui';

import { ArrowRight, Plus, Trash2 } from 'lucide-react';

export function ButtonIcons() {
  return (
    <Space wrap>
      <Button startIcon={<Plus />}>新建项目</Button>
      <Button variant="outline" endIcon={<ArrowRight />}>
        继续下一步
      </Button>
      <Button variant="outline" aria-label="添加项目" startIcon={<Plus />} />
      <Button danger variant="outline" aria-label="删除项目" startIcon={<Trash2 />} />
    </Space>
  );
}

整行显示

fullWidth 让按钮填满父容器宽度，适合表单提交和移动端操作区。

full-width.tsx

import { Button } from '@ifhover/leaf-ui';

export function ButtonFullWidth() {
  return <Button fullWidth>继续下一步</Button>;
}

扩展用法

按钮组

分裂按钮

extensions.tsx

import { Button, ButtonGroup, Flex, Space, SplitButton, Text } from '@ifhover/leaf-ui';

export function ExtensionDemo() {
  return (
    <Space direction="vertical" align="start">
      <Flex direction="column" gap="sm" align="center">
        <Text>按钮组</Text>
        <ButtonGroup>
          <Button variant="outline">上一步</Button>
          <Button variant="outline">下一步</Button>
        </ButtonGroup>
      </Flex>
      <Flex direction="column" gap="sm" align="center">
        <Text>分裂按钮</Text>
        <SplitButton
          items={[
            { key: 'copy', label: '保存副本' },
            { key: 'draft', label: '存为草稿' },
          ]}
        >
          保存
        </SplitButton>
      </Flex>
    </Space>
  );
}

Button API

属性	类型	默认值	说明
`variant`	`'solid' \| 'outline' \| 'ghost' \| 'link'`	`'solid'`	视觉样式
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	按钮尺寸
`danger`	`boolean`	`false`	使用红色危险语义，支持所有 variant
`loading`	`boolean`	`false`	显示加载指示器并禁用交互
`fullWidth`	`boolean`	`false`	填满父容器宽度
`startIcon`	`ReactNode`	—	文字前的图标，加载时由指示器替代
`endIcon`	`ReactNode`	—	文字后的图标
`disabled`	`boolean`	`false`	禁用交互。
`type`	`'button' \| 'submit' \| 'reset'`	`'button'`	原生按钮类型
`ref`	`Ref<HTMLButtonElement>`	—	按钮 DOM 引用

支持其他原生 button 属性，例如 onClick、name、value、form、className、style、aria-* 和 data-*。

类型

可导入 ButtonProps 定义组件属性，或单独使用以下样式、尺寸类型：

import type { ButtonProps, ButtonVariant, ButtonSize } from '@ifhover/leaf-ui';

表单与键盘

默认 type="button"，放进表单时不会意外提交。需要提交表单，请显式设置 type="submit"。

组件保留原生键盘行为：Tab 聚焦，Enter 或 Space 触发。禁用和加载状态会阻止交互；聚焦时显示清晰的焦点轮廓。

定制样式

<ConfigProvider theme={{ primaryColor: '#7654c6', borderRadius: 18 }}>
  <Button>自定义主题</Button>
</ConfigProvider>

配置选项与实时示例见定制主题。

扩展类型

import type { ButtonGroupProps, SplitButtonProps } from '@ifhover/leaf-ui';

ButtonGroupProps API

属性	类型	默认值	说明
`size`	`'sm' \| 'md' \| 'lg'`	—	尺寸或间距预设
`disabled`	`boolean`	—	禁用交互。
`attached`	`boolean`	`true`	连接相邻按钮

SplitButtonProps API

属性	类型	默认值	说明
`variant`	`'solid' \| 'outline' \| 'ghost' \| 'link'`	—	按钮样式
`size`	`'sm' \| 'md' \| 'lg'`	—	尺寸或间距预设
`danger`	`boolean`	—	危险操作颜色
`loading`	`boolean`	—	加载状态
`fullWidth`	`boolean`	—	占满宽度
`startIcon`	`ReactNode`	—	前置图标
`endIcon`	`ReactNode`	—	后置图标
`items`	`readonly DropdownItem[]`	必填	必需。数据项目，保持 key 唯一且稳定
`menuLabel`	`string`	—	菜单按钮的可访问名称
`dropdownProps`	`Omit<DropdownProps, 'items' \| 'children' \| 'disabled'>`	—	操作菜单属性

#Button 按钮

#基础用法

#危险操作

#尺寸

#禁用与加载

#实际交互

#图标

#整行显示

#扩展用法

#Button API

#类型

#表单与键盘

#定制样式

#扩展类型

#ButtonGroupProps API

#SplitButtonProps API