vue3-liquid-glass

v1.0.0

Published

2 months ago

Apple-inspired Liquid Glass optical effect UI component library for Vue 3

0High
0Medium
0Low

luvletter

vue3 liquid-glass glassmorphism apple-ui webgl shader refraction chromatic-aberration vue-bits ui

vue3-liquid-glass

💧 vue3-liquid-glass

基于 Vue 3 + TypeScript 的苹果级液态玻璃与物理光学折射 UI 组件库

参考 Kyant0/AndroidLiquidGlass、Vue Bits - GlassSurface 与 rdev/liquid-glass-react 深度研发

✨ 核心特性

🔮 双渲染内核支持：
- WebGL 模式 (GPU 物理光线追踪)：采用全局单例 WebGL 上下文（杜绝移动端 16 个 Context 限制），通过有向距离场（SDF）与法线向量计算非线性凸透镜弯曲弧度，具有真实棱镜 RGB 色散环与 2.5D 穹顶光泽。
- SVG 模式 (Vue Bits 官方标准)：1:1 接入 Vue Bits GlassSurface 矢量双梯度法线位移图与三通道分色色散，中央 100% 晶莹剔透，纯净无噪点。
🍎 1:1 还原 Apple App Store 底栏动效：
- 超界大号悬浮透镜：拖拽时指示器高度与宽度动态扩展并放大（上下突破底栏边界 10px+），形如大号悬浮晶莹水滴；
- 静止状态紧贴内壁：静止受控状态下呈现优雅的高斯磨砂胶囊药丸，严丝合缝紧贴底栏内壁；
- 手势拖拽 60fps/120fps 实时重绘：实时折射并放大当前手指正下方的图标与文字；
- 流体果冻拉伸 (Fluid Dynamic Stretch)：跨 Tab 平移时透镜沿运动方向延展，并在到达目标时柔和回弹。
⚡ 完整移动端触控优化：全面适配 Pointer / Touch 手势，内建 iOS 级弹簧动力学（Spring Physics）引擎。
📦 开箱即用的丰富组件套件：涵盖玻璃容器、按钮、底栏、药丸开关、胶囊滑块等全套组件。

📦 安装

使用 Yarn 或 npm / pnpm 安装：

# 使用 yarn
yarn add vue3-liquid-glass

# 使用 npm
npm install vue3-liquid-glass

# 使用 pnpm
pnpm add vue3-liquid-glass

🚀 快速上手

1. 全局注册

在项目入口文件（main.ts 或 main.js）中引入并安装：

import { createApp } from 'vue'
import App from './App.vue'
import Vue3LiquidGlass from 'vue3-liquid-glass'
import 'vue3-liquid-glass/dist/index.css' // 或 import 'vue3-liquid-glass/style.css'

const app = createApp(App)
app.use(Vue3LiquidGlass)
app.mount('#app')

2. 按需导入

也可以在单文件组件中直接按需导入组件与组合式函数：

<script setup lang="ts">
import {
  LiquidBackdropRoot,
  LiquidBackdropLayer,
  LiquidGlass,
  LiquidGlassWebGL,
  LiquidGlassSVG,
  LiquidBottomTabs,
  LiquidButton,
  LiquidToggle,
  LiquidSlider,
} from 'vue3-liquid-glass'
import 'vue3-liquid-glass/dist/index.css'
</script>

📚 组件使用指南

1. 背景捕获与注册 (`LiquidBackdropRoot` / `LiquidBackdropLayer`)

液态玻璃需要获取底层背景图像以计算物理折射。使用 LiquidBackdropRoot 包裹整个区域，并通过 LiquidBackdropLayer 注册指定图层。

