# @glass-sdk/liquid-glass 中文文档

规范地址：https://npmcn.com/package/%40glass-sdk/liquid-glass/

版本：0\.0\.2
npm 元数据更新时间：2026-10-10T01:36:01.367Z
中文译文更新时间：2026-11-16T15:32:28.094Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40glass-sdk/liquid-glass
原文对照：https://npmcn.com/package/%40glass-sdk/liquid-glass/?lang=original
项目主页：https://liquid-glass.glassapp.dev/
源码仓库：https://github.com/Glass-HQ/liquid-glass

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：307 kB，129 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react \>=19\.0\.0，react-dom \>=19\.0\.0
- 首次发布：2026-10-07T22:51:18.710Z
- 最新版本发布：2026-10-10T01:36:00.924Z
- 近 30 天下载量：7897（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

液晶材料和可访问的React组件用于网络和Electron,由vgpu和WGSL所建造.

## 安装

```sh
npm install @glass-sdk/liquid-glass
```

也可以使用：`pnpm add @glass-sdk/liquid-glass`、`yarn add @glass-sdk/liquid-glass`、`bun add @glass-sdk/liquid-glass`

## README

# 液体玻璃

玻璃表面与控制反应,网络,和电能. 清晰而有规律的材料支持光和暗的外观和活性内含.

