expo-liquid-glass

Expo Liquid Glass

打造原生感十足、清晰易读，并能在 iOS/Android 上安全降级的 Liquid Glass UI。

执行顺序

1. 确认平台和运行时限制。
2. 对照 HIG 分类检查设计是否一致（适用于设计工作量较大的任务）。
3. 选择一种主要实现路径（仅在需要时添加第二种路径）。
4. 编写代码前，先应用符合 Apple 设计规范的视觉规则。
5. 实现带明确回退方案的防护型玻璃组件。
6. 在浅色/深色以及透明/着色外观下进行无障碍和视觉 QA。

1) 前置限制

• 仅将 Liquid Glass 用于控件/导航栏界面，不要用于主要内容表面。
• 这些 API 变化很快：确定语法前，请先查阅当前 Expo SDK 文档。
• 高级 iOS 原生功能需要开发版构建： expo-glass-effect 和 @expo/ui 在 iOS 上的 Expo Go 中并不可靠。
• 范围限定为 Expo 中的 Liquid Glass：使用 HIG 规则指导实现，不要重新设计无关的产品行为。

2) 设计对齐（适用于设计工作量较大的任务）

对于涉及重大视觉设计决策的任务，请根据以下 HIG 分类进行评估：

1. 基础 检查材质、颜色、布局、动效和无障碍方面的影响。
2. 模式 检查导航/搜索/流程行为是否符合系统预期。
3. 组件 检查屏幕中使用的栏、按钮、菜单、字段、侧边栏和覆盖层。
4. 输入 检查触控、手势、键盘和指针行为是否一致且易于发现。

请参阅 references/apple-liquid-glass-design.md，了解实用设计指南。 如果拟定的样式与 HIG 的设计意图冲突，请优先选择符合 HIG 的方案。

3) 选择主要路径

路径	适用场景	权衡
expo-glass-effect	需要玻璃胶囊、浮动按钮、工具栏、分组控件的大多数 RN 屏幕	在 Expo 中是最佳默认选择；必须防护运行时可用性
@expo/ui（Host + SwiftUI 修饰符）	原生 SwiftUI 组合、高级玻璃转场、协调 ID/命名空间	仅适用于 iOS 系列平台，需要开发版构建工作流，采用 SwiftUI 心智模型
expo-router/unstable-native-tabs	系统原生 Liquid Glass 标签栏和 iOS 26 导航行为	不稳定 API；SDK 54 和 55 的语法不同
@callstack/liquid-glass	非 Expo RN，或选择统一使用 Callstack 包的团队	侧重 iOS/tvOS；同样需要回退方案和运行时检查

可根据需要组合使用：

• 使用原生标签栏作为导航栏界面。
• 使用 expo-glass-effect 实现屏幕内的浮动控件。
• 仅在需要 SwiftUI 专属行为时使用 @expo/ui。

4) Apple 风格设计规则（关键）

实现视觉效果前，请应用以下规则：

1. 通过布局和间距体现层级，而非装饰性图层。
2. 将相关控件归入共享的玻璃组；用间距分隔无关组。
3. 让内容延伸至屏幕边缘，并显示在控件后方，使玻璃有内容可折射。
4. 优先使用系统控件/材质，仅做少量自定义。
5. 将强烈的品牌色放在内容/背景中，而不是导航栏中。
6. 确保图标/标签在浅色、深色、透明和着色模式下都有高对比度。
7. 避免使用全屏玻璃面板；仅在顶层交互界面使用玻璃。

5) 实现模式

模式 A：带防护的自适应玻璃包装器

import { Platform, View } from 'react-native';
import { BlurView } from 'expo-blur';
import { GlassView, isGlassEffectAPIAvailable } from 'expo-glass-effect';

export function AdaptiveGlass({ style, children }) {
  if (isGlassEffectAPIAvailable()) {
    return (
      <GlassView style={style} glassEffectStyle="regular" tintColor="#FFFFFF10">
        {children}
      </GlassView>
    );
  }

  if (Platform.OS === 'ios') {
    return (
      <BlurView style={style} intensity={40} tint="dark">
        {children}
      </BlurView>
    );
  }

  return <View style={[style, { backgroundColor: 'rgba(60,60,67,0.30)' }]}>{children}</View>;
}

