交互式内容 | Nimbus 中文文档

文档通常需要展示机制——请求如何流转、状态如何嵌套、线路如何对接。Nimbus 将问题拆分：框架负责繁琐的生命周期，你负责渲染。

无头包装器

nimbus-docs/react 提供了一个无头的 <Diagram> 包装器和可组合的 hooks——usePhase、useMeasure、useTabIndicator、useDiagram。包装器处理那些难以做好的事情：离屏暂停、减弱动效支持、键盘快捷键、错误边界和跨岛屿协调。它本身不渲染任何可见内容。

useDiagram

useTabIndicator

DiagramControls

useMeasure

Tabs

最小的有意义示例——usePhase 遍历两个步骤，渲染的节点依次亮起。

Left

Right

import { Diagram, usePhase } from "@cloudflare/nimbus-docs/react";
import { DiagramControls } from "@/components/react/diagram";

function PingPong() {
  const { current } = usePhase({
    steps: [{ id: "left", hold: 1500 }, { id: "right", hold: 1500 }],
    loop: true,
  });
  return (
    <div className="flex items-center justify-center gap-12 py-12">
      <Node label="Left" active={current === "left"} />
      <Node label="Right" active={current === "right"} />
    </div>
  );
}

export function Demo() {
  return (
    <Diagram label="Ping-pong">
      <DiagramControls />
      <PingPong />
    </Diagram>
  );
}

装饰由你掌控

操作栏、标签页组和播放/暂停控件是你拥有的视觉装饰。通过注册表按需安装到 src/components/react/diagram/：

npx @cloudflare/nimbus-docs add diagram

yarn dlx @cloudflare/nimbus-docs add diagram

pnpm dlx @cloudflare/nimbus-docs add diagram

bunx @cloudflare/nimbus-docs add diagram

你可以自由编辑、重新设计样式或替换它们——hooks 仍然正常工作。从未编写交互式卡片的站点不会产生任何开销：react 和 react-dom 是可选的对等依赖，仅在你导入 nimbus-docs/react 时加载。

边界划分

层	所有者	内容
`<Diagram>` + hooks	`nimbus-docs/react`	生命周期、状态、离屏暂停、减弱动效、键盘、错误边界。
装饰	你（注册表）	操作栏、控件、标签页指示器——复制到你的仓库中。
渲染	你	几何形状、布局、图表所表达的语义。

框架负责行为；你负责外观。使用 client:visible 指令将结果嵌入 MDX，使其在滚动到视图中时进行水合。