# @ajuarezso/capacitor-liquid-glass 中文文档

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

版本：0\.8\.0
npm 元数据更新时间：2026-09-18T03:57:58.030Z
中文译文更新时间：2026-11-06T17:37:17.684Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ajuarezso/capacitor-liquid-glass
原文对照：https://npmcn.com/package/%40ajuarezso/capacitor-liquid-glass/?lang=original
项目主页：https://github.com/anthonyjuarezsolis/capacitor-liquid-glass#readme
源码仓库：https://github.com/anthonyjuarezsolis/capacitor-liquid-glass

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

- 包体积（解压后）：205 kB，22 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：@capacitor/core ^8\.0\.0
- 首次发布：2026-04-18T20:39:14.000Z
- 最新版本发布：2026-09-18T03:57:57.880Z
- 近 30 天下载量：2566（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

iOS 26 Liquid Glass本土染色体 (TabBar, Navigation Bar, Alerts, Sheds) 为Capacitor apps. 优雅地回到了iOS < 26和Android上.

## 安装

```sh
npm install @ajuarezso/capacitor-liquid-glass
```

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

## README

# @ajuarezso/电容器-液晶

> **Real iOS 26 Liquid Glass 原生铬(TabBar + searchBar + profile for more),用于Capacitor应用.** 唯一一个曝光 Apple 真实的 Capacitor 插件( 截至 2026) `.glassEffect()` 渲染——不是CSS `backdrop-filter` 相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相.

