# @avenra/liquid-glass 中文文档

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

版本：1\.2\.0
npm 元数据更新时间：2026-06-14T19:33:00.974Z
中文译文更新时间：2026-11-07T07:52:55.357Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40avenra/liquid-glass
原文对照：https://npmcn.com/package/%40avenra/liquid-glass/?lang=original
项目主页：https://docs.avenra.online/docs/liquid-glass/getting-started
源码仓库：https://github.com/DevSam7t3/liquid-glass

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

- 包体积（解压后）：1 MB，20 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：0 个
- 首次发布：2026-06-05T06:07:22.364Z
- 最新版本发布：2026-06-14T19:33:00.839Z
- 近 30 天下载量：6127（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

基于物理的液态玻璃UI效应——斯内尔定律 SVG 置放地图,春季动画,零运行时间依赖.

## 安装

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

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

## README

# @avenra/ 液晶

[![CI](https://github.com/DevSam7t3/liquid-glass/actions/workflows/ci.yml/badge.svg)](https://github.com/DevSam7t3/liquid-glass/actions/workflows/ci.yml) [![CodeQL](https://github.com/DevSam7t3/liquid-glass/actions/workflows/codeql.yml/badge.svg)](https://github.com/DevSam7t3/liquid-glass/actions/workflows/codeql.yml) [![npm version](https://img.shields.io/npm/v/@avenra/liquid-glass.svg)](https://www.npmjs.com/package/@avenra/liquid-glass) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

基于物理的液态玻璃UI效应为网. 斯内尔定律折射被烤成一幅SVG流离地图,分光相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相接相相接相接相接相接相接相接相接相相接相接相接相接相.

> **浏览器注释 :** SVG迁移效应要求 `backdrop-filter: url()` 这是 **仅铬**。所有其他浏览器都收到 CSS `blur + saturate` 倒下,看起来仍然像被冰冻的玻璃.

* * *

## 安装

```bash
npm install @avenra/liquid-glass
```

```html
<!-- CDN (production) -->
<script src="https://cdn.jsdelivr.net/npm/@avenra/liquid-glass/dist/liquid-glass.umd.min.js"></script>
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@avenra/liquid-glass/styles/liquid-glass.css"
/>
```

* * *

## 快开始

### npm/ 捆绑器

```ts
import { createLiquidButton, createLiquidSwitch, createLiquidSlider } from '@avenra/liquid-glass';
import '@avenra/liquid-glass/styles';

const btn = createLiquidButton('#myBtn', { label: 'Save' });
btn.on('click', (e: MouseEvent) => console.log('clicked'));

const sw = createLiquidSwitch('#toggle', { checked: false });
sw.on('change', ({ checked }) => console.log('switch:', checked));

const sl = createLiquidSlider('#slider', { min: 0, max: 100, value: 50 });
sl.on('input', ({ value }) => updateVolume(value));
sl.on('change', ({ value }) => savePreference(value)); // fires on release
```

### CDN / 脚本标签

```html
<script src="https://cdn.jsdelivr.net/npm/@avenra/liquid-glass/dist/liquid-glass.umd.min.js"></script>
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@avenra/liquid-glass/styles/liquid-glass.css"
/>
<button id="btn"></button>
<script>
  const { createLiquidButton } = LiquidGlass;
  createLiquidButton('#btn', { label: 'Click me' }).on('click', () => alert('hello'));
</script>
```

### 0-JS — 数据属性

```html
<button data-liquid-button data-label="Subscribe"></button>
<div data-liquid-switch data-checked="true"></div>
<div data-liquid-slider data-min="0" data-max="100" data-value="50"></div>
<div data-liquid-glass></div>
```

```js
import { init } from '@avenra/liquid-glass';
const handles = init(); // scans document and applies everything
```

* * *

## Theming — CSS 自定义属性

在你的风格表里覆盖这些

```css
:root {
  --lg-tint: rgba(255, 255, 255, 0.05); /* glass body fill           */
  --lg-border: rgba(255, 255, 255, 0.2); /* 1px edge border           */
  --lg-shadow-out: 0 10px 30px rgba(0, 0, 0, 0.3); /* drop shadow               */
  --lg-shadow-hi: inset 0 2px 5px rgba(255, 255, 255, 0.25); /* top highlight */
  --lg-shadow-lo: inset 0 -2px 5px rgba(0, 0, 0, 0.15); /* bottom shade  */
  --lg-accent: #3b82f6; /* slider fill / progress fill gradient start  */
  --lg-accent-2: #60a5fa; /* gradient end                                */
}
```

* * *

## API 参考

### 通用选项( 所有组件继承这些选项)

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `bezelWidth` | `number` | `20` | Px 折射活性贝泽环宽度 |
| `glassThickness` | `number` | `80` | 虚拟玻璃深度(较大 = 更平相射线漂移) |
| `refractiveIndex` | `number` | `1.5` | 折射n2(1.0=无弯曲,2.0=强)指数 |
| `profile` | `'convexSquircle' | 'convexCircle' | 'concave' | fn` | `'convexSquircle'` | Bezel 表面形状 |
| `blur` | `number` | `0.5` | 迁移前的高斯文模糊度 |
| `saturation` | `number` | `1.3` | 迁移后颜色饱和倍数 |
| `specularSlope` | `number` | `0.8` | 光谱突出强度 0–1 |
| `filterMode` | `'screen' | 'composite'` | `'screen'` | SVG 过滤器混合管 |
| `width` 编号 : `height` | `number` | 自动 | 覆盖地图生成的元素维度 |
| `radius` | `number | null` | 自动 | 角半径覆盖( null = 从 CSS 读取) |

### 常见的手柄 API( 每个工厂都返回)

```ts
handle.on(event, fn); // subscribe — returns handle (chainable)
handle.off(event, fn); // unsubscribe a specific listener
handle.once(event, fn); // subscribe once — auto-removed after first fire
handle.destroy(); // clean up all injected DOM and stop animations
```

所有活动包括: `destroy` 事件于 `destroy()` 名为.

* * *

### `createLiquidGlass(target, options?)`

将玻璃效果应用到任何元素中.

```ts
const glass = createLiquidGlass('#myCard', {
  bezelWidth: 24,
  glassThickness: 120,
  refractiveIndex: 2.0,
});

glass.on('resize', ({ width, height }) => console.log(width, height));
glass.refresh(); // rebuild maps (auto-called on resize)
glass.destroy();
```

| 活动 | 有效载荷 |
| --- | --- |
| `resize` | `{ width: number; height: number }` |
| `destroy` | —— 说 |

* * *

### `createLiquidButton(target, options?)`

```ts
const btn = createLiquidButton('#myBtn', { label: 'Save Changes' });
btn.on('click', (e: MouseEvent) => handleSave(e));
btn.setLabel('Saved ✓');
btn.destroy();
```

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `label` | `string` | 按钮文本 |

| 活动 | 有效载荷 |
| --- | --- |
| `click` | `MouseEvent` |
| `mouseenter` 编号 : `mouseleave` | `MouseEvent` |
| `mousedown` 编号 : `mouseup` | `MouseEvent` |
| `destroy` | —— 说 |

* * *

### `createLiquidSwitch(target, options?)`

```ts
const sw = createLiquidSwitch('#toggle', { checked: true });
sw.on('change', ({ checked }) => applyTheme(checked));
sw.checked = false; // programmatic setter
sw.toggle();
sw.destroy();
```

| 选项 | 类型 | 默认 |
| --- | --- | --- |
| `checked` | `boolean` | `false` |

| 活动 | 有效载荷 |
| --- | --- |
| `change` | `{ checked: boolean; element: Element }` |
| `destroy` | —— 说 |

* * *

### `createLiquidSlider(target, options?)`

```ts
const sl = createLiquidSlider('#slider', { min: 0, max: 100, value: 50, step: 5 });
sl.on('input', ({ value }) => updateUI(value)); // while dragging
sl.on('change', ({ value }) => saveToServer(value)); // on release
sl.value = 75; // programmatic setter
sl.destroy();
```

| 选项 | 类型 | 默认 |
| --- | --- | --- |
| `min` 编号 : `max` | `number` | `0` 编号 : `100` |
| `value` | `number` | `50` |
| `step` | `number` | `1` |

| 活动 | 有效载荷 |
| --- | --- |
| `input` | `{ value: number; element: Element }` |
| `change` | `{ value: number; element: Element }` |
| `destroy` | —— 说 |

* * *

### `createLiquidCursor(container, options?)`

取代内部系统光标的玻璃 Orb `container`。矿石生长在悬浮上,收缩在点击上.

```ts
const cursor = createLiquidCursor('#stage', { size: 90 });
cursor.destroy(); // restores the default cursor
```

| 选项 | 类型 | 默认 |
| --- | --- | --- |
| `size` | `number` | `90` |

* * *

### `createLiquidInput(target, options?)`

玻璃包装 `<input>` 每个键盘上都有微振动,焦点上则有大小弹簧.

```ts
const inp = createLiquidInput('#searchBox', {
  placeholder: 'Search…',
  type: 'text',
});
inp.on('input', ({ value }) => runSearch(value));
inp.on('focus', () => showSuggestions());
inp.value = 'prefilled text'; // getter/setter
inp.focus();
inp.destroy();
```

| 选项 | 类型 | 默认 |
| --- | --- | --- |
| `placeholder` | `string` | `''` |
| `value` | `string` | `''` |
| `type` | `string` | `'text'` |

| 活动 | 有效载荷 |
| --- | --- |
| `focus` | `FocusEvent` |
| `blur` | `FocusEvent` |
| `input` | `{ value: string; element: Element }` |
| `destroy` | —— 说 |

* * *

### `createLiquidDial(target, options?)`

扶轮把手-指针将它不断地拖转.

```ts
const dial = createLiquidDial('#knob', { value: 0 });
dial.on('change', ({ angle }) => setFilter(angle));
dial.angle = 90; // programmatic setter (degrees)
dial.destroy();
```

| 选项 | 类型 | 默认 |
| --- | --- | --- |
| `value` | `number` (分数) | `0` |

| 活动 | 有效载荷 |
| --- | --- |
| `change` | `{ angle: number; element: Element }` |
| `destroy` | —— 说 |

* * *

### `createLiquidTooltip(target, options)`

玻璃丸会弹出在悬浮/聚焦的触发元素上方.

```ts
// Assuming #myTooltip is positioned relative to its parent:
const tip = createLiquidTooltip('#myTooltip', {
  trigger: '#triggerBtn',
  text: 'More details',
});
tip.on('show', () => {});
tip.show(); // programmatic show
tip.hide(); // programmatic hide
tip.toggle();
tip.setText('Updated text');
tip.destroy();
```

| 选项 | 类型 | 需求 |
| --- | --- | --- |
| `trigger` | `string | Element` | ✓ |
| `text` | `string` | —— 说 |

| 活动 | 有效载荷 |
| --- | --- |
| `show` 编号 : `hide` | —— 说 |
| `destroy` | —— 说 |

* * *

### `createLiquidProgress(target, options?)`

Fluid 进度栏,在值更新时带有 squish 动画.

```ts
const bar = createLiquidProgress('#progressBar', { value: 0 });
bar.on('change', ({ value }) => console.log(value + '%'));
bar.value = 65; // triggers spring + squish
bar.destroy();
```

| 选项 | 类型 | 默认 |
| --- | --- | --- |
| `value` | `number` 0 - 100 个 | `0` |

| 活动 | 有效载荷 |
| --- | --- |
| `change` | `{ value: number; element: Element }` |
| `destroy` | —— 说 |

* * *

### `init(options?)`

扫描 DOM 为 `data-liquid-*` 属性,并自动应用匹配厂.

```ts
import { init } from '@avenra/liquid-glass';

const handles = init(); // whole document
const handles = init({ root: '#myApp' }); // limit to subtree
```

**支持的数据属性 :**

| 属性 | 通过 `data-*` |
| --- | --- |
| `data-liquid-button` | `data-label` |
| `data-liquid-switch` | `data-checked` |
| `data-liquid-slider` | `data-min`, (中文(简体) ), `data-max`, (中文(简体) ), `data-value`, (中文(简体) ), `data-step` |
| `data-liquid-glass` | `data-bezel-width`, (中文(简体) ), `data-refractive-index`, (中文(简体) ), `data-profile`等 (中文(简体) ). |

回返 `AnyHandle[]` 每个匹配元素一个手柄.

* * *

## 类型脚本

从包根导出所有类型 :

```ts
import type {
  LiquidGlassHandle,
  LiquidGlassOptions,
  LiquidGlassEventMap,
  LiquidButtonHandle,
  LiquidButtonOptions,
  LiquidButtonEventMap,
  LiquidSwitchHandle,
  LiquidSwitchOptions,
  LiquidSwitchEventMap,
  LiquidSliderHandle,
  LiquidSliderOptions,
  LiquidSliderEventMap,
  LiquidCursorHandle,
  LiquidCursorOptions,
  LiquidInputHandle,
  LiquidInputOptions,
  LiquidInputEventMap,
  LiquidDialHandle,
  LiquidDialOptions,
  LiquidDialEventMap,
  LiquidTooltipHandle,
  LiquidTooltipOptions,
  LiquidTooltipEventMap,
  LiquidProgressHandle,
  LiquidProgressOptions,
  LiquidProgressEventMap,
  AnyHandle,
} from '@avenra/liquid-glass';
```

* * *

## 高级——低级API

使用原始物理引擎构建一个完全定制的玻璃组件:

```ts
import {
  Spring,
  PROFILES,
  buildMaps,
  createFilterSVG,
  injectImages,
  setScale,
  nextFilterId,
  supportsBackdropFilter,
} from '@avenra/liquid-glass';

const { dispUrl, specUrl, maxDisplacement } = buildMaps({
  width: 200,
  height: 140,
  radius: 70,
  bezelWidth: 30,
  glassThickness: 150,
  refractiveIndex: 1.5,
});

const filterId = nextFilterId('my-lens');
const { svg, refs } = createFilterSVG({ filterId, width: 200, height: 140 });
injectImages(refs, dispUrl, specUrl);
myElement.appendChild(svg);

if (supportsBackdropFilter()) {
  innerEl.style.backdropFilter = `url("#${filterId}")`;
}

// Animation loop — spring the displacement scale
const spring = new Spring(maxDisplacement, 300, 20);
spring.setTarget(maxDisplacement * 1.5);
requestAnimationFrame(function loop() {
  setScale(refs, spring.update(1 / 60));
  if (!spring.isSettled()) requestAnimationFrame(loop);
});
```

* * *

## 浏览器兼容性

| 特性 | 颜色 | 边缘 | 火花 | 萨法里 |
| --- | --- | --- | --- | --- |
| SVG 移动 + 光谱折射 | ✓ | ✓ | —— 说 | —— 说 |
| CSS 模糊/饱和倒置 | ✓ | ✓ | ✓ | ✓ |

* * *

## 从源头构建

```bash
npm install
npm run build    # outputs dist/
npm test         # build + run physics unit tests
```

## 许可证

麻省理工学院

* * *

## 支助

需要帮忙吗? 请看我们的 [支助指南](https://npmcn.com/package/%40avenra/liquid-glass/SUPPORT.md)。 。 。 .

## 捐款

欢迎捐款! 请读我们的 [贡献指南](https://npmcn.com/package/%40avenra/liquid-glass/CONTRIBUTING.md) 财务报告和审定财务报表 [行为守则](https://npmcn.com/package/%40avenra/liquid-glass/CODE_OF_CONDUCT.md) 在提交拉动请求之前.

## 警卫

如果你发现安全隐患 请见我们 [安全政策](https://npmcn.com/package/%40avenra/liquid-glass/SECURITY.md)。 。 。 .

## 常见问题

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

基于物理的液态玻璃UI效应——斯内尔定律 SVG 置放地图,春季动画,零运行时间依赖\.

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

在项目目录运行 npm install @avenra/liquid-glass，或使用 pnpm add / yarn add / bun add。

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

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

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

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @avenra/liquid-glass 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

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

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

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

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

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