[实例和组成部分参考](https://liquid-glass.glassapp.dev/#examples) • 妇女 [GitHub 图像](https://github.com/Glass-HQ/liquid-glass)

## 安装

```sh
npm install @glass-sdk/liquid-glass@~0.0.2
```

## 快开始

```tsx
import { GlassScene, GlassContent, GlassSurface, GlassButton } from "@glass-sdk/liquid-glass";
import "@glass-sdk/liquid-glass/styles.css";

export function Example() {
  return (
    <GlassScene material="regular" appearance="light" style={{ height: 320 }}>
      <GlassContent>
        <img src="/landscape.jpg" alt="Mountain lake"
          style={{ width: "100%", height: "100%", objectFit: "cover" }} />
      </GlassContent>
      <GlassSurface radius={28}
        style={{ position: "absolute", left: 24, top: 100, padding: 20 }}>
        <GlassButton onClick={() => console.log("Saved")}>Save</GlassButton>
      </GlassSurface>
    </GlassScene>
  );
}
```

导入样式表一次 。 它不要求 Tailwind 或 CSS 重置 。 把玻璃组件放进去 `GlassScene`,有一个 `GlassContent` 背景层。 文字,SVG, 和图层中的图像保持活性. 在 Next.js 中,使用客户端组件.

`GlassContent` 让你的道具 裁判 和孩子们保持其源元素 稳定透明包装。 瞄准它的阶级,而不是依赖它成为现场的直接孩子. 将准备用于完成的成分的不透明性和剪接涂上 `GlassScene` 或共同祖先; `GlassContent` 样式描述玻璃后输入.

## 构成部分

| 构成部分 | 目的 |
| --- | --- |
| `GlassScene`, (中文(简体) ), `GlassContent` | 场景与活地背景层. |
| `GlassSurface`, (中文(简体) ), `GlassButton` | 玻璃容器和按钮. |
| `GlassToolbar`, (中文(简体) ), `GlassToolbarButton`, (中文(简体) ), `GlassToolbarLink`, (中文(简体) ), `GlassToolbarGroup`, (中文(简体) ), `GlassToolbarSpacer` | 键盘可导航工具栏. |
| `GlassTabs` | 有移动选择指标的标签栏. |
| `GlassTabsRoot`, (中文(简体) ), `GlassTabsList`, (中文(简体) ), `GlassTabsTrigger`, (中文(简体) ), `GlassTabsIndicator`, (中文(简体) ), `GlassTabsContent` | 可编译的标签和面板. |
| `GlassMenu`, (中文(简体) ), `GlassMenuTrigger`, (中文(简体) ), `GlassMenuContent`, (中文(简体) ), `GlassMenuItem` | 带有定位和焦点修复的菜单. |
| `GlassMenuSubmenu`, (中文(简体) ), `GlassMenuSubmenuTrigger`, (中文(简体) ), `GlassMenuSubmenuContent` | 内脏菜单. |
| `GlassSlider`, (中文(简体) ), `GlassSwitch` | 滑轮和开关. |
| `GlassForeground`, (中文(简体) ), `useGlassForeground` | 外观含量较高,玻璃表面可折叠. |
| `GlassShape`, (中文(简体) ), `GlassShapeContainer`, (中文(简体) ), `GlassCorner` | 连续角和容器相接几何. |
| `GlassProgressiveBlur`, (中文(简体) ), `GlassScrollEdges` | 逐渐模糊背景内容和滚动边缘 . |

按钮,工具栏,标签,菜单,滑动器,和开关使用Base UI行为. 标准道具,参考文献,无障碍名称,以及状态回调仍然可用. 见 [组件示例](https://liquid-glass.glassapp.dev/#examples) 使用量和 [基准用户界面参考](https://base-ui.com/react/overview/quick-start) 为继承道具.

## 材料和动议

设定默认值 `GlassScene`;单个表面可以覆盖它们. 菜单弹出默认为正则 .

| Prop | 默认 | 使用量 |
| --- | --- | --- |
| `material` | `"clear"` | `"clear"` 或者说 `"regular"`。 。 。 . |
| `appearance` | `"light"` | `"light"` 或者说 `"dark"`。 。 。 . |
| `radius` | 特定构成部分 | CSS像素中的连续角半径, `"capsule"`,或 `"circle"`。普通表面默认为 8px. |
| `refraction` | `60` | CSS像素中的非负离所. 被嵌入的表面将其默认限制在母体内置. |
| `tint` | 无 | 六位数六分色相. 在不更改文本或图标的情况下给玻璃涂色. |
| `interactive` | 特定构成部分 | 按下并拖动反馈;默认情况下用于按钮、工具栏和标签栏. |
| `fluid` | `false` | 当布局维度变化时动画大纲. |
| `morphFrom` | 无 | 表面的开口和收尾形状的元素会反射或取出. |
| `morph` | 按背景分列 | `"become"` 替换源; `"detach"` 与它分开. |
| `motion` | `"full"` | `"full"`, (中文(简体) ), `"reduced"`,或 `"none"`;从现场继承. |

滑动和切换按下拇指默认为 Clear,折射分别是5px和7.75px. 他们 `tint` 设置音轨颜色.

系统减动优惠总是适用的,包括: `motion="full"`减少运动可以消除伸展和出行; `"none"` 删除过渡。 Safari与其他浏览器使用相同的运动设置.

覆盖样式 `className`,内置样式,或CSS公用事业. 样式表使用低特性 `:where()` 选择者。 使用 `radius` 换个角落 这样材料和内容片段就一致了 覆盖 `--lg-foreground` 用于文本和图标颜色.

## 设置控制

这个 `render` 道具会将道具,处理器,样式,和裁判器与你的组件相融合. 自定义组件必须转发到它们的 DOM 元素 。 使用透明背景来保持玻璃的可见度.

```tsx
<GlassSurface material="clear" render={<Button onClick={save} />}>
  Save
</GlassSurface>
```

菜单留在他们的现场。 内容接受 `side`, (中文(简体) ), `align`, (中文(简体) ), `sideOffset`, (中文(简体) ), `alignOffset`,以及 `collisionAvoidance`; 默认值为下/后相差8px 。 使用 `positionerProps` 财务报告和审定财务报表 `portalProps` 用于额外的 Base UI 选项.

```tsx
<GlassMenu>
  <GlassMenuTrigger render={<GlassButton />}>Options</GlassMenuTrigger>
  <GlassMenuContent>
    <GlassMenuItem onClick={save}>Save</GlassMenuItem>
    <GlassMenuSubmenu>
      <GlassMenuSubmenuTrigger>Share</GlassMenuSubmenuTrigger>
      <GlassMenuSubmenuContent>
        <GlassMenuItem onClick={copyLink}>Copy link</GlassMenuItem>
      </GlassMenuSubmenuContent>
    </GlassMenuSubmenu>
  </GlassMenuContent>
</GlassMenu>
```

`GlassMenuGroup`, (中文(简体) ), `GlassMenuGroupLabel`, (中文(简体) ), `GlassMenuSeparator`, (中文(简体) ), `GlassMenuCheckboxItem`, (中文(简体) ), `GlassMenuRadioGroup`,以及 `GlassMenuRadioItem` 暴露相应的基础UI部件.

在工具栏中,用 `GlassToolbarButton render={<GlassMenuTrigger />}`。使用工具栏按钮和链接进行箭头键导航. `GlassToolbarSpacer` 分离玻璃组: `sizing="fixed"` 给定8px空格; `"flexible"` 填补可用的空间。 给工具栏一个宽度或高度,以便灵活间隔.

## 标签、滑动和开关

```tsx
<GlassTabs aria-label="Navigation" defaultValue="home"
  items={[{ value: "home", label: "Home" }, { value: "library", label: "Library" }]} />

<GlassSlider aria-label="Volume" defaultValue={50}
  onValueCommitted={(value) => console.log(value)} />
<GlassSlider ticks aria-label="Intensity" min={0} max={100} step={25} />
<label>Notifications <GlassSwitch name="notifications" defaultChecked /></label>
```

标签选择第一个启用的项目,除非 `defaultValue` 已经设定。 使用 `value` 财务报告和审定财务报表 `onValueChange` 用于控制选择。 对于面板或自定义触发器,由标签部分组成:

```tsx
<GlassTabsRoot defaultValue="preview">
  <GlassTabsList aria-label="View">
    <GlassTabsIndicator />
    <GlassTabsTrigger value="preview">Preview</GlassTabsTrigger>
    <GlassTabsTrigger value="usage">Usage</GlassTabsTrigger>
  </GlassTabsList>
  <GlassTabsContent value="preview">Your preview</GlassTabsContent>
  <GlassTabsContent value="usage">Your usage code</GlassTabsContent>
</GlassTabsRoot>
```

此列表也在 Base UI 标签根范围内工作; 不要嵌入另一个根 。 保留标签标签中的互动元素 .

滑动器接受数字 `value` 或者说 `defaultValue`, (中文(简体) ), `min`, (中文(简体) ), `max`, (中文(简体) ), `step`, (中文(简体) ), `onValueChange`,以及 `onValueCommitted`。默认值为 0–100,分0.1个步骤。 与 `ticks`,步骤必须平均划分范围,最多间隔100个. `thumbProps` 披露输入参考和可访问值文本.

开关接受 Base UI 开关道具,包括 `checked`, (中文(简体) ), `defaultChecked`, (中文(简体) ), `onCheckedChange`, (中文(简体) ), `name`,以及 `inputRef`。带有标签或 `aria-label`。两种控制支持表, RTL, `tint`和减少运动.

## 渐进模糊

`GlassProgressiveBlur` 软化 `GlassContent` 在边缘。 在内容层外放置标题和控件,使其保持清晰.

```tsx
<GlassScene style={{ height: 320, overflow: "hidden" }}>
  <GlassContent>
    <img src="/landscape.jpg" alt="Mountain lake"
      style={{ width: "100%", height: "100%", objectFit: "cover" }} />
  </GlassContent>
  <GlassProgressiveBlur edge="bottom" size={80} blur={20} />
</GlassScene>
```

用于滚动内容, 使用 `GlassContent layout="scroll"` 作为取景所,并传递其参考文献到 `GlassScrollEdges`在Safari卷轴期间,这保持了玻璃和模糊的固定状态。 给场景一个有界限的高度,并在内容旁放置浮控:

```tsx
const viewport = useRef<HTMLDivElement>(null);

<GlassScene style={{ height: 320, overflow: "hidden" }}>
  <GlassContent layout="scroll" ref={viewport} tabIndex={0} role="region"
    aria-label="Reading list" style={{ scrollPaddingBlock: 80 }}>
    {children}
  </GlassContent>
  <GlassScrollEdges target={viewport} size={80} blur={20} />
</GlassScene>
```

| Prop | 默认 | 使用量 |
| --- | --- | --- |
| `edge` | `"bottom"` | 原始边缘 : `top`, (中文(简体) ), `bottom`, (中文(简体) ), `inline-start`,或 `inline-end`。 。 。 . |
| `edges` | `["top", "bottom"]` | 卷起助道边. 逻辑边缘遵循方向. |
| `target` | 需要滚动帮助 | 翻到滚动的取景口. |
| `size` | `80` | 边缘深度为像素,0–4096;卷轴边缘夹住一半的取景口. |
| `blur` | `20` | 高斯标准偏差以像素表示, 0–64. |
| `refraction` | `0` | 光学在像素中的迁移, 0–32. |
| `disabled` | `false` | 删除效果. |

取景口需要明显的高地和卷轴外溢. 保持其外侧的固定头和控件,并使用卷轴粘贴来使焦点内容能够进入清晰区域. 在到达的边缘和没有溢出时,模糊不清。 透明度的降低和强迫的颜色使效果失效。 如果地图准备失败, 内容仍可读取 `onDiagnostic` 报告错误.

## 内容形状和前景

`GlassShape` 将图像和内容剪辑到连续的角落而不需要一个场景 :

```tsx
<GlassShape radius={28} render={<img src="/cover.jpg" alt="Album cover" />} />
<GlassShape radius={40} style={{ padding: 4 }}>
  <GlassShape concentric={{ inset: 4 }} radius={8}>Nested content</GlassShape>
</GlassShape>
```

`concentric` 遵循最近申报的容器大纲. `GlassSurface` 也支持着它。 使用 `GlassShapeContainer` 在不剪接的情况下宣布几何; `GlassCorner` 将控制位置置于曲线角附近。 同心圆形状和角控都接受 `container={containerRef}` 为兄弟姐妹或门户。 容器必须是可测量的;不支持旋转。 将弹出物保留在剪接的内容之外.

使用 `GlassForeground` 用于背景上方的普通DOM,在较高的玻璃表面下应折叠. 对于现有元素参考,使用 `useGlassForeground()`。在同一场景中保留重叠的内容和菜单.

## 没有反应

```ts
import { createGlassScene } from "@glass-sdk/liquid-glass/dom";
import "@glass-sdk/liquid-glass/styles.css";

const scene = createGlassScene(document.querySelector<HTMLElement>(".lg-scene")!);
scene.setContent(document.querySelector<HTMLElement>(".lg-content")!);
const remove = scene.addSurface(document.querySelector<HTMLElement>(".lg-surface")!, {
  material: "regular", radius: 28,
});

// On teardown:
remove();
scene.dispose();
```

使用 React 示例中定位的场景/内容/表面结构 . `scene.addForeground(element)` 登记前景内容并返回清理功能. `scene.addAnimator(animator)` 在场景测量前更新自定义动画.

在"Firefox"中,每个地表都画出自己的玻璃:场景增加了一个 `aria-hidden` 作为表层的最后一个孩子, 在它的其他孩子下面, 它描绘活的 `-moz-element()` 查看内容并重写。 内容层本身在那里没有过滤. Firefox 否则会在页面动画中的任意一帧的软件上重新涂上一个被过滤的内容层. 如果内容元素没有 `id`场景给它一个,而它附着。 表面不应依赖 `:last-child` 造型他们自己的孩子.

这个 `/core`, (中文(简体) ), `/gpu`,以及 `/dom` 出口为自定义集成提供几何、材料、渲染和控制API。 类型声明描述了他们的选择.

## 要求和限制

-   反应19+用于反应组件;HTTPS或localhost和一个可用的WebGPU适配器来制取玻璃材料地图. 渐进模糊不需要 WebGPU .
-   SVG过滤器的性能因浏览器引擎而异. Safari可以花费比Chrimium要长得多的时间过滤出大量内容层,即使材料地图被缓存. 让场景接近它们需要的内容来折叠,并在你支持的设备上测试动画菜单. Chromium,Firefox,Safari,和Electron都是接受目标;它们没有相同的性能.
-   对于萨法里一贯的违纪行为,给予 `GlassContent` 一个不透明的背景。 透明源像素可以将原始内容留在被折叠的图像下.
-   使用带有明确内容层的有界限的场景. 任意的页面回放采样,原生视频组成,旋转/变生祖先,原生端口不在所支持的范围. 跨原产地形象政策适用.
-   `GlassScene.maxSurfaces` 默认为16并最多接受64个。 使用 `onDiagnostic` 用于地图准备、构造时间、过滤图限制和GPU出错.
-   节点Next TypeScript 用户目前需要 `skipLibCheck: true` 对于上游 vgpu 声明.

## 如何运作

vgpu 使 WGSL 材料映射; SVG 过滤器将其应用到活的 DOM 内容. 地表移动时会缓存并再用地图. 几何变化准备出新的地图. 库中不抓取 DOM 截图 .

## 捐款和许可证

见 [捐款](https://github.com/Glass-HQ/liquid-glass/blob/main/CONTRIBUTING.md)。根据 [麻省理工学院](https://npmcn.com/package/%40glass-sdk/liquid-glass/LICENSE)。 。 。 .

## 常见问题

### @glass-sdk/liquid-glass 是什么？

液晶材料和可访问的React组件用于网络和Electron,由vgpu和WGSL所建造\.

### 如何安装 @glass-sdk/liquid-glass？

在项目目录运行 npm install @glass-sdk/liquid-glass，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.0\.0）、react-dom（\>=19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @glass-sdk/liquid-glass 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @glass-sdk/liquid-glass 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @glass-sdk/liquid-glass 可以商用吗？

@glass-sdk/liquid-glass 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @glass-sdk/liquid-glass 的下载量有多少？

根据 npm 官方下载统计，@glass-sdk/liquid-glass 在 2026/10/17 – 2026/11/15 这 30 天内被下载 7,897 次，日均约 263 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @glass-sdk/liquid-glass 还在维护吗？

最新版本 0\.0\.2 发布于 2026/10/10（1 个月前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/10/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

