# Leaf UI 0.8.1 > Version-specific documentation for @ifhover/leaf-ui@0.8.1. Read only the pages required for your task. Match the package name and version installed in the application; do not substitute the latest version. ## API discovery - [API and exported type index](https://ifhover.github.io/leaf-ui/api/index.json): Map exact public exports to individual Markdown pages. > 轻盈、自然、可定制的 React 组件库。统一的基础组件与表单，让界面自然生长。 ## 指南 - [认识 Leaf UI](https://ifhover.github.io/leaf-ui/guide/introduction.md): 一套为 React 应用准备的 UI 组件。以绿色为起点，让界面清晰自然，也保留你的品牌个性。 - [安装&快速开始](https://ifhover.github.io/leaf-ui/guide/getting-started.md): Leaf UI 支持 React 18 与 React 19。安装后即可在 React 页面中使用，基础样式与组件样式会自动加载。 - [服务端渲染](https://ifhover.github.io/leaf-ui/guide/ssr.md): Leaf UI 的基础样式和组件样式会自动加载。下面只介绍各框架需要额外处理的部分，安装和组件用法见快速开始。 - [AI 与 Skills](https://ifhover.github.io/leaf-ui/guide/ai.md): 安装 Leaf UI skill，让 AI 在编写组件时按需查阅当前项目安装版本的 API、类型与示例。 - [浏览器兼容性](https://ifhover.github.io/leaf-ui/guide/compatibility.md): 建议使用 Chrome、Edge、Firefox 或 Safari 的当前或上一代稳定版。 - [定制主题](https://ifhover.github.io/leaf-ui/guide/theming.md): 颜色、圆角和深色模式都通过 ConfigProvider 的 theme 设置。通常几行配置就够了，其他样式会自动跟随。 - [Tailwind CSS](https://ifhover.github.io/leaf-ui/guide/tailwindcss.md): 在 Tailwind 中复用 Leaf UI 的颜色、圆角和间距。 - [切换语言](https://ifhover.github.io/leaf-ui/guide/internationalization.md): 通过 ConfigProvider 的 locale 设置组件语言，日期面板、空状态、清除按钮等内置文本会一起切换。 - [视觉与交互规范](https://ifhover.github.io/leaf-ui/guide/design-standards.md): 统一使用语义颜色、尺寸与间距变量，组件在深浅色、舒适与紧凑模式下保持一致。完整规范维护在仓库 DESIGN-STANDARDS.md。 Card 的小、默认和大尺寸统一调整留白、标题字号和标题栏高度，内嵌 Tabs 默认跟随卡片尺寸。标签页与标题共用一个头部区域：有标题时在标题下方，没有标题时占满标题栏高度并垂直居中，分割线只位于整条标签栏下方。标签文字与正文左边缘对齐，页面内容沿用卡片内边距，底部继续由 divided 控制分区外观。 警告状态统一使用明亮的黄橙色，图标、控件边框和状态填充保持一致；文字使用独立派生的可读颜色。可通过 ConfigProvider 的 theme.tokens.warningColor 定制警告色。 下拉选项统一使用灰色的悬停与键盘候选背景，已选中项保留主题色底色、文字和勾选标记。Select、自动完成、级联、树选择、时间列表和菜单使用同一配色方案；自动完成、提及和命令面板中的候选项仍使用灰色。移动背景平滑切换位置和颜色，经过选中项时不会叠色；禁用项不响应交互，危险操作保留红色提示。配色随 ConfigProvider 的区域主题与深浅外观调整。 Select、TreeSelect 和 Cascader 的多选标签使用一致的尺寸与间距。默认可换行，tagWrap={false} 保持单行并以 +N 折叠超出部分；长标签自动省略，搜索框和操作按钮始终保留空间。折叠只影响展示，不改变已选值。 主按钮和描边按钮点击后沿外轮廓快速扩散一圈波纹，再缓慢淡出，按钮与文字保持稳定；柔和按钮和链接按钮不展示波纹。主按钮悬停提亮、按下加深，描边按钮通过文字和边框变色反馈。柔和按钮使用中性浅底，危险状态使用淡红色背景和红色文字，悬停与按下时背景逐渐加深。菜单和标签页通过颜色、透明度、边框和阴影反馈，选中指示器可以移动到目标项。抽屉平滑滑入；提示内容整体出现，图标和文字不单独回弹。关闭区域动效或系统减少动态效果时，按钮不展示波纹；系统偏好优先于页面设置。 层级由圆角、边框和文字共同建立。圆角由外向内递减：弹窗、抽屉和浮层使用大圆角，卡片、提示与选项卡片等内容表面使用中圆角，按钮、输入框和表格外框使用基础圆角，复选框等小元素使用小圆角，状态标签使用无边框的基础圆角。内容表面依靠细边框和浅灰底区分，不叠加阴影；阴影只留给真正浮起的层，例如浮层、弹窗、拖动中的项目和滑块把手。文字层级依靠字号与颜色：正文 14px、辅助文字 13px，Card 标题和文档标题使用 600 字重，其他组件标题、标签和按钮使用 500 字重；选项分组等小标题使用 12px、加字距的灰色样式。 紧贴容器的内部背景采用嵌套圆角：内部圆角 = max(0px, 外框圆角 − 内边距 − 边框厚度)。默认浮层的外框为 16px、内边距为 6px、边框为 1px，因此选项为 9px。悬停、选中和移动高亮背景使用同一轮廓，并随主题自动更新；非等距留白按各方向计算，多层结构计入额外留白。小圆角和直角主题收敛到 0，独立控件、日历格子、标签和图标继续使用各自的语义圆角。 Menu 的导航项、悬停背景与移动选中高亮使用和按钮一致的基础圆角，不随菜单内边距缩小；单独配置 Menu 圆角时，这些轮廓一起更新。可选条目悬停、键盘聚焦与按下时只改变文字和图标颜色，背景保持不变；带子菜单的展开项使用浅色悬停背景与较深的按下背景。子级选中时祖先保持普通样式。子菜单使用较淡文字与 32px 默认行高，紧凑密度为 26px，浮层沿用相同反馈。 Pagination 默认使用描边按钮，也可切换为无边框样式；尺寸沿用控件高度，按下时保持位置与大小，选中背景平滑移动。描边按钮通过文字和边框变色反馈，无边框按钮使用中性背景。 卡片样式 Tabs 的内层标签和移动选中背景使用相同圆角，由标签栏圆角减去实际留白和边框派生，最小为零，跟随区域主题或组件级圆角配置。标签栏随内容收缩，尺寸包含边框和内边距，正文仍使用可用宽度。卡片标签统一使用 3px 内边距与间距、普通文字色和浮起的选中块，按下不缩放；block 让选项等宽，省略面板内容可只显示标签栏。 Tag 仅提供无边框的浅底和实色形态，使用主题基础圆角，默认 10px；组件级圆角配置优先。Tag、CheckableTag 与 TagGroup 默认加粗，跟随主题 headingWeight（默认 600），可用 bold={false} 恢复普通字重，也可通过区域默认参数统一配置。 组件验收要覆盖默认、悬停、按下、键盘焦点、选中、禁用、加载、错误、空状态。状态同时用文字或 ARIA 表达，不能只依靠颜色。图标按钮需要可访问名称；图标与文本的基线、弹窗表单与页脚边缘需要对齐。 紧凑模式面向鼠标和键盘的信息密集页面，不缩小正文字号。触屏优先舒适或更大的显式尺寸；必要操作目标至少 24px，推荐 44px。尺寸覆盖的顺序是局部组件设置、显式主题尺寸、区域密度、默认值。 按钮的横向留白随实际高度按比例生成，各尺寸都可以用组件级 padding 定制。小尺寸步骤条保留正文字号，卡片和列表形式的选项组使用统一的分区标题。Card 标题区域的上下留白一致，与正文衔接时不重复叠加间距。Modal 的标题图标与浅分隔线适合丰富内容；Confirm 是通过 API 调用的简短提示，使用留白分区，图标放在正文旁。没有副标题时减少头部留白，Card 分区、Modal 和 Drawer 的底部操作区使用一致的紧凑留白；Confirm 沿用相同的底部留白。 步骤条的文字背景保持透明，横向连线排在文字之后。头像只保留一圈 2px 白色边缘，组合头像也不叠加外圈阴影。DataTable 默认无边框并开启斑马纹；无边框使用直角、无表头灰底，表头下方保留 2px 分割线。bordered 开启带圆角的外框、表头浅底与列分隔线，两种模式的表头文字均使用正文色。斑马纹将浅灰表面与表格表面各混合一半并隐藏行间线，striped={false} 恢复行间细线。悬停时在行基础背景上混合 3% 主色，普通行和条纹行都有轻微反馈。 链接按钮无背景、边框、内边距和固定控件高度，悬停 / 按下只改变文字颜色，不展示波纹。页面跳转使用 Link；Button 的链接样式用于文字操作。 - [安装&快速开始](https://ifhover.github.io/leaf-ui/guide/installation.md) - [工作空间组合](https://ifhover.github.io/leaf-ui/guide/workspace.md): 使用 Layout 组织页面框架，Flex 与 Grid 排列内容，Form 编辑字段，DataTable 展示结构化数据。 鉴权、持久化和请求取消由应用处理。组件页面提供各自能力的简短示例。 ## 组件 - [组件总览](https://ifhover.github.io/leaf-ui/components/index.md): 浏览常用界面与表单组件，查看交互示例、用法与 API。 - [使用图标](https://ifhover.github.io/leaf-ui/components/icons.md): Leaf UI 内部及本文示例使用 Lucide，但 lucide-react 并不是唯一选择。按钮的 startIcon / endIcon、输入框的 prefix / suffix 接受 ReactNode，可以传入其他图标库的 React 组件。 - [ConfigProvider 配置](https://ifhover.github.io/leaf-ui/components/config-provider.md): 为整个应用或局部区域统一设置主题、语言和组件默认参数。 放在应用入口时作用于整个应用；嵌套使用时只调整当前区域。 - [Typography 排版](https://ifhover.github.io/leaf-ui/components/typography.md): 组织标题、正文和链接。 - [Button 按钮](https://ifhover.github.io/leaf-ui/components/button.md): 用于触发操作，如提交表单、保存内容或删除记录。 - [Divider 分割线](https://ifhover.github.io/leaf-ui/components/divider.md): 分隔内容、段落或一组操作。 - [Splitter 分割面板](https://ifhover.github.io/leaf-ui/components/splitter.md): 调整工作区面板的大小。 - [Layout 布局](https://ifhover.github.io/leaf-ui/components/layout.md): 组织页面的头部、侧栏、内容与底部。 - [Grid 栅格](https://ifhover.github.io/leaf-ui/components/grid.md): 根据屏幕宽度排列内容。 - [Flex 弹性布局](https://ifhover.github.io/leaf-ui/components/flex.md): 控制内容的排列方向、对齐、间距与换行，不为子元素添加额外容器。 - [Space 间距](https://ifhover.github.io/leaf-ui/components/space.md): 统一一组元素之间的间距。 - [ScrollArea 滚动区域](https://ifhover.github.io/leaf-ui/components/scroll-area.md): 在限定区域内浏览内容。 - [Scrollbar 滚动条](https://ifhover.github.io/leaf-ui/components/scrollbar.md): 在区域内浏览较长或较宽的内容。 - [Masonry 瀑布流](https://ifhover.github.io/leaf-ui/components/masonry.md): 排列高度不一的卡片与图片。 - [AppBar 应用导航](https://ifhover.github.io/leaf-ui/components/app-bar.md): 组织应用顶部和底部的导航。 - [CommandPalette 命令面板](https://ifhover.github.io/leaf-ui/components/command-palette.md): 快速搜索并执行操作。 - [FloatButton 悬浮按钮](https://ifhover.github.io/leaf-ui/components/float-button.md): 提供随时可用的快捷操作。 - [Anchor 锚点与固钉](https://ifhover.github.io/leaf-ui/components/anchor.md): 浏览长页目录并保持重要操作可见。 - [Menu 菜单](https://ifhover.github.io/leaf-ui/components/menu.md): 按层级组织页面导航。 - [BackTop 回到顶部](https://ifhover.github.io/leaf-ui/components/back-top.md): 快速返回页面或滚动容器顶部。 - [Steps 步骤条](https://ifhover.github.io/leaf-ui/components/steps.md): 展示任务的进展和当前步骤。 - [Breadcrumb 面包屑](https://ifhover.github.io/leaf-ui/components/breadcrumb.md): 展示当前页面在导航层级中的位置。 - [Pagination 分页](https://ifhover.github.io/leaf-ui/components/pagination.md): 按页浏览较多的数据。 - [Tabs 标签页](https://ifhover.github.io/leaf-ui/components/tabs.md): 在同一区域切换不同内容。 切换时正文和内容区域高度立即更新，不使用过渡动画；标签栏的选中指示线保留移动效果。 卡片样式的标签栏默认随标签内容调整宽度，空间不足时在栏内滚动。size 控制整个标签栏的 30 / 36 / 42px 高度，包含 3px 内边距和边框；选项间距为 3px，采用灰底与浮起的选中块，选中块在浅色模式下为纯白色，深色模式下使用主题浮起表面色，按下保持原尺寸。设置 block 可让标签等宽铺满，正文区域仍使用可用宽度。 - [Statistic 统计数值](https://ifhover.github.io/leaf-ui/components/statistic.md): 展示指标数值和倒计时。数字首次显示时默认从 0 递增或递减到目标值，后续变化从当前显示值平滑过渡到新目标。 - [DataTable 表格](https://ifhover.github.io/leaf-ui/components/table.md): 浏览、筛选和管理结构化数据。 - [Descriptions 描述列表](https://ifhover.github.io/leaf-ui/components/descriptions.md): 按名称和值展示对象详情。 - [QRCode 二维码](https://ifhover.github.io/leaf-ui/components/qr-code.md): 将文本和链接展示为二维码。 - [Timeline 时间线](https://ifhover.github.io/leaf-ui/components/timeline.md): 按顺序展示事件与进展。 - [VirtualList 虚拟列表](https://ifhover.github.io/leaf-ui/components/virtual-list.md): 流畅浏览大量列表内容。 - [InfiniteScroll 无限滚动](https://ifhover.github.io/leaf-ui/components/infinite-scroll.md): 浏览到列表末尾时加载更多内容。 - [Tag 标签](https://ifhover.github.io/leaf-ui/components/tag.md): 标记内容的分类或状态。 - [Badge 角标](https://ifhover.github.io/leaf-ui/components/badge.md): 展示数量、未读提醒或简短状态。 - [Avatar 头像](https://ifhover.github.io/leaf-ui/components/avatar.md): 展示用户、团队或对象的头像。 - [Card 卡片](https://ifhover.github.io/leaf-ui/components/card.md): 在独立容器中展示相关内容和操作。 标题默认使用 600 字重加粗，可通过 ConfigProvider 的 theme.headingWeight 调整。 - [Collapse 折叠面板](https://ifhover.github.io/leaf-ui/components/collapse.md): 展开或收起一组内容。 - [Tree 树](https://ifhover.github.io/leaf-ui/components/tree.md): 按层级浏览、选择或勾选内容。 - [Carousel 轮播](https://ifhover.github.io/leaf-ui/components/carousel.md): 依次浏览图片或内容。 - [Image 图片](https://ifhover.github.io/leaf-ui/components/image.md): 展示图片并放大浏览图片组。 - [FileList 文件列表](https://ifhover.github.io/leaf-ui/components/file-list.md): 展示文件信息、上传状态，并提供预览、下载和移除操作。 - [Mentions 提及](https://ifhover.github.io/leaf-ui/components/mentions.md): 在文本中插入成员或内容引用。 - [Upload 文件上传](https://ifhover.github.io/leaf-ui/components/upload.md): 选择或拖拽文件，查看上传进度。 - [Transfer 穿梭框](https://ifhover.github.io/leaf-ui/components/transfer.md): 在两个列表之间选择和移动项目。 - [InputOTP 验证码输入](https://ifhover.github.io/leaf-ui/components/input-otp.md): 输入和粘贴验证码。 - [InputMask 格式输入](https://ifhover.github.io/leaf-ui/components/input-mask.md): 按照指定格式填写信息。 - [Input 输入框](https://ifhover.github.io/leaf-ui/components/input.md): 用于输入单行文本，如姓名、邮箱或搜索关键词。 - [InputNumber 数字输入框](https://ifhover.github.io/leaf-ui/components/input-number.md): 输入数量、金额等数字内容。 - [Textarea 文本域](https://ifhover.github.io/leaf-ui/components/textarea.md): 用于输入多行文本，如留言、简介或备注。 - [Checkbox 复选框](https://ifhover.github.io/leaf-ui/components/checkbox.md): 用于从一组选项中选择多项。 - [Radio 单选框](https://ifhover.github.io/leaf-ui/components/radio.md): 用于从一组选项中选择一项。 - [Switch 开关](https://ifhover.github.io/leaf-ui/components/switch.md): 用于即时开启或关闭某个设置。 - [Slider 滑动输入条](https://ifhover.github.io/leaf-ui/components/slider.md): 通过滑动选择数值或区间。 - [Rate 评分](https://ifhover.github.io/leaf-ui/components/rate.md): 选择或展示评分。 - [Select 选择器](https://ifhover.github.io/leaf-ui/components/select.md): 用于从下拉列表中选择一项或多项。 - [AutoComplete 自动完成](https://ifhover.github.io/leaf-ui/components/auto-complete.md): 在输入文本时提供建议，帮助快速完成填写。 - [Cascader 级联选择](https://ifhover.github.io/leaf-ui/components/cascader.md): 用于逐级选择地区、分类等有层级关系的选项。 - [TreeSelect 树选择器](https://ifhover.github.io/leaf-ui/components/tree-select.md): 从层级数据中选择一个或多个值。 - [ColorPicker 颜色选择器](https://ifhover.github.io/leaf-ui/components/color-picker.md): 选择颜色，为内容和品牌增添个性。 - [Form 表单](https://ifhover.github.io/leaf-ui/components/form.md): 组织字段、标签和校验提示，收集表单数据。 - [TimeRangePicker 时间范围](https://ifhover.github.io/leaf-ui/components/time-range-picker.md): 选择一天内的起止时间。 - [DatePicker 日期选择器](https://ifhover.github.io/leaf-ui/components/date-picker.md): 用于选择日期。 需要同时选择时间时，使用 DateTimePicker；需要起止区间时，使用 DateRangePicker。 - [TimePicker 时间选择器](https://ifhover.github.io/leaf-ui/components/time-picker.md): 用于选择时间。 - [DateTimePicker 日期时间选择器](https://ifhover.github.io/leaf-ui/components/date-time-picker.md): 选择一个具体的日期与时间。 - [DateRangePicker 日期区间选择器](https://ifhover.github.io/leaf-ui/components/date-range-picker.md): 选择起止日期或时间，限定一个区间。 - [Calendar 日历](https://ifhover.github.io/leaf-ui/components/calendar.md): 查看日期、选择日期并展示日程安排。 - [Tour 引导](https://ifhover.github.io/leaf-ui/components/tour.md): 分步骤介绍页面上的功能。 - [Notification 通知提醒](https://ifhover.github.io/leaf-ui/components/notification.md): 在页面角落展示通知与后续操作。 - [Popconfirm 气泡确认](https://ifhover.github.io/leaf-ui/components/popconfirm.md): 在操作位置附近确认重要操作。 - [ErrorBoundary 错误边界](https://ifhover.github.io/leaf-ui/components/error-boundary.md): 展示内容异常时的备用界面。 - [LoadingBar 顶部加载条](https://ifhover.github.io/leaf-ui/components/loading-bar.md): 展示页面或任务的加载进度。 - [Dropdown 下拉菜单](https://ifhover.github.io/leaf-ui/components/dropdown.md): 在菜单中收纳更多操作。 - [Modal 弹窗](https://ifhover.github.io/leaf-ui/components/modal.md): 在弹窗中展示内容或完成操作。 - [Drawer 抽屉](https://ifhover.github.io/leaf-ui/components/drawer.md): 从页面边缘展开内容，查看详情或完成操作。 - [Confirm 确认框](https://ifhover.github.io/leaf-ui/components/confirm.md): 在执行重要操作前征求确认，通过 API 调用并等待用户的选择。 - [Alert 警告提示](https://ifhover.github.io/leaf-ui/components/alert.md): 在页面中提示操作结果或需要关注的信息。 - [Result 结果](https://ifhover.github.io/leaf-ui/components/result.md): 展示操作结果、空数据或需要关注的状态。 - [Message 消息提示](https://ifhover.github.io/leaf-ui/components/message.md): 以短暂提示反馈操作结果。 - [Loading 加载](https://ifhover.github.io/leaf-ui/components/loading.md): 提示内容正在加载或操作正在进行。 - [Skeleton 骨架屏](https://ifhover.github.io/leaf-ui/components/skeleton.md): 在内容加载时展示结构占位。 - [Progress 进度条](https://ifhover.github.io/leaf-ui/components/progress.md): 展示任务的完成程度。 - [Tooltip 文字提示](https://ifhover.github.io/leaf-ui/components/tooltip.md): 为页面元素补充简短说明。 - [Popover 气泡卡片](https://ifhover.github.io/leaf-ui/components/popover.md): 在元素附近展示说明或补充操作。 - [Empty 空状态](https://ifhover.github.io/leaf-ui/components/empty.md): 空状态已整合至 Result 结果。请使用 Result 的 status="empty"；Empty 保留为兼容入口。 ## API - [API 参考](https://ifhover.github.io/leaf-ui/api/index.md): 这里提供全局配置的完整字段，方便有进阶需求时查询。常用写法和可运行示例见 ConfigProvider。 - [组件默认参数](https://ifhover.github.io/leaf-ui/api/component-defaults.md): 通过 ConfigProvider 的 components 设置区域内的组件默认参数。常用示例、命名规则和继承方式见组件默认值。 - [主题变量](https://ifhover.github.io/leaf-ui/api/theme-tokens.md): 日常定制优先设置 ConfigProvider 的 theme.primaryColor、theme.borderRadius 和 theme.controlHeight，其他样式会自动派生，见定制主题。 - [PopupOptions](https://ifhover.github.io/leaf-ui/api/popup-options.md): Select、日期与时间选择器等组件共用的浮层参数。单个组件的配置优先于 ConfigProvider 的 getPopupContainer；Modal、Drawer 的挂载容器参数名为 container。 - [翻译资源](https://ifhover.github.io/leaf-ui/api/translations.md): 通过 ConfigProvider 的 translations 补充语言，locale 决定当前语言与回退顺序。查看可运行示例。 ## 更新记录 - [更新记录](https://ifhover.github.io/leaf-ui/changelog.md): 记录每个 npm 版本的新增功能、体验改进与问题修复。