安装指南

Lumi UI 使用 `shadcn/ui` CLI 来管理依赖和安装组件。

初始化项目并安装基础主题

在你的终端中运行以下命令：


pnpm dlx shadcn@latest init https://lumiui.dev/r/init.json

这条命令会初始化你的项目，安装必要的依赖，并设置 Lumi UI 的基础主题。它还会在你的全局样式中配置一个必要的 CSS 隔离规则（例如 root:isolate）。

配置 Lumi UI 组件源

更新你的 component.json 文件，加入 Lumi UI 的组件源配置。这样你就能通过 npx shadcn-ui add 命令来添加 Lumi UI 组件了。

在配置中添加以下内容：

component.json

{
  // ... 其他配置
  "registries": {
    "@lumi-ui": "https://lumiui.dev/r/{name}.json"
  }
  // ...
}

添加根布局包装器

为了让第一步中配置的样式作用域和隔离规则正确生效，你需要用一个带有 root 类名的 div 包裹住应用的主要内容。

更新你的主布局文件（例如 layout.tsx 或类似文件），如下所示：

layout.tsx

  <body>
    <div className="root">{children}</div>
  </body>

这一步确保了所有 Lumi UI 的样式都能被正确地限定作用域，并与你的应用其他部分隔离。更多细节可以参考 Base UI 关于 Portals 的文档。

提示

请记得给 body 添加 relative，以支持 iOS。

添加设计令牌

在 @theme inline 块中添加全局变量：

globals.css

  /* 用于弹出层/提示消息 */
  --ease-spring: cubic-bezier(0.23, 1, 0.32, 1);
 
  /* 用于抽屉/对话框 */
  --ease-smooth: cubic-bezier(0.32, 0.72, 0, 1);

添加 CSS 工具类

将以下 CSS 工具类粘贴到你的全局样式文件中（例如 globals.css 或类似文件）：

globals.css

 /* 弹出层动画 */
 @utility animate-popup {
   @apply origin-[var(--transform-origin)] transition-[opacity,scale,transform] ease-spring duration-150;
   &[data-starting-style],
   &[data-ending-style] {
     opacity: 0;
     scale: 0.95;
   }
 }
 
 /* 浮层描边 */
 @utility overlay-outline {
   @apply outline outline-border dark:-outline-offset-1;
 }
 
 /* 选中高亮 */
 @utility highlight-on-active {
   @apply data-highlighted:relative data-highlighted:z-0 data-highlighted:before:absolute data-highlighted:before:inset-x-1.5 data-highlighted:before:inset-y-0 data-highlighted:before:z-[-1] data-highlighted:before:rounded-md data-highlighted:before:bg-accent data-highlighted:text-accent-foreground;
 }

对话框、抽屉和提示消息的组件级 CSS 可以在它们各自的安装指南中找到。

安装全部 UI 组件

执行以下命令，一次性安装 Lumi UI 的全部组件：


pnpm dlx shadcn@latest add @lumi-ui/ui

Toast 组件需要一些额外配置。请参考 Toast 获取更多详细信息。