#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' | 按钮尺寸 |
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 引用 |
#ButtonGroupProps API
用于组合一组相关按钮的参数。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
size | 'sm' | 'md' | 'lg' | — | 按钮尺寸 |
disabled | boolean | — | 禁用交互。 |
attached | boolean | true | 连接相邻按钮 |
#SplitButtonProps API
主操作与下拉操作组合按钮的参数。
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
variant | 'solid' | 'outline' | 'text' | 'link' | 'outline' | 按钮样式 |
size | 'sm' | 'md' | 'lg' | 'md' | 按钮尺寸。 |
danger | boolean | false | 危险操作颜色 |
loading | boolean | false | 加载状态 |
fullWidth | boolean | false | 占满宽度 |
startIcon | ReactNode | — | 前置图标 |
endIcon | ReactNode | — | 后置图标 |
items | readonly DropdownItem[] | 必填 | 数据项目,保持 key 唯一且稳定 |
menuLabel | string | — | 菜单按钮的可访问名称 |
dropdownProps | Omit<DropdownProps, 'items' | 'children' | 'disabled'> | — | 操作菜单属性 |