模式 B：安全使用 expo-glass-effect

• 根据需要优先选择 glassEffectStyle：'regular' | 'clear' | 'identity'。
• 绝不要在 GlassView 或其父组件上设置 opacity < 1。
• 将 isInteractive 视为仅在挂载时生效。如需更改，使用 key 重新挂载。
• 避免在 GlassView 内放置可滚动内容。
• 渲染前，请使用 isGlassEffectAPIAvailable() 检查是否可用。

模式 C：原生标签页（特定 SDK 的语法）

SDK 55+ 复合 API：

<NativeTabs.Trigger name="index">
  <NativeTabs.Trigger.TabBarIcon
    ios={{ default: 'house', selected: 'house.fill' }}
    androidIconName="home"
  />
  <NativeTabs.Trigger.TabBarLabel>Home</NativeTabs.Trigger.TabBarLabel>
</NativeTabs.Trigger>

SDK 54 API：

<NativeTabs.Trigger name="index">
  <NativeTabs.Trigger.Icon sf="house.fill" md="home" />
  <NativeTabs.Trigger.Label>Home</NativeTabs.Trigger.Label>
</NativeTabs.Trigger>

已知问题：在某些堆栈中，推入屏幕时，透明的 NativeTabs 可能会闪白。 可通过 ThemeProvider 设置背景色来缓解（参见 native-tabs 参考文档）。

模式 D：使用命名空间 ID 的 SwiftUI Glass

需要协调玻璃过渡效果时，请使用 @expo/ui：

import { Host, Namespace, Text } from '@expo/ui/swift-ui';
import { glassEffect, glassEffectID, padding } from '@expo/ui/swift-ui/modifiers';

const ns = new Namespace('glass');

<Host style={{ width: 220, height: 56 }}>
  <Text
    modifiers={[
      padding({ all: 16 }),
      glassEffect({ glass: { variant: 'regular' } }),
      glassEffectID({ id: 'primary-chip', in: ns }),
    ]}
  >
    Explore
  </Text>
</Host>;

6) 无障碍与质量门槛

完成前必须执行以下检查：

• 检查 AccessibilityInfo.isReduceTransparencyEnabled()，并提供非玻璃效果的回退方案。
• 验证界面在明亮、暗色和高饱和度背景上的可读性。
• 在 iOS 26 上验证浅色和有色系统外观。
• 在交互式动画期间保持点击目标和间距稳定。
• 在低端测试设备上测量启用和不启用玻璃效果时的滚动性能。

7) 常见故障模式及修复方法

• 标题栏中的双重模糊效果： 原生标题栏模糊效果与自定义玻璃子视图叠加，会导致层次浑浊。在标题栏配件中使用普通的半透明 View。
• 玻璃效果显得平淡： 纯色背景会消除折射线索。在表面后方添加色调变化、渐变或图像。
• 控件过度自定义： 过多叠加色调、边框和阴影会削弱原生质感。从系统默认样式开始，再进行轻微调整。
• 缺少运行时保护： 无保护地渲染玻璃 API，可能会导致崩溃，或在不受支持的构建版本上悄然降级。
• 版本差异： 原生标签页和 SwiftUI 封装更新很快；编码前请查阅特定 SDK 的文档。

8) 参考资料加载策略

仅加载任务所需的内容：

• references/expo-ui-swiftui.md：SwiftUI 组件映射、Host 布局、修饰符模式。
• references/native-tabs.md：原生标签页行为、迁移说明和已知问题。
• references/callstack-liquid-glass.md：Callstack 设置和兼容性权衡。
• references/apple-liquid-glass-design.md：符合 Apple 规范的构图、层级、动效和无障碍规则。

如果请求侧重设计（而非 API），请先优先参考此文件中的 Apple 视觉规则， 然后从相关参考文档中获取 API 语法。