[![npm version](https://img.shields.io/npm/v/@ajuarezso/capacitor-liquid-glass.svg)](https://www.npmjs.com/package/@ajuarezso/capacitor-liquid-glass) [![license](https://img.shields.io/npm/l/@ajuarezso/capacitor-liquid-glass.svg)](https://npmcn.com/package/%40ajuarezso/capacitor-liquid-glass/LICENSE)

> 埃斯帕尼奥尔: [读取](https://npmcn.com/package/%40ajuarezso/capacitor-liquid-glass/README.es.md)

## 为什么会这样

介绍iOS 26 **液体玻璃** ——将模糊态+动态折射态+边缘态相结合的新型系统材料突出该变化与基础内容+形态过渡态+触动-反应变形态+有锡/清晰变相. 苹果公司将它用于新的TabBar,Navigation Bar, Sheps, Menus,动态岛,音乐应用,App Store,以及控制中心.

**截至2026年,这是唯一一个能曝光真实的 Capacitor 插件 `UIGlassEffect`** 通过浮在WebView上方的本地覆盖. CSS 等网络替代品 `backdrop-filter`, (中文(简体) ), `mix-blend-mode`,而SVG过滤器可以模仿静态模糊而不能复制:

-   动态折射( 轻弯曲, 基于运动)
-   边缘突出这一具有基本内容的转变
-   粉碎元素之间的过渡( 例如, 选项卡丸在项目之间滑动)
-   触摸反应变形(按下时为"squish")
-   系统一级动态岛屿和控制中心一体化

这些需要私人金属遮阳剂,苹果不会暴露于 `WKWebView`。唯一的路径是 **本地覆盖** 锁定在 WebView 上方, 这正是这个插件所做的 .

## 今日运出(v0.3.x)

| 部件 | iOS 26+ (英语) | iOS 15-25 (韩语) | 机器人 | 网页 |
| --- | --- | --- | --- | --- |
| **标签栏** | 真正的液体玻璃 | 经典 `UITabBar` | \-没有 -没有 | \-没有 -没有 |
| **搜索栏** | 真正的液体玻璃 | 经典 `UISearchBar` 在模糊的容器中 | \-没有 -没有 | \-没有 -没有 |

在不支持的平台(Android,Web,iOS < 26)上,插件是一个优雅的"不"(no-op)——你的CSS/HTML倒置继续工作.

## 安装

```bash
npm install @ajuarezso/capacitor-liquid-glass
npx cap sync ios
```

iOS 最小目标 : `15.0`。 。 。 . **真正的液体玻璃需要iOS 26+**;在老iOS上,当地人 `UITabBar` 编号 : `UISearchBar` 仍然制造,但没有液态玻璃材料.

## 快开始

### 标签栏

```typescript
import { LiquidGlass } from '@ajuarezso/capacitor-liquid-glass';

await LiquidGlass.showTabBar({
  items: [
    { id: '/home',    label: 'Home',    sfSymbol: 'house' },
    { id: '/search',  label: 'Search',  sfSymbol: 'magnifyingglass' },
    { id: '/cart',    label: 'Cart',    sfSymbol: 'bag', badge: '3' },
    { id: '/profile', label: 'Profile', sfSymbol: 'person' },
  ],
  selectedIndex: 0,
  tintColor: '#FA7319',
  tabBarStyle: 'liquidGlass',  // 'default' | 'ultraThin' | 'transparent' | 'liquidGlass'
});

await LiquidGlass.addListener('tabSelected', ({ id, index }) => {
  console.log('Tab tapped:', id, index);
});

await LiquidGlass.updateTabBadge({ id: '/cart', badge: '5' });
await LiquidGlass.setSelectedTab({ id: '/profile' });
await LiquidGlass.hideTabBar();
```

### 搜索栏

```typescript
await LiquidGlass.showSearchBar({
  placeholder: 'Search',
  cancelText: 'Cancel',
  tintColor: '#FA7319',
});

await LiquidGlass.addListener('searchTextChanged', ({ text }) => {
  console.log('User typed:', text);
});
await LiquidGlass.addListener('searchSubmitted', ({ text }) => {
  console.log('User submitted:', text);
});
await LiquidGlass.addListener('searchCancelled', () => {
  console.log('User tapped cancel');
});

await LiquidGlass.clearSearchText();
await LiquidGlass.hideSearchBar();
```

## API 参考

### 标签栏

#### `showTabBar(options): Promise<void>`

```typescript
interface ShowTabBarOptions {
  items: LiquidGlassTabItem[];
  selectedIndex?: number;            // default 0
  tintColor?: string;                 // '#RRGGBB'
  tabBarStyle?: TabBarStyle;          // 'default' | 'ultraThin' | 'transparent' | 'liquidGlass'
  containerElement?: string | HTMLElement;  // bind to an HTML element (see below)
}

interface LiquidGlassTabItem {
  id: string;          // stable id emitted in events
  label: string;       // text under the icon
  sfSymbol: string;    // SF Symbol name, e.g. 'house.fill'
  badge?: string;      // '3' or '•' or undefined
}
```

#### `containerElement` ——将栏与 HTML 元素(iOS)绑定

默认情况下,标签栏会把自己钉入屏幕下方。 过 `containerElement` (一个元素 `id`,或 `HTMLElement`改为: 换成 **将原生栏粘入您布局中元素的界限** —— 说 与Capacitor Google地图占位符元素相同的想法。 ()[1号](https://github.com/anthonyjuarezsolis/capacitor-liquid-glass/issues/1)(中文(简体) )

```typescript
await LiquidGlass.showTabBar({
  items: [...],
  containerElement: 'tab-bar-slot',  // <div id="tab-bar-slot"> in your DOM
});
```

```html
<!-- A placeholder that reserves where the native bar should sit. -->
<div id="tab-bar-slot" style="
  position: fixed; left: 16px; right: 16px; bottom: 24px;
  height: calc(64px + env(safe-area-inset-bottom));">
</div>
```

如何运作:

-   插件测量元素的 `getBoundingClientRect()` 和立场 本地栏( 上上覆) 匹配 —— CSS px 映射 1:1 到 UIKit 点 a WKWebView,所以没有应用缩放.
-   它自动重同步 `ResizeObserver` + 滚动 + 旋转 + 键盘 (单位:千美元)`visualViewport`),所有连接通过 `requestAnimationFrame` 所以120赫兹 卷起火力,每帧最多一次重定位.
-   元素是一个 **只有布局占位符** - 保持空/透明 土生土长的酒吧在上面 解决和衡量发生在联合来文中 `HTMLElement` 从不穿越本土桥梁.

> ⚠️ **要包含的元素大小 `env(safe-area-inset-bottom)` 当它坐在 底边.** 原生栏正好填充元素的矩形——如果 元素比栏的自然高度( ~49 pt + 安全区域)短 被剪掉的标签/相片。 如果测量到的矩形是 `0` 内 任意尺寸插件会倒回下方.

> 纯粹 **职位** 更改 a `position: fixed` 元素点出否 `scroll`编号 :`resize`编号 :`ResizeObserver` 事件不会自动重同步 。 打电话 `showTabBar(...)` (便宜——它重新计量) 低级 `setTabBarBounds(...)` 你自己来.

#### `setTabBarBounds({ bounds }): Promise<void>`

低等逃生舱口(iOS):将栏杆重新定位为明确矩形 (单位:千美元)`{ x, y, width, height }` 在CSS px,视图-相对). 绑定层 传球时,为您开这个 `containerElement`; 只有在 您自己测量元素。 网络/Android上的禁用和当栏不是时 显示.

#### `hideTabBar(): Promise<void>`

隐藏而不破坏配置。 用于全屏模式/地图.

#### `setSelectedTab({ index?, id? }): Promise<void>`

程序选择(深链接,内部导航).

#### `updateTabBadge({ id, badge }): Promise<void>`

更新单个徽章而无需重新配置整条栏(保留选择).

#### `getTabBarLayout(): Promise<{ height, bottomSafeArea }>`

返回以点为单位的布局以保留内容粘贴.

### 搜索栏

#### `showSearchBar(options?): Promise<void>`

```typescript
interface ShowSearchBarOptions {
  placeholder?: string;
  initialText?: string;
  cancelText?: string;
  tintColor?: string;
  hideCancelButton?: boolean;
}
```

#### `hideSearchBar(): Promise<void>`

#### `clearSearchText(): Promise<void>`

### 活动

| 事件 | 有效载数 |
| --- | --- |
| `tabSelected` | `{ index: number, id: string }` |
| `tabBarLayoutChanged` | `{ height: number, bottomSafeArea: number }` |
| `searchTextChanged` | `{ text: string }` |
| `searchSubmitted` | `{ text: string }` |
| `searchCancelled` | `{}` |

## 角实例

```typescript
import { Component, inject, signal } from '@angular/core';
import { LiquidGlass } from '@ajuarezso/capacitor-liquid-glass';
import { Capacitor } from '@capacitor/core';
import { Router } from '@angular/router';

@Component({ selector: 'app-shell', template: '<router-outlet />' })
export class AppShell {
  private router = inject(Router);

  async ngOnInit() {
    if (!Capacitor.isNativePlatform()) return;

    await LiquidGlass.showTabBar({
      items: [
        { id: '/home', label: 'Home', sfSymbol: 'house' },
        { id: '/cart', label: 'Cart', sfSymbol: 'bag' },
      ],
      tabBarStyle: 'liquidGlass',
    });

    LiquidGlass.addListener('tabSelected', ({ id }) => {
      this.router.navigate([id]);
    });
  }
}
```

对于不支持的平台(Android, Web),将您的 CSS / Tailwind 标签栏设置为 : `Capacitor.getPlatform()`。 。 。 .

## 与替代品的比较

| 项目 | 平台 | 真正的液体玻璃吗? | 收养 | 活动? |
| --- | --- | --- | --- | --- |
| **@ajuarezso/电容器-液晶** | iOS 控制器 | **对** (实数 `UIGlassEffect`(中文(简体) ) | 安东尼·华雷斯·索利斯 | 有(2026) |
| 支助科 `backdrop-filter: blur(...)` | 所有网页视图 | 没有(只是静态模糊) | 普遍 | 无 |
| `@react-native-community/blur` | 原生反应 | 部分(UIBlur效应,无) `UIGlassEffect`(中文(简体) ) | RN社区 | 对 |
| `flutter_glassmorphism` | 小蝶头 | 没有( 只是CSS 等同) | 社区 | 对 |
| Tauri WKWBView 本地覆盖 | 陶里语Name | 尚未公布 | 无 | 无 |

## 为什么不只是CSS `backdrop-filter`? 吗?

因为它是一个根本不同的效果:

-   **支助科 `backdrop-filter: blur(20px)`** 只是静态模糊 后面是什么。 就是这样.
-   **iOS 26 液态玻璃`UIGlassEffect`(中文(简体) )** + 模糊 + 动态折射 + 边缘 突出显示在元素之间与内容运动的相变相相变相(滑动的分页平面) + 触动-反应变形 + 锡变相 + 系统动态岛集成. 苹果公司使用私人金属遮阳器 **没有** 被曝出WKWebView.

如果你只需要一个营销网站或非iOS应用程序的静态玻璃形态,只需使用CSS. 如果您需要真实的 Apple iOS 26 在 iPhone 运行的 Capacitor app 上查看,这个插件是最短的路径.

## 路线图

-   [x] **页:1**: 有液体玻璃背景的标签栏
-   [x] **页:1**: 搜索栏覆盖
-   [x] **页:1**: 样式变体 (`'default'` 编号 : `'ultraThin'` 编号 : `'transparent'` 编号 : `'liquidGlass'`(中文(简体) )
-   [x] **页:1**: 将 TabBar 绑入 HTML 元素(`containerElement`(中文(简体) )[1号](https://github.com/anthonyjuarezsolis/capacitor-liquid-glass/issues/1)(中文(简体) )
-   [ ] 导航 栏(大标题、领头/领头项目)
-   [ ] 工具栏( 像 Safari 等浮动工具栏)
-   [ ] 警报(标准和破坏性)
-   [ ] 带有偏移的工作表
-   [ ] 菜单/ 弹出
-   [ ] Android 材料3 表达式等同物

公关欢迎.

## 限制

1.  **真正的液态玻璃所需的iOS 26**。在 iOS 15-25 上,插件仍然使本地化 `UITabBar` 编号 : `UISearchBar` 但是没有液态玻璃材料——回到 `UIBlurEffect.systemThinMaterial`。 。 。 .
    
2.  **Android是没有的**材料3 示意等同物列于行进图上,但尚未发运。 让你自己的倒计时.
    
3.  **本地覆盖浮出网络视频**,所以它不会与您的网络路由器的路由器转换相匹配。 使用 `hideTabBar()` 输入不显示标签栏的全屏路径时.
    
4.  **应用程序存储**: 此插件只使用公共的 Apple API. 没有私人API风险.
    
5.  **`containerElement` 约束** 在调整大小/滚动/旋转/键盘上重新同步,但 **没有** 在纯正的位置移动一个 `position: fixed` 元素,该元素不释放 DOM 事件。 回顾 `showTabBar(...)` (或 `setTabBarBounds(...)`)在这样的动作后. 还要将绑定的元素大小包括底部安全区域(见 `containerElement` 上面的docs)或被剪去的栏.
    

## 可发现的关键词

这个插件解决了:电容器液相玻璃,ios 26 液相玻璃电容器,电容器标签条原生地,电容器搜索条原生地,ionic液相玻璃,ios 26 UIGlasseffect电容器,电容器玻璃形态原生地,电容器原生地铬,电容器UITabBar,电容器UISearch Bar,电容器角取出取出取出取出电容器液相玻璃.

相关项目:

-   支助科 `backdrop-filter` (不是真正的液体玻璃,只是模糊)
-   `@capacitor/status-bar` (不同的关切——仅限地位栏)
-   反应本地模糊库( 不同的框架)
-   标签条的电容社区插件( 使用 HTML/ CSS, 不使用原生液体玻璃)

## 仓库

-   资料来源: [https://github.com/anthonyjuarezsolis/电容器-液晶](https://github.com/anthonyjuarezsolis/capacitor-liquid-glass)
-   问题: [https://github.com/anthonyjuarezsolis/电容器-液晶/问题](https://github.com/anthonyjuarezsolis/capacitor-liquid-glass/issues)
-   npm: https://www.npmjs.com/package/@ajuarezso/ 电容-液体-玻璃
-   在 iPhone 17 Pro Max 运行 iOS 26.5 上建造并核实

## 许可证

麻省理工学院 安东尼·华雷斯·索利斯——见 [自由主义](https://npmcn.com/package/%40ajuarezso/capacitor-liquid-glass/LICENSE)

## 常见问题

### @ajuarezso/capacitor-liquid-glass 是什么？

iOS 26 Liquid Glass本土染色体 \(TabBar, Navigation Bar, Alerts, Sheds\) 为Capacitor apps\. 优雅地回到了iOS \< 26和Android上\.

### 如何安装 @ajuarezso/capacitor-liquid-glass？

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

### @ajuarezso/capacitor-liquid-glass 支持 TypeScript 吗？

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

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

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

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

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

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

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

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

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