---
title: "React 版 Liquid Glass 组件，用 shadcn 安装"
description: "React 版 Liquid Glass 组件：38 个开源的 Base UI 组件，在所有现代浏览器里都能折射，用 shadcn CLI 安装。"
url: https://liquidglassdesign.com/zh/blog/liquid-glass-react-components
language: zh-Hans
published: 2026-11-20
updated: 2026-11-20
author: "Liquid Glass Design"
tags: ["Web 前端","代码","组件"]
translations:
  en: https://liquidglassdesign.com/blog/liquid-glass-react-components.md
  zh-Hant: https://liquidglassdesign.com/zh-TW/blog/liquid-glass-react-components.md
  ja: https://liquidglassdesign.com/ja/blog/liquid-glass-react-components.md
  hi: https://liquidglassdesign.com/hi/blog/liquid-glass-react-components.md
---

# React 版 Liquid Glass 组件，用 shadcn 安装

> React 版 Liquid Glass 组件：38 个开源的 Base UI 组件，在所有现代浏览器里都能折射，用 shadcn CLI 安装。

想在 React 应用里用上 Liquid Glass 组件，最快的办法是一条 shadcn 命令：`npx shadcn@latest add https://liqui.design/r/button.json`。它会装上 [Liqui](https://liqui.design/?utm_source=liquidglassdesign.com&utm_medium=referral&utm_campaign=blog_components) 的按钮。Liqui 是一套基于 Base UI 的玻璃组件，共 38 个，不用 WebGL 就能弯折身后的页面，Chromium、Safari 和 Firefox 里都能用。

Liqui 是我们自己的项目。它从这个图库发展而来，采用 MIT 许可证，源码在 [GitHub](https://github.com/leefanv/liqui-design) 上。最后一节列出了它的局限，可以先看看你的项目会不会因此用不了它。

## 包含哪些组件

这个库有 38 个组件：按钮、菜单、选择框、对话框、抽屉、滑块、开关、标签页、toast 提示、一个 iOS 风格的浮动标签栏，以及配套的表单控件。每个组件都是一个 [Base UI](https://base-ui.com) 基础组件，下面垫了一层玻璃表面，所以焦点管理、键盘操作和 ARIA 都由 Base UI 负责。

它们的交付方式和 shadcn/ui 组件一样。CLI 把组件文件以普通 TSX 的形式写进你的仓库，你像改其他文件一样改它。唯一留作依赖的是折射内核，也就是 npm 包 `@liqui-design/glass`。里面有位移贴图的计算、一个共享的 SVG 滤镜注册表和各浏览器的回退方案，这部分代码你大概不会想自己维护。

![Liqui 首页的演示区：沙漠照片上一组仿 macOS 控制中心的玻璃面板，旁边是带折射、边框宽度和磨砂滑杆的 Optics 面板](https://cdn.liquidglassdesign.com/blog/2beccd42-12aa-4a13-861c-083c6c041f0a.jpg)

*Liqui 首页的演示区，在 Chromium 中截图。* [打开 liqui.design](https://liqui.design/?utm_source=liquidglassdesign.com&utm_medium=referral&utm_campaign=blog_components)

## 用 shadcn 安装 Liquid Glass 组件

你需要 React 18 或 19，以及 Tailwind CSS v4。Liqui 和 shadcn/ui 用的是同一套 Base UI 底座（`shadcn init -b base`），所以现有的 `components.json`、`cn()` 辅助函数和 token 配置都能沿用。

按 URL 添加单个组件：

```bash
npx shadcn@latest add https://liqui.design/r/button.json
```

这条命令会写入 `components/ui/button.tsx`，把玻璃相关的 token 加进你的 `globals.css`，并安装 `@liqui-design/glass`。如果打算加好几个组件，先在 `components.json` 里注册一次命名空间：

```json
{
  "registries": {
    "@liqui-design": "https://liqui.design/r/{name}.json"
  }
}
```

```bash
npx shadcn@latest add @liqui-design/button @liqui-design/select
```

`@liqui-design/button` 是由 shadcn CLI 解析的 registry 条目。`npm i @liqui-design/button` 会失败，因为 npm 上只发布了 `@liqui-design/glass` 这一个包，CLI 会替你装好它。

用起来和其他 shadcn 组件一样：

```tsx
import { Button } from '@/components/ui/button';

export default function Page() {
  return (
    <main className="min-h-dvh bg-[url(/wallpaper.jpg)] bg-cover p-10">
      <Button>Skip</Button>
      <Button variant="accent">Continue</Button>
    </main>
  );
}
```

## 让玻璃后面有东西可折射

留意这两个按钮后面的壁纸。透镜放在纯色上，你透过它看到的还是纯色，所以白色页面上的玻璃按钮看起来像个发灰的方块，很容易被当成 bug。玻璃要放在照片、视频、边缘分明的渐变，或者在下面滚动的内容上。如果设计确实是放在纯色背景上，就设 `material="clear"`，靠染色来表现。

![一个停在 52 的玻璃音量滑块和一个圆形 AirPlay 按钮，浮在一张手握黑色音箱的特写照片上](https://cdn.liquidglassdesign.com/gallery/296cd13d-8a84-8095-9a94-c13755eef388.webp)

*Liquid Glass - Slider Concept(Volume) by sanoj sunny。* [在图库中查看](https://liquidglassdesign.com/gallery/liquid-glass-slider-concept%28volume%29)

sanoj sunny 的滑块概念设计正好是这种材质想要的环境：控件后面是一张形状鲜明、对比强烈的照片，玻璃有边缘可以弯折。为什么弯折发生在边缘，我们的 [Liquid Glass 介绍文章](https://liquidglassdesign.com/zh/what-is-liquid-glass)里有解释。

## 哪些 Liquid Glass UI 组件做成玻璃

Liqui 沿用 Apple 划的界线：你透过它去操作的表面用玻璃，承载数值的控件用实心填充。

- 按钮、弹出层、菜单、工具栏、sheet 和对话框用玻璃。它们浮在你的内容上面，这种材质的用处就是让内容透出来。
- Checkbox、Radio、Toggle 和 Switch 是平面的。静止时用 `--lq-control` 加一圈细线，打开时用 `--lq-accent`。
- Button 两种都有。默认变体是玻璃，`accent` 和 `danger` 是实心填充。带色的透镜会随背后的内容变色，品牌色放在夜景照片上和亮色照片上看起来不一样，就起不到品牌色的作用了。

你自己的设计也可以这样检验：想把复选框做成玻璃时，先问问用户从它身上读到的是什么。如果答案是「开或关」，就做成实心的。

## iOS 浮动标签栏

Tab Bar 仿的是 iOS 26 的浮动标签栏。它浮在页面上方，折射在下面滚动的列表，按下某个标签时，手指下面还会出现第二块透镜。

```bash
npx shadcn@latest add https://liqui.design/r/tab-bar.json
```

```tsx
'use client';
import { useState } from 'react';
import { Heart, House } from 'lucide-react';
import { TabBar, TabBarItem } from '@/components/ui/tab-bar';

export function BottomBar() {
  const [tab, setTab] = useState('home');
  return (
    <TabBar value={tab} onValueChange={setTab}>
      <TabBarItem value="home" icon={<House fill="currentColor" strokeWidth={0} />}>Home</TabBarItem>
      <TabBarItem value="saved" icon={<Heart fill="currentColor" strokeWidth={0} />} badge={3}>Saved</TabBarItem>
    </TabBar>
  );
}
```

它的样子主要由 frost 决定。frost 会同时加模糊和染色，而模糊会让嵌在另一块透镜里的透镜失效：内层胶囊还没来得及弯折边缘，边缘就先被模糊抹掉了。文档里讲了其中的取舍：frost 为 0.35 时，标签文字很清楚，但选中的胶囊糊成一团；为 0 时胶囊正常，可页面内容会直接穿过文字标签。标签栏最后默认用 0.16。

![iPhone 屏幕底部，消息列表上浮着一条半透明标签栏：Dashboard、Inbox、Scan、Customer 和 More](https://cdn.liquidglassdesign.com/gallery/545590e9-61cb-48b2-9a28-66b12941f222.webp)

*Liquid Glass Mobile app Navbar by Mahdi Sourabh。* [在图库中查看](https://liquidglassdesign.com/gallery/liquid-glass-mobile-app-navbar)

Mahdi Sourabh 的导航栏概念设计从设计这一侧体现了同样的平衡：一块浅色面板压在滚动的列表上，一行行内容从下面经过时，标签依然清晰可读。

## Safari 和 Firefox

网页上的折射靠 `backdrop-filter: url(#filter)` 实现，到 2026 年 11 月只有 Chromium 能画出来。`backdrop-filter` 的值里一旦引用了 SVG 滤镜，Safari 会把整个值丢掉，Firefox 则直接忽略。WebKit bug 245510 已经有补丁在审，但仍未关闭。各浏览器的细节见我们的 [CSS 和 SVG 指南](https://liquidglassdesign.com/zh/blog/liquid-glass-css-svg)。

这两个引擎都能把 SVG 滤镜画在元素自己的内容上，Liqui 用的就是这一点：用 `LiquiBackdrop` 包住一块区域，页面本身无法折射时，里面的每个玻璃表面都会改为折射这个背景的一份副本。

```tsx
import { LiquiBackdrop, LiquiGlass } from '@liqui-design/glass';

<LiquiBackdrop
  backdrop={<img src="/wallpaper.jpg" className="absolute inset-0 size-full object-cover" />}
>
  <LiquiGlass radius={20}>…</LiquiGlass>
</LiquiBackdrop>
```

每个表面在挂载时自己选一个渲染层级，不需要任何配置：

1. 背景折射（Backdrop refraction）：对表面后面的实时页面做位移。仅限 Chromium。
2. 副本折射（Copy refraction）：对已知背景的一份副本做位移。用于 Safari 和 Firefox，限 `LiquiBackdrop` 内部。
3. 磨砂（Frost）：模糊、染色，加上预先烘焙好的边缘高光。其他情况都用这一级。
4. 透明（Clear）：只有染色和边缘高光，不用 backdrop 滤镜，在你指定 `material="clear"` 时使用。

副本只对直接放在背景上的表面有效。嵌在另一个表面里的表面，或者 portal 到盒子外面的弹出层，会退回到磨砂，边缘高光保留。所以记得在 Safari 里检查你的 UI：一个调成 `frost: 0` 的表面到了磨砂层级可能很难看清，因为原来靠透镜完成的事，现在只能交给染色。这时可以跑一遍[无障碍指南](https://liquidglassdesign.com/zh/blog/liquid-glass-accessibility)里的对比度检查。

## 主题

颜色由十四个 `--lq-*` 自定义属性控制，CLI 会把它们写进 `globals.css`。在那里改 `--lq-accent` 或 `--lq-tint`，所有组件都会跟着变，包括 portal 到 `document.body` 的弹出层。深色模式同时认 `.dark` 和 `[data-theme='dark']`，所以覆盖样式两处都要写。

光学参数没法做成 CSS 变量，因为它们要喂给 canvas 生成的贴图和 SVG 滤镜，所以改由 `LiquiThemeProvider` 传入。大部分参数（`frost`、`finish`、`dispersion`）是默认值，单个组件可以覆盖；`radiusScale`、`refractionScale`、`bezelScale` 和 `blurScale` 则是乘在每个组件自身数值上的倍数。这样调厚玻璃时，滚动条滑块和抽屉会按比例一起变厚。如果只有一个全局折射值，滚动条滑块会被扭成一片模糊。

```tsx
<LiquiThemeProvider theme={{ glass: { frost: 0.2, refractionScale: 1.25 } }}>
  {children}
</LiquiThemeProvider>
```

[主题编辑器](https://liqui.design/theme?utm_source=liquidglassdesign.com&utm_medium=referral&utm_campaign=blog_components)用滑杆同时调这两部分，然后导出 CSS 和 provider 代码。主题保存在你的浏览器里，导出时只包含你改过的部分。

## 性能

开销大的是位移贴图和 `backdrop-filter` 滤镜链。贴图在 canvas 上只生成一次，按尺寸和光学参数缓存，所以十个同样大小的按钮共用一张贴图。滤镜都放在同一个隐藏的 SVG 注册表里，菜单再次打开时第一帧就有折射。有两种情况仍然会掉帧：`dispersion` 大于 0 时，滤镜计算量大约变成三倍；同一屏上放十几个大面积的 backdrop-filter 表面，比只放一个大表面更费。

## 什么时候该用别的方案

Liqui 只支持 React，还需要 Tailwind v4，所以没法直接放进 Vue 应用或 Tailwind 3 项目。在 WebKit 发布修复之前，任何库都没法在 Safari 里折射任意的实时内容。如果你只要一块玻璃面板，不需要整套组件系统，纯 CSS 和 SVG 的做法要带的东西更少。其他选择以及它们各自的渲染方式，见我们的 [Liquid Glass React 库对比](https://liquidglassdesign.com/zh/blog/liquid-glass-react-libraries)。

想先看看组件效果，[文档](https://liqui.design/docs/components?utm_source=liquidglassdesign.com&utm_medium=referral&utm_campaign=blog_components)把每个组件都放在真实背景上展示；Media Player 模板用 `npx shadcn@latest add https://liqui.design/r/media-player.json` 一次装好一整个页面。要找设计参考，图库的 [UI 版块](https://liquidglassdesign.com/ui)收集了设计师在 Dribbble 等平台上发布的 Liquid Glass 界面。

*版本、设置和数据核对于 2026 年 11 月 20 日（`@liqui-design/glass` 0.8.0）。*

## 参考来源

- https://liqui.design/docs
- https://liqui.design/docs/handbook/glass
- https://liqui.design/docs/handbook/theming
- https://liqui.design/docs/components/tab-bar
- https://liqui.design/docs/components/button
- https://liqui.design/llms-full.txt
- https://github.com/leefanv/liqui-design
- https://www.npmjs.com/package/@liqui-design/glass
- https://base-ui.com
- https://ui.shadcn.com/docs/cli
- https://bugs.webkit.org/show_bug.cgi?id=245510
