expo-liquid-glass

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Expo Liquid Glass

Ship Liquid Glass UI that feels native, stays legible, and degrades safely across iOS/Android.

打造原生质感、清晰易读且能在iOS/Android平台安全降级的Liquid Glass UI。

Execution Order

执行步骤

Confirm platform/runtime constraints.
Check design alignment against HIG buckets (recommended for design-heavy tasks).
Pick one primary implementation path (add a second path only if needed).
Apply Apple-aligned visual rules before writing code.
Implement guarded glass components with explicit fallbacks.
Run accessibility and visual QA in both light/dark and clear/tinted appearances.

确认平台/运行时约束条件。
对照HIG分类检查设计一致性（设计密集型任务推荐）。
选择一种主要实现方案（仅在必要时添加第二种方案）。
编写代码前先应用苹果对齐的视觉规则。
实现带有明确降级方案的受保护玻璃组件。
在浅色/深色模式以及清晰/着色外观下运行无障碍和视觉质量检查。

1) Preflight Constraints

1) 前置约束

Use Liquid Glass only for controls/navigation chrome, not primary content surfaces.
Treat these APIs as fast-moving: check current Expo SDK docs before finalizing syntax.
Expect a development build for advanced iOS-native features:
```
expo-glass-effect
```
and
```
@expo/ui
```
are not reliable in Expo Go on iOS.
Keep scope on Liquid Glass in Expo: use HIG rules to guide implementation, not to redesign unrelated product behavior.

仅将Liquid Glass用于控件/导航栏，而非主要内容区域。
这些API更新较快：最终确定语法前请查阅当前Expo SDK文档。
高级iOS原生功能需要开发构建版本：
```
expo-glass-effect
```
和
```
@expo/ui
```
在iOS的Expo Go中不可靠。
聚焦于Expo中的Liquid Glass：使用HIG规则指导实现，而非重新设计无关的产品行为。

2) Design Alignment (Recommended for design-heavy tasks)

2) 设计对齐（设计密集型任务推荐）

For tasks that involve significant visual design decisions, evaluate against these HIG buckets:

Foundations Check materials, color, layout, motion, and accessibility implications.
Patterns Check navigation/search/flow behavior for consistency with system expectations.
Components Check bars, buttons, menus, fields, sidebars, and overlays used by the screen.
Inputs Check touch, gesture, keyboard, and pointer behavior for parity and discoverability.

See

references/apple-liquid-glass-design.md

for practical design guidance. If a proposed style conflicts with HIG intent, prefer the HIG-consistent option.

对于涉及大量视觉设计决策的任务，需对照以下HIG分类进行评估：

基础准则 检查材质、颜色、布局、动效和无障碍影响。
交互模式 检查导航/搜索/流程行为是否符合系统预期。
组件规范 检查屏幕使用的栏、按钮、菜单、输入框、侧边栏和浮层。
输入交互 检查触摸、手势、键盘和指针行为的一致性和可发现性。

查看

references/apple-liquid-glass-design.md

获取实用设计指导。如果提议的样式与HIG意图冲突，优先选择符合HIG的方案。

3) Choose the Primary Path

3) 选择主要实现方案

Path	Use It For	Tradeoffs
`expo-glass-effect`	Most RN screens that need glass chips, floating buttons, toolbars, grouped controls	Best default in Expo; must guard runtime availability
`@expo/ui` ( `Host` + SwiftUI modifiers)	Native SwiftUI composition, advanced glass transitions, coordinated IDs/namespaces	iOS-family only, dev-build workflow, SwiftUI mental model
`expo-router/unstable-native-tabs`	System-native Liquid Glass tab bars and iOS 26 nav behavior	Unstable API; syntax differs between SDK 54 and 55
`@callstack/liquid-glass`	Non-Expo RN or teams standardizing on Callstack package	iOS/tvOS focus; also requires fallbacks and runtime checks

Combine paths when appropriate:

Use native tabs for navigation chrome.
Use
```
expo-glass-effect
```
for floating controls inside screens.
Use
```
@expo/ui
```
only where SwiftUI-specific behavior is required.

