For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/button.md.

Button 按钮

触发保存、提交或删除等操作。

基础用法

按钮文字应清楚描述操作,点击事件通过 onClick 处理。

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

export function ButtonBasic() {
  return <Button>保存</Button>;
}

默认 type="button",不会提交表单。需要提交时,请设置 type="submit"。

示例

按钮外观

通过 variant 选择外观:默认描边、实底、文字或行内链接。行内链接默认使用主题色,悬停时文字变亮,按下时变深,默认颜色过渡为 200ms。

描边
实底
文字
链接
variants.tsx
import { Button, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';

const options = [
  { value: 'outline', label: '描边' },
  { value: 'solid', label: '实底' },
  { value: 'text', label: '文字' },
  { value: 'link', label: '链接' },
] as const;

export function ButtonVariants() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      {options.map(({ value, label }) => (
        <Fragment key={value}>
          <Text tone="muted">{label}</Text>
          <Flex align="center" wrap>
            <Button variant={value}>保存</Button>
          </Flex>
        </Fragment>
      ))}
    </Grid>
  );
}

尺寸

通过 size 设置尺寸,默认为 md。

小
中
大
sizes.tsx
import { Button, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';

const options = [
  { value: 'sm', label: '小' },
  { value: 'md', label: '中' },
  { value: 'lg', label: '大' },
] as const;

export function ButtonSizes() {
  return (
    <Grid gap={16} align="center" style={{ gridTemplateColumns: 'max-content minmax(0, 1fr)' }}>
      {options.map(({ value, label }) => (
        <Fragment key={value}>
          <Text tone="muted">{label}</Text>
          <Flex align="center" wrap>
            <Button size={value}>保存</Button>
          </Flex>
        </Fragment>
      ))}
    </Grid>
  );
}

危险操作

设置 danger 表示删除、清空等危险操作,可搭配任意外观。

描边
实底
文字
链接
danger.tsx
import { Button, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';

const options = [
  { value: 'outline', label: '描边' },
  { value: 'solid', label: '实底' },
  { value: 'text', label: '文字' },
  { value: 'link', label: '链接' },
] as const;

export function ButtonDanger() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      {options.map(({ value, label }) => (
        <Fragment key={value}>
          <Text tone="muted">{label}</Text>
          <Flex align="center" wrap>
            <Button danger variant={value}>
              删除
            </Button>
          </Flex>
        </Fragment>
      ))}
    </Grid>
  );
}

禁用与加载

disabled 禁用按钮;loading 显示加载指示器并阻止重复点击。

禁用
加载
states.tsx
import { Button, Flex, Grid, Text } from '@ifhover/leaf-ui';

export function ButtonStates() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">禁用</Text>
      <Flex align="center" wrap>
        <Button disabled>保存</Button>
      </Flex>
      <Text tone="muted">加载</Text>
      <Flex align="center" wrap>
        <Button loading>保存</Button>
      </Flex>
    </Grid>
  );
}

图标

通过 startIcon 和 endIcon 添加图标。只有图标时,必须提供 aria-label。

小
中
大
icons.tsx
import { Button, Flex, Grid, Text } from '@ifhover/leaf-ui';
import { ArrowRight, Plus, Trash2 } from 'lucide-react';
import { Fragment } from 'react';

const options = [
  { value: 'sm', label: '小' },
  { value: 'md', label: '中' },
  { value: 'lg', label: '大' },
] as const;

export function ButtonIcons() {
  return (
    <Grid gap={16} align="center" style={{ gridTemplateColumns: 'max-content minmax(0, 1fr)' }}>
      {options.map(({ value, label }) => (
        <Fragment key={value}>
          <Text tone="muted">{label}</Text>
          <Flex align="center" gap={8} wrap>
            <Button size={value} startIcon={<Plus />}>
              新建项目
            </Button>
            <Button size={value} variant="outline" endIcon={<ArrowRight />}>
              继续下一步
            </Button>
            <Button size={value} variant="outline" aria-label="添加项目" startIcon={<Plus />} />
            <Button
              size={value}
              danger
              variant="outline"
              aria-label="删除项目"
              startIcon={<Trash2 />}
            />
          </Flex>
        </Fragment>
      ))}
    </Grid>
  );
}

整行显示

设置 fullWidth,让按钮填满父容器。

full-width.tsx
import { Button } from '@ifhover/leaf-ui';

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

异步保存

通过应用状态控制 loading。示例使用定时器模拟请求,实际使用时替换为业务异步操作。

尚未保存
loading.tsx
import { Button, Flex, Text } 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 (
    <Flex direction="column" gap="md" align="start">
      <Button loading={status === 'loading'} onClick={save}>
        {status === 'saved' ? '再次保存' : '保存更改'}
      </Button>
      <Text tone="muted" role="status">
        {status === 'saved' ? '更改已保存' : '尚未保存'}
      </Text>
    </Flex>
  );
}

按钮组

使用 ButtonGroup 连接相邻操作,并统一配置尺寸或禁用状态。

button-group.tsx
import { Button, ButtonGroup } from '@ifhover/leaf-ui';

export function ButtonGroupDemo() {
  return (
    <ButtonGroup aria-label="步骤操作">
      <Button>上一步</Button>
      <Button>下一步</Button>
    </ButtonGroup>
  );
}

分裂按钮

SplitButton 将主要操作和相关菜单放在一起;主按钮使用 onClick,菜单项分别提供自己的操作。

split-button.tsx
import { Flex, SplitButton, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function SplitButtonDemo() {
  const [result, setResult] = useState('');

  return (
    <Flex direction="column" gap="md" align="start">
      <SplitButton
        variant="solid"
        onClick={() => setResult('已保存')}
        menuLabel="更多保存方式"
        items={[
          { key: 'copy', label: '保存副本', onClick: () => setResult('副本已保存') },
          { key: 'draft', label: '存为草稿', onClick: () => setResult('草稿已保存') },
        ]}
      >
        保存
      </SplitButton>
      <Text tone="muted" role="status">
        {result}
      </Text>
    </Flex>
  );
}

API

Button API

支持 onClick、name、form、aria-*、data-* 等原生 button 属性。

属性类型默认值说明
variant'solid' | 'outline' | 'text' | 'link''outline'视觉样式
size'sm' | 'md' | 'lg''md'按钮尺寸
dangerbooleanfalse使用红色危险语义,支持所有 variant
loadingbooleanfalse显示加载指示器并禁用交互
fullWidthbooleanfalse填满父容器宽度
startIconReactNode—文字前的图标,加载时由指示器替代
endIconReactNode—文字后的图标
disabledbooleanfalse禁用交互。
type'button' | 'submit' | 'reset''button'原生按钮类型
refRef<HTMLButtonElement>—按钮 DOM 引用

ButtonGroupProps API

用于组合一组相关按钮的参数。

属性类型默认值说明
size'sm' | 'md' | 'lg'—按钮尺寸
disabledboolean—禁用交互。
attachedbooleantrue连接相邻按钮

SplitButtonProps API

主操作与下拉操作组合按钮的参数。

属性类型默认值说明
variant'solid' | 'outline' | 'text' | 'link''outline'按钮样式
size'sm' | 'md' | 'lg''md'按钮尺寸。
dangerbooleanfalse危险操作颜色
loadingbooleanfalse加载状态
fullWidthbooleanfalse占满宽度
startIconReactNode—前置图标
endIconReactNode—后置图标
itemsreadonly DropdownItem[]必填数据项目,保持 key 唯一且稳定
menuLabelstring—菜单按钮的可访问名称
dropdownPropsOmit<DropdownProps, 'items' | 'children' | 'disabled'>—操作菜单属性