Docs
博客更新日志GitHub简中文档
首页指南EAS参考学习

Reference version

存档Expo SnackDiscord 和论坛新闻邮件
This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 56).

MaskedView

与 @react-native-masked-view/masked-view 兼容的遮罩视图。

Android
iOS

GitHub

npm

更新日志

For the complete documentation index, see llms.txt. Use this file to discover all available pages.

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

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

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

安装

Terminal
- npx expo install @expo/ui

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 迁移

  • 将导入从 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'。

基本用法

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

Alpha 淡出遮罩

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

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

API

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

Component

MaskedView

Android
iOS

Type: React.Element<MaskedViewProps>

Renders children with the alpha channel of maskElement applied as a mask: opaque pixels of maskElement reveal children, transparent pixels hide them.

API-compatible with @react-native-masked-view/masked-view.

Drop-in props for @react-native-masked-view/masked-view's MaskedView.

See: https://github.com/callstack/masked-view

MaskedViewProps

children

Android
iOS
Optional • Type: ReactNode

Content rendered behind the mask.

maskElement

Android
iOS
Type: ReactElement

The element used as the mask. Only opaque pixels of maskElement make the masked content visible — transparent pixels hide it.

Inherited Props