方案	适用场景	权衡
`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-Style Design Rules (Critical)

4) 苹果风格设计准则（关键）

Apply these rules before implementing visuals:

Keep hierarchy in layout and spacing, not decorative layers.
Group related controls into shared glass clusters; separate unrelated groups with space.
Let content run edge-to-edge behind controls so glass has something to refract.
Use system controls/material first; customize minimally.
Move strong brand color into content/background, not navigation bars.
Keep icons/labels high contrast in light, dark, clear, and tinted modes.
Avoid full-screen glass sheets; reserve glass for top-level interaction surfaces.

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

在布局和间距中体现层级，而非依赖装饰层。
将相关控件分组到共享的玻璃集群中；用间距分隔不相关的组。
让内容延伸至控件后方边缘，使玻璃有可折射的内容。
优先使用系统控件/材质；尽量少自定义。
将强烈的品牌色用于内容/背景，而非导航栏。
在浅色、深色、清晰和着色模式下保持图标/标签的高对比度。
避免全屏玻璃面板；将玻璃质感保留给顶层交互区域。

5) Implementation Patterns

5) 实现模式

Pattern A: Guarded Adaptive Glass Wrapper

模式A：带降级的自适应玻璃包装器

tsx

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>;
}

tsx

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>;
}

Pattern B: Safe

expo-glass-effect

Usage

模式B：安全使用

expo-glass-effect

Prefer

glassEffectStyle

'regular' | 'clear' | 'identity'

as needed.

Never set
```
opacity < 1
```
on
```
GlassView
```
or parents.
Treat
```
isInteractive
```
as mount-time only. Remount using a
```
key
```
if it must change.
Avoid scrollable content inside
```
GlassView
```
.
Check availability with
```
isGlassEffectAPIAvailable()
```
before rendering.

根据需要优先使用

glassEffectStyle

：

'regular' | 'clear' | 'identity'

。

切勿在
```
GlassView
```
或其父组件上设置
```
opacity < 1
```
。
将
```
isInteractive
```
视为仅在挂载时生效的属性。如需更改，请使用
```
key
```
重新挂载。
避免在
```
GlassView
```
内部使用可滚动内容。
渲染前检查
```
isGlassEffectAPIAvailable()
```
以确认可用性。

Pattern C: Native Tabs (SDK-Specific Syntax)

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

SDK 55+ compound API:

tsx

<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:

tsx

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

Known issue: transparent

NativeTabs

can flash white while pushing screens in some stacks. Mitigate by setting a background color via

ThemeProvider

(see native-tabs reference).

SDK 55+ 复合API：

tsx

<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：

tsx

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

已知问题：在某些导航栈中，透明的

NativeTabs

在推送屏幕时可能会闪现白色。可通过

ThemeProvider

设置背景色来缓解（请参阅原生标签栏参考资料）。

Pattern D: SwiftUI Glass with Namespace IDs

模式D：带命名空间ID的SwiftUI玻璃效果

Use

@expo/ui

when coordinated glass transitions are needed:

tsx

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>;

当需要协同玻璃过渡效果时使用

@expo/ui

：

tsx

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) Accessibility and Quality Gates

6) 无障碍与质量检查

Treat this as required before completion:

Check

AccessibilityInfo.isReduceTransparencyEnabled()

and provide non-glass fallback.

Verify legibility over bright, dark, and high-saturation backgrounds.
Validate both clear and tinted system appearances on iOS 26.
Keep hit targets and spacing stable during interactive animations.
Measure scroll performance with and without glass on low-end test devices.

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

检查

AccessibilityInfo.isReduceTransparencyEnabled()

并提供非玻璃质感降级方案。

验证在明亮、深色和高饱和度背景上的可读性。
在iOS 26上验证清晰和着色系统外观下的表现。
确保交互动画期间点击目标和间距保持稳定。
在低端测试设备上测量有无玻璃效果时的滚动性能。

7) Common Failure Modes and Fixes

7) 常见问题与修复方案

Double blur in headers: Native header blur + custom glass child causes muddy layering. Use a plain translucent View in header accessories.
Flat-looking glass: Solid backgrounds remove refraction cues. Add tonal variation, gradients, or imagery behind the surface.
Over-customized controls: Heavy tint/border/shadow stacks reduce native feel. Start from system defaults, then tune lightly.
Missing runtime guards: Rendering glass APIs unguarded can crash or silently degrade on unsupported builds.
Version drift: Native-tabs and SwiftUI wrappers evolve quickly; check SDK-specific docs before coding.

头部双重模糊：原生头部模糊 + 自定义玻璃子组件会导致分层模糊不清。在头部附属区域使用普通半透明View。
玻璃质感平淡：纯色背景会移除折射线索。在玻璃表面后方添加色调变化、渐变或图像。
过度自定义控件：大量色调/边框/阴影堆叠会降低原生质感。从系统默认值开始，然后进行轻微调整。
缺少运行时保障：未加保护地渲染玻璃API可能会在不支持的构建版本中崩溃或静默降级。
版本差异：原生标签栏和SwiftUI包装器更新迅速；编码前请查阅特定SDK文档。

8) Reference Loading Strategy

8) 参考资料加载策略

Load only what is needed for the task:

```
references/expo-ui-swiftui.md
```
: SwiftUI component mapping, Host layout, modifier patterns.
```
references/native-tabs.md
```
: Native tab behaviors, migration notes, known issues.
```
references/callstack-liquid-glass.md
```
: Callstack setup and compatibility tradeoffs.
```
references/apple-liquid-glass-design.md
```
: Apple-aligned composition, hierarchy, motion, and accessibility rules.

If a request is design-heavy (not API-heavy), prioritize Apple visual rules in this file first, then pull API syntax from the relevant reference.

仅加载任务所需的参考资料：

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

如果请求是设计密集型（而非API密集型），请优先参考本文档中的苹果视觉规则，然后从相关参考资料中获取API语法。

expo-liquid-glass

Original

Translation

Expo Liquid Glass

Expo Liquid Glass

Execution Order

执行步骤

1) Preflight Constraints

1) 前置约束

2) Design Alignment (Recommended for design-heavy tasks)

2) 设计对齐（设计密集型任务推荐）

3) Choose the Primary Path

3) 选择主要实现方案

4) Apple-Style Design Rules (Critical)

4) 苹果风格设计准则（关键）

5) Implementation Patterns

5) 实现模式

Pattern A: Guarded Adaptive Glass Wrapper

模式A：带降级的自适应玻璃包装器

Pattern B: Safe
`expo-glass-effect`
Usage

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

Pattern C: Native Tabs (SDK-Specific Syntax)

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

Pattern D: SwiftUI Glass with Namespace IDs

模式D：带命名空间ID的SwiftUI玻璃效果

6) Accessibility and Quality Gates

6) 无障碍与质量检查

7) Common Failure Modes and Fixes

7) 常见问题与修复方案

8) Reference Loading Strategy

8) 参考资料加载策略

expo-liquid-glass

Original

Translation

Expo Liquid Glass

Expo Liquid Glass

Execution Order

执行步骤

1) Preflight Constraints

1) 前置约束

2) Design Alignment (Recommended for design-heavy tasks)

2) 设计对齐（设计密集型任务推荐）

3) Choose the Primary Path

3) 选择主要实现方案

4) Apple-Style Design Rules (Critical)

4) 苹果风格设计准则（关键）

5) Implementation Patterns

5) 实现模式

Pattern A: Guarded Adaptive Glass Wrapper

模式A：带降级的自适应玻璃包装器

Pattern B: Safe expo-glass-effect Usage

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

Pattern C: Native Tabs (SDK-Specific Syntax)

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

Pattern D: SwiftUI Glass with Namespace IDs

模式D：带命名空间ID的SwiftUI玻璃效果

6) Accessibility and Quality Gates

6) 无障碍与质量检查

7) Common Failure Modes and Fixes

7) 常见问题与修复方案

8) Reference Loading Strategy

8) 参考资料加载策略

Pattern B: Safe
`expo-glass-effect`
Usage

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