Button 按钮

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

基础用法

solid 适合主要操作，soft 适合柔和强调，outline 适合次要操作，ghost 适合低优先级操作。

交互预览按钮样式

variants.tsx

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

export function ButtonVariants() {
  return (
    <>
      <Button>主要按钮</Button>
      <Button variant="soft">柔和按钮</Button>
      <Button variant="outline">描边按钮</Button>
      <Button variant="ghost">文字按钮</Button>
    </>
  );
}

使用前，在应用入口导入一次 @sudden3/leaf-ui/styles.css。接入步骤见快速开始。

危险操作

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

交互预览危险操作

danger.tsx

import { Button } from '@sudden3/leaf-ui';
import { Trash2 } from 'lucide-react';

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

尺寸

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

交互预览按钮尺寸

sizes.tsx

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

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

禁用与加载

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

交互预览禁用与加载

states.tsx

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

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

实际交互

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

交互预览异步保存

点击试试保存操作。

loading.tsx

import { Button } from '@sudden3/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 (
    <>
      <Button loading={status === 'loading'} onClick={save}>
        {status === 'loading' ? '正在保存' : status === 'saved' ? '再次保存' : '保存更改'}
      </Button>
      <span role="status">{status === 'saved' ? '更改已保存。' : '点击试试保存操作。'}</span>
    </>
  );
}

图标

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

交互预览图标按钮

icons.tsx

import { Button } from '@sudden3/leaf-ui';
import { ArrowRight, Plus, Trash2 } from 'lucide-react';

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

整行显示

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

交互预览整行按钮

full-width.tsx

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

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

Button API

属性	类型	默认值	说明
`variant`	`'solid' \| 'soft' \| 'outline' \| 'ghost'`	`'solid'`	视觉样式
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	按钮尺寸
`danger`	`boolean`	`false`	使用红色危险语义，支持所有 variant
`loading`	`boolean`	`false`	显示加载指示器并禁用交互
`disabled`	`boolean`	`false`	禁用交互
`fullWidth`	`boolean`	`false`	填满父容器宽度
`startIcon`	`ReactNode`	—	文字前的图标，加载时由指示器替代
`endIcon`	`ReactNode`	—	文字后的图标
`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 '@sudden3/leaf-ui';

表单与键盘

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

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

定制样式

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

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

#Button 按钮

#基础用法

#危险操作

#尺寸

#禁用与加载

#实际交互

#图标

#整行显示

#Button API

#类型

#表单与键盘

#定制样式