This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

一个具有与 @react-native-masked-view/masked-view 兼容的 API 的 MaskedView 组件。maskElement 的不透明像素显示其背后的遮罩内容；透明像素隐藏它。

🌐 A MaskedView component with an API compatible with @react-native-masked-view/masked-view. The opaque pixels of maskElement reveal the masked content behind it; transparent pixels hide it.

在底层，这个组件将任意 React Native 子组件桥接到平台特定的 @expo/ui 掩码原语中：

🌐 Under the hood this component bridges arbitrary React Native children into the platform-specific @expo/ui masking primitives:

• Android：使用 BlendMode.DstIn 的 Jetpack Compose 图形层合成。
• iOS：SwiftUI .mask 修改器。

Android

iOS

安装

🌐 Installation

If you are installing this in an existing React Native app, make sure to install expo in your project.

从 @react-native-masked-view/masked-view 迁移

🌐 Migrating from @react-native-masked-view/masked-view

• 将导入从 import MaskedView from '@react-native-masked-view/masked-view' 更新为 import { MaskedView } from '@expo/ui/community/masked-view'。
• androidRenderingMode 属性不受支持。基于 Compose 的实现始终使用离屏图形层，因此该属性没有对应项，并且在公共类型中被省略。
• Web 未实现。在 Web 上，子元素会以未遮罩的方式渲染，并且会记录一次性控制台警告。对于 Web 目标，优先使用适合你特定情况的 CSS 原语：
  • 渐变文本 — 使用 background-clip: text 和 color: 'transparent' 以及 CSS 渐变/图片作为背景。
  • Alpha 淡入淡出 — mask-image: linear-gradient(...)（或 WebkitMaskImage）直接在内容视图上。
  • 形状蒙版（圆形、圆角矩形等）—— clip-path: circle(...) / inset(...) / path(...)，或 border-radius + overflow: 'hidden'。

安卓截图

🌐 Android screen capture

在 Android 上，原生截图和会话重放集成必须在 UI 线程 捕获 MaskedView。如果在后台线程绘制其 Jetpack Compose 布局，可能会导致应用崩溃并出现 IllegalArgumentException: Detected multithreaded access to SnapshotStateObserver。图片处理和编码可以在后台线程运行。

🌐 On Android, native screenshot and session replay integrations must capture MaskedView on the UI thread. Drawing its Jetpack Compose layout from a background thread can crash the app with IllegalArgumentException: Detected multithreaded access to SnapshotStateObserver. Image processing and encoding can run on a background thread.

基本用法

🌐 Basic usage

MaskedViewExample.tsx

复制

import { MaskedView } from '@expo/ui/community/masked-view';
import { StyleSheet, Text, View } from 'react-native';

export default function MaskedViewExample() {
  return (
    <MaskedView
      style={{ width: 300, height: 80 }}
      maskElement={
        <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
          <Text style={{ fontSize: 64, fontWeight: 'bold' }}>EXPO</Text>
        </View>
      }>
      <View
        style={[
          StyleSheet.absoluteFill,
          {
            experimental_backgroundImage:
              'linear-gradient(135deg, #FF3B30, #FF9500, #FFCC00, #34C759, #007AFF, #AF52DE)',
          },
        ]}
      />
    </MaskedView>
  );
}

Android

iOS

Alpha 淡化遮罩

🌐 Alpha-fade mask

只有 maskElement 的 alpha 通道才重要：不透明像素显示内容，透明像素隐藏内容。使用一个从不透明到透明的 LinearGradient（来自 expo-linear-gradient）——例如将 'black' 到下面的 'transparent' ——沿某一轴淡出内容。

🌐 Only the alpha channel of the maskElement matters: opaque pixels reveal content, transparent pixels hide it. Use a LinearGradient (from expo-linear-gradient) that goes from opaque to transparent — 'black' (for example) to 'transparent' below — to fade content out along an axis.

AlphaFadeExample.tsx

复制

import { MaskedView } from '@expo/ui/community/masked-view';
import { LinearGradient } from 'expo-linear-gradient';
import { StyleSheet, View } from 'react-native';

export default function AlphaFadeExample() {
  return (
    <MaskedView
      style={{ width: 300, height: 80, flexDirection: 'row' }}
      maskElement={
        <LinearGradient
          colors={['black', 'transparent']}
          start={{ x: 0, y: 0 }}
          end={{ x: 1, y: 0 }}
          style={StyleSheet.absoluteFill}
        />
      }>
      <View style={{ flex: 1, backgroundColor: '#3D5A80' }} />
      <View style={{ flex: 1, backgroundColor: '#DAA520' }} />
      <View style={{ flex: 1, backgroundColor: '#E07A5F' }} />
    </MaskedView>
  );
}

Android

iOS

应用接口

🌐 API

import { MaskedView } from '@expo/ui/community/masked-view';

Component