<template>
  <LiquidBackdropRoot class="backdrop-container">
    <!-- 注册名为 "myWallpaper" 的背景层 -->
    <LiquidBackdropLayer name="myWallpaper" :src="wallpaperUrl">
      <img :src="wallpaperUrl" class="bg-img" alt="Backdrop" />
    </LiquidBackdropLayer>

    <!-- 浮动在背景之上的液态玻璃组件 -->
    <LiquidGlass target="myWallpaper" :corner-radius="24" class="glass-card">
      <h2>液态玻璃卡片</h2>
    </LiquidGlass>
  </LiquidBackdropRoot>
</template>

<script setup lang="ts">
import { ref } from 'vue'
const wallpaperUrl = ref('https://example.com/wallpaper.jpg')
</script>

<style scoped>
.backdrop-container {
  position: relative;
  width: 100%;
  height: 400px;
}
.bg-img {
  width: 100%;
  height: 100%;
  object-fit: cover;
}
.glass-card {
  width: 260px;
  height: 160px;
}
</style>

2. 基础液态玻璃容器 (`LiquidGlass`)

通用液态玻璃容器，支持通过 mode 属性无缝切换渲染内核。

<template>
  <!-- WebGL 物理光学模式 -->
  <LiquidGlass
    mode="webgl"
    target="myWallpaper"
    :corner-radius="20"
    :refraction-height="16"
    :refraction-amount="28"
    :chromatic-aberration="true"
    :surface-color="'rgba(255, 255, 255, 0.16)'"
  >
    <span>WebGL 晶莹玻璃</span>
  </LiquidGlass>

  <!-- SVG 滤镜位移模式 (Vue Bits 规范) -->
  <LiquidGlass
    mode="svg"
    target="myWallpaper"
    :corner-radius="20"
    :distortion-scale="-80"
    :surface-color="'rgba(255, 255, 255, 0.16)'"
  >
    <span>SVG 滤镜玻璃</span>
  </LiquidGlass>
</template>

提示：如果想完全杜绝任何混合逻辑，可以直接引入独立的 LiquidGlassWebGL 或 LiquidGlassSVG 组件。

3. 苹果级液态底部导航栏 (`LiquidBottomTabs`)

支持手势滑动拖拽、超界放大透镜、流体拉伸与 iOS 级弹簧阻尼动画。

<template>
  <LiquidBottomTabs
    v-model="activeTab"
    target="myWallpaper"
    :tabs="tabList"
    :mode="'webgl'"
    :inline="false"
    :bottom-offset="'24px'"
    :max-width="'460px'"
    @change="handleTabChange"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const activeTab = ref('home')

const tabList = [
  { id: 'home', label: '首页', icon: '🏠' },
  { id: 'discover', label: '发现', icon: '🧭' },
  { id: 'messages', label: '消息', icon: '✉' },
  { id: 'profile', label: '我的', icon: '👤' },
]

const handleTabChange = (id: string | number) => {
  console.log('当前选中 Tab:', id)
}
</script>

💡 自定义 Tab 内容插槽

<LiquidBottomTabs v-model="activeTab" :tabs="tabList" target="myWallpaper">
  <template #tab="{ tab, active, index }">
    <div :class="['custom-tab', { active }]">
      <span>{{ tab.icon }}</span>
      <small>{{ tab.label }}</small>
    </div>
  </template>
</LiquidBottomTabs>

4. 弹性液态按钮 (`LiquidButton`)

内置弹簧按压微缩动力学与边缘色散。

<template>
  <LiquidButton
    target="myWallpaper"
    :corner-radius="9999"
    :surface-color="'rgba(0, 122, 255, 0.45)'"
    :border-color="'rgba(140, 200, 255, 0.85)'"
    :scale-down="0.92"
    @click="handleClick"
  >
    <span style="color: #fff; font-weight: 600;">确定提交</span>
  </LiquidButton>
</template>

5. 液态胶囊开关 (`LiquidToggle`)

<template>
  <LiquidToggle
    v-model="toggleValue"
    target="myWallpaper"
    :width="80"
    :height="44"
    :active-track-color="'rgba(52, 199, 89, 0.92)'"
    :inactive-track-color="'rgba(220, 220, 225, 0.85)'"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
