安装 Installation
@cloudflare/kumo

安装 Installation

在你的项目中安装并配置 Kumo。

npm 注册表

@cloudflare/kumo 包发布在公共 npm 注册表上，安装无需任何特殊配置。

安装包

使用你喜欢的包管理器安装 Kumo。当前版本为 v2.14.0。

npm

npm install @cloudflare/kumo

pnpm

pnpm add @cloudflare/kumo

yarn

yarn add @cloudflare/kumo

对等依赖

Kumo 需要以下对等依赖。大多数 React 项目已经安装了它们：

# 必需的对等依赖
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 再导出全部 37 个 Base UI 组件，同时支持批量导入和细粒度导入两种方式：

批量导入 (便捷)

// 一次性导入多个原语
import { Popover, Slider, Accordion } from "@cloudflare/kumo/primitives";

细粒度导入 (推荐，性能更优)

// 单独导入各个原语，获得更好的树摇效果
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 的源文件添加到你的 content 配置中，并导入样式。导入顺序很重要 —— Kumo 样式必须位于 @import "tailwindcss" 之前，这样 Kumo 的主题令牌才会先被注册：

重要: Tailwind CSS v4 默认不会扫描 node_modules/。你必须添加 @source 指令，Tailwind 才能发现 Kumo 组件使用的工具类。否则组件可能 缺失样式渲染 (例如 Dialog 不居中)。

/* app.css 或 main.css */
@source "../node_modules/@cloudflare/kumo/dist/**/*.{js,jsx,ts,tsx}";
@import "@cloudflare/kumo/styles/tailwind";
@import "tailwindcss";

/* 你的自定义样式 */

@source 路径是相对于你的 CSS 文件的。请根据你的项目结构调整 —— 例如，如果你的 CSS 在 src/styles/ 下，可能需要 ../../node_modules/@cloudflare/kumo/dist/**/*.{"{"}js,jsx,ts,tsx{"}"}。

注意：你也可以使用默认导出 @cloudflare/kumo/styles,它等价于 styles/tailwind。

不使用 Tailwind CSS 的用户 (独立版本)

如果你的应用不使用 Tailwind CSS，请使用包含全部已编译样式的独立 (standalone) 版本：

// 在你的应用入口文件中 (如 main.tsx、index.tsx)
import "@cloudflare/kumo/styles/standalone";

独立版本预编译了全部 Tailwind 工具类和 Kumo 组件样式，无需任何 Tailwind 配置！

隔离你的应用根元素

Kumo 的浮动组件 (Select、Combobox、Dropdown、Popover、Tooltip、Dialog 等) 会把弹层渲染到 document.body 末尾的挂载层 (portal) 中。由于 Kumo 不为这些弹层设置 z-index,你自己布局中的任何正 z-index(例如吸顶头部) 都可能绘制在打开的弹层之上。

为避免这种情况，请像 Base UI 推荐的那样,为你的应用根元素添加 isolation: isolate:

/* 包裹整个应用的元素，如 #root 或 #app */
.root {
  isolation: isolate;
}

或者使用 Tailwind:

<div id="root" className="isolate">
  {/* 你的应用 */}
</div>

这会为你的应用内容创建一个独立的层叠上下文，使挂载的弹层始终显示在最上层，无论你布局中使用了什么 z-index 值。请把它应用在包裹应用内容的元素上，而不是 <body> —— 隔离 body 会把挂载层放进同一个层叠上下文，反而达不到目的。

如果你发现自己在用 z-index 让 Kumo 弹层显示在自己的 UI 之上，这说明哪里出了问题。修复方法几乎总是如上所示隔离你的应用根元素， 而不是提高弹层的 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 导出发布，可以直接从包中导入。这些是 Button、Input、Dialog 这样的核心 UI 原语。

import { Button, Input, Dialog } from "@cloudflare/kumo";

当你需要一致、自带样式且能与应用无缝集成的 UI 原语时，请使用组件。组件有版本管理、支持树摇，并能自动接收更新。

区块 (CLI 安装)

区块是更高级别的组合 (如 PageHeader 和 ResourceListPage),通过 Kumo CLI 安装。区块的代码完全归你所有，方便你按需定制。


# 初始化 Kumo 配置

npx @cloudflare/kumo init

# 列出可用的区块

npx @cloudflare/kumo blocks

# 安装一个区块

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";

// 用 Tailwind 合并类名
const className = cn("base-class", condition && "conditional-class");

// 生成安全的随机 ID
const id = safeRandomId();

// 为你的框架配置链接组件 (将 href 映射到你的路由)
<LinkProvider component={YourAppLink}>{/* 你的应用 */}</LinkProvider>;