Installation
通过安装 Kumo 并导入组件来快速上手。
NPM 注册表
@cloudflare/kumo 包发布在公共 npm 注册表上，安装时无需任何特殊配置。
安装包
使用你偏好的包管理器安装 Kumo。当前版本为 v2.13.2。
npm
npm install @cloudflare/kumopnpm
pnpm add @cloudflare/kumoyarn
yarn add @cloudflare/kumo对等依赖
Kumo 需要以下对等依赖。大多数 React 项目通常已经安装了这些依赖：
# Required peer dependencies
pnpm add react react-dom @phosphor-icons/react导入组件
可以从主包导入组件，或使用细粒度导入以获得更好的 tree-shaking 效果：
主包导入
import { Button, Input, LayerCard } from "@cloudflare/kumo";细粒度导入（推荐）
import { Button } from "@cloudflare/kumo/components/button";
import { Input } from "@cloudflare/kumo/components/input";Base UI 原语
Kumo 基于 Base UI 构建，这是一个提供无样式、可访问特性的 React 组件库。如果你需要在高级场景中访问底层原语，Kumo 通过 barrel 导入和细粒度导入两种方式重新导出了全部 37 个 Base UI 组件：
Barrel 导入（更方便）
// Import multiple primitives at once
import { Popover, Slider, Accordion } from "@cloudflare/kumo/primitives";细粒度导入（性能优先，推荐）
// Import individual primitives for better tree-shaking
import { Popover } from "@cloudflare/kumo/primitives/popover";
import { Slider } from "@cloudflare/kumo/primitives/slider";
import { Accordion } from "@cloudflare/kumo/primitives/accordion";细粒度导入只包含你实际用到的原语，从而减小打包体积。
可用的原语（共 37 个）： 布局 · Accordion, Collapsible, Separator, ScrollArea, Toolbar — 浮层 · AlertDialog, Dialog, Popover, PreviewCard, Tooltip, Toast — 菜单 · Menu, Menubar, ContextMenu, NavigationMenu — 表单控件 · Autocomplete, Button, Checkbox, CheckboxGroup, Combobox, Input, NumberField, Radio, RadioGroup, Select, Slider, Switch, Toggle, ToggleGroup — 表单结构 · Field, Fieldset, Form — 展示 · Avatar, Meter, Progress, Tabs
注意： 在有可用的 Kumo 样式组件时应优先使用它们。原语主要用于构建 Kumo 中尚未提供的自定义组件，或者需要精细控制样式和行为的场景。
导入样式
Kumo 根据你的项目配置提供两种 CSS 分发方式：
使用 Tailwind CSS（推荐）
如果你的应用使用 Tailwind CSS，请将 Kumo 的源文件加入内容配置并导入样式。导入顺序很重要 — Kumo 样式必须位于 @import "tailwindcss" 之前，这样才能先注册 Kumo 的主题令牌：
重要： Tailwind CSS v4 默认不会扫描 node_modules/。你必须添加
@source 指令，这样 Tailwind 才能发现 Kumo 组件使用的工具类。否则组件
可能以缺少样式的方式渲染（例如 Dialog 未居中）。
/* app.css or main.css */
@source "../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}";
@import "@cloudflare/kumo/styles/tailwind";
@import "tailwindcss";
/* Your custom styles */@source 路径是相对于你的 CSS 文件的。请根据你的项目结构调整 — 例如，
如果你的 CSS 位于 src/styles/，可能需要写成
../../node_modules/@cloudflare/kumo/dist/**/*.{"{"}js,jsx,ts,tsx{"}"}。
注意：你也可以使用默认导出 @cloudflare/kumo/styles，它等价于 styles/tailwind。
不使用 Tailwind（独立构建）
如果你的应用不使用 Tailwind CSS，请使用已包含全部编译样式的独立构建：
// In your app entry point (e.g., main.tsx, index.tsx)
import "@cloudflare/kumo/styles/standalone";独立构建预编译了所有 Tailwind 工具类和 Kumo 组件样式，无需进行任何 Tailwind 配置！
隔离应用根节点
Kumo 的浮层组件（Select、Combobox、Dropdown、Popover、Tooltip、Dialog 等）会通过 portal 把弹层渲染到 document.body 末尾。由于 Kumo 不会给这些弹层设置 z-index，你布局中任何正的 z-index（例如吸顶头部）都可能盖在打开的弹层之上。
为避免这种情况，请按 Base UI 的建议，给应用根元素添加 isolation: isolate：
/* The element that wraps your entire app, e.g. #root or #app */
.root {
isolation: isolate;
}或者使用 Tailwind：
<div id="root" className="isolate">
{/* Your app */}
</div>这会为应用内容创建独立的层叠上下文，因此无论布局中使用什么 z-index 值，通过 portal 渲染的弹层始终显示在最顶层。请将此属性应用到包裹应用内容的元素上，而不是 <body> — 隔离 body 会让 portal 落入同一层叠上下文，从而失去效果。
如果你需要用 z-index 才能让 Kumo 弹层显示在你的界面之上，这说明某些
地方出了问题。解决办法几乎总是像上面那样隔离应用根节点，而不是提高弹层
的 z-index，或针对 Base UI 的内部 data 属性做处理。
使用示例
下面是一个结合 Tailwind CSS 使用 Kumo 组件的完整示例：
CSS 文件（app.css）
@source "../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}";
@import "@cloudflare/kumo/styles/tailwind";
@import "tailwindcss";注意：@source 路径是相对于你的 CSS 文件的，请根据你的项目结构调整。
组件文件（App.tsx）
import { Button, Input, LayerCard } from "@cloudflare/kumo";
import "./app.css";
export default function App() {
return (
<LayerCard className="rounded-lg p-6">
<h1 className="mb-4 text-2xl font-bold">Welcome to Kumo</h1>
<Input placeholder="Enter your name..." className="mb-4" />
<Button variant="primary">Submit</Button>
</LayerCard>
);
}块与组件
Kumo 为你的应用提供两种构建单元：
组件（NPM 导出）
组件以 NPM 导出的形式发布，可以直接从包中导入。它们是核心 UI 原语，例如 Button、Input 和 Dialog。
import { Button, Input, Dialog } from "@cloudflare/kumo";当你需要与你的应用无缝集成、样式一致且预置的 UI 原语时，请使用组件。组件有版本管理、支持 tree-shaking，并会自动更新。
块（通过 CLI 安装）
块是更高级的组合（例如 PageHeader 和 ResourceListPage），通过 Kumo CLI 安装。块把代码完全交给你，你可以根据自己的需求自由定制。
# Initialize Kumo configuration
npx @cloudflare/kumo init
# List available blocks
npx @cloudflare/kumo blocks
# Install a block
npx @cloudflare/kumo add PageHeader安装后，块位于你的项目中（例如 src/components/kumo/），可按需定制。CLI 会自动把相对路径的导入转换为 @cloudflare/kumo，实现无缝集成。
import { PageHeader } from "src/components/kumo/page-header/page-header";- 你需要超出 props 范围的定制
- 你想完全掌控实现方式
- 你在构建特定于应用的布局
- 某些代码你更倾向于复制粘贴而不是依赖包
工具函数
Kumo 还导出了一些用于常见场景的工具函数：
import { cn, safeRandomId, LinkProvider } from "@cloudflare/kumo";
// Merge class names with Tailwind
const className = cn("base-class", condition && "conditional-class");
// Generate safe random IDs
const id = safeRandomId();
// Configure link component for your framework (maps href to your router)
<LinkProvider component={YourAppLink}>{/* Your app */}</LinkProvider>;