const toggleValue = ref(true)
</script>

6. 液态胶囊滑块 (`LiquidSlider`)

<template>
  <LiquidSlider
    v-model="sliderValue"
    target="myWallpaper"
    :min="0"
    :max="100"
    :step="1"
    :thumb-width="48"
    :thumb-height="24"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
const sliderValue = ref(45)
</script>

⚙️ 核心属性与 API 说明

1. 通用物理光学属性 (`LensEffects`)

2. `LiquidBottomTabs` 专属属性

| 属性名 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | | modelValue | string \| number | 必填 | 当前选中的 Tab ID (v-model) | | tabs | TabItem[] | 必填 | Tab 项数组：[{ id, label, icon }] | | inline | boolean | false | 是否作为行内元素渲染（true 为行内，false 为底部固定定位） | | height | number \| string | '54px' | 底栏高度 | | maxWidth | number \| string | '460px' | 底栏最大宽度 | | bottomOffset | number \| string | '24px' | 固定定位时的底部边距 | | indicatorInset | number | 3 | 静止态指示器与底栏内壁的贴合间距 (px) | | dragScale | number | 1.28 | 手势拖拽时的放大比例（超界液态透镜） | | indicatorSurfaceColor | string | 'rgba(255, 255, 255, 0.32)' | 静止态磨砂指示器表面着色 | | indicatorBorderColor | string | 'rgba(255, 255, 255, 0.65)' | 静止态磨砂指示器高光描边色 | | indicatorBlur | number | 20 | 静止态指示器高斯模糊模糊半径 (px) |

3. SVG 模式专属微调属性 (`LiquidGlassSVG`)

| 属性名 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | | distortionScale | number | -80 | 主位移缩放强度 | | redOffset | number | 0 | 红色通道位移偏移量 | | greenOffset | number | 12 | 绿色通道位移偏移量 | | blueOffset | number | 24 | 蓝色通道位移偏移量 | | displace | number | 0.6 | 高斯模糊平滑度 (stdDeviation) | | blurAmount | number | 11 | 内部软化内核模糊半径 |

🛠️ 本地开发与测试

本项目自带轻量测试演示工程（位于 test/ 目录下）：

# 安装依赖
yarn

# 启动开发测试服务器 (运行在 http://localhost:5173)
yarn test:dev

# 构建核心库
yarn build

# 构建测试工程
yarn test:build

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

vue3-liquid-glass

💧 vue3-liquid-glass

✨ 核心特性

📦 安装

🚀 快速上手

1. 全局注册

2. 按需导入

📚 组件使用指南

1. 背景捕获与注册 (LiquidBackdropRoot / LiquidBackdropLayer)

2. 基础液态玻璃容器 (LiquidGlass)

3. 苹果级液态底部导航栏 (LiquidBottomTabs)

💡 自定义 Tab 内容插槽

4. 弹性液态按钮 (LiquidButton)

5. 液态胶囊开关 (LiquidToggle)

6. 液态胶囊滑块 (LiquidSlider)

⚙️ 核心属性与 API 说明

1. 通用物理光学属性 (LensEffects)

2. LiquidBottomTabs 专属属性

3. SVG 模式专属微调属性 (LiquidGlassSVG)

🛠️ 本地开发与测试

📄 开源许可证

1. 背景捕获与注册 (`LiquidBackdropRoot` / `LiquidBackdropLayer`)

2. 基础液态玻璃容器 (`LiquidGlass`)

3. 苹果级液态底部导航栏 (`LiquidBottomTabs`)

4. 弹性液态按钮 (`LiquidButton`)

5. 液态胶囊开关 (`LiquidToggle`)

6. 液态胶囊滑块 (`LiquidSlider`)

1. 通用物理光学属性 (`LensEffects`)

2. `LiquidBottomTabs` 专属属性

3. SVG 模式专属微调属性 (`LiquidGlassSVG`)