【HarmonyOS 】平台day26: React Native 实践：Overlay 遮罩层组件开发指南

前言

随着华为生态的持续演进，HarmonyOS 已成为多设备协同开发的重要平台。虽然 React Native 官方尚未原生支持 HarmonyOS，但借助社区方案（如 React Native Harmony）或桥接能力，我们仍可在 HarmonyOS 设备上运行基于 React Native 的应用。本文将带你实战开发一个通用的 Overlay 遮罩层组件，适用于弹窗、引导页、加载提示等场景，并适配 HarmonyOS 的 UI 规范与交互特性。

一、为什么需要 Overlay 遮罩层？

在移动应用中，Overlay（覆盖层）常用于：

显示模态弹窗（Modal）
全局加载指示器（Loading）
用户引导（Onboarding）
禁用背景交互（防止误操作）

一个好的 Overlay 组件应具备以下特性：

支持半透明遮罩
可自定义内容区域
支持点击遮罩关闭
动画过渡流畅
适配 HarmonyOS 的安全区域与手势系统

二、项目环境准备

前提：你已配置好 React Native 开发环境，并集成 HarmonyOS 支持（可通过 @react-native-harmony/cli 或类似工具链）。

bash 复制代码

# 示例：初始化项目（假设已有 Harmony 支持）
npx react-native init MyHarmonyApp --template react-native-template-harmony
cd MyHarmonyApp

确保 package.json 中包含 Harmony 相关依赖：

json 复制代码

{
  "dependencies": {
    "react": "18.2.0",
    "react-native": "0.74.0",
    "@react-native-harmony/core": "^0.1.0"
  }
}

三、实现 Overlay 遮罩层组件

创建文件 src/components/Overlay.js：

jsx 复制代码

import React, { useState, useEffect } from 'react';
import {
  View,
  Modal,
  StyleSheet,
  Animated,
  TouchableWithoutFeedback,
  Platform,
} from 'react-native';

// 适配 HarmonyOS 的安全区域（若支持）
import { useSafeAreaInsets } from 'react-native-safe-area-context';

const Overlay = ({
  visible = false,
  onClose,
  children,
  overlayColor = 'rgba(0, 0, 0, 0.5)',
  closeOnOverlayTap = true,
  animationType = 'fade', // 'fade' | 'slide'
}) => {
  const [opacity] = useState(new Animated.Value(0));
  const insets = useSafeAreaInsets();

  useEffect(() => {
    if (visible) {
      Animated.timing(opacity, {
        toValue: 1,
        duration: 200,
        useNativeDriver: true,
      }).start();
    } else {
      Animated.timing(opacity, {
        toValue: 0,
        duration: 150,
        useNativeDriver: true,
      }).start();
    }
  }, [visible]);

  const handleOverlayPress = () => {
    if (closeOnOverlayTap && onClose) {
      onClose();
    }
  };

  return (
    <Modal
      transparent={true}
      visible={visible}
      animationType="none" // 使用自定义动画
      onRequestClose={onClose}
    >
      <TouchableWithoutFeedback onPress={handleOverlayPress}>
        <Animated.View
          style={[
            styles.overlay,
            {
              backgroundColor: overlayColor,
              opacity: opacity,
              paddingTop: insets.top,
              paddingBottom: insets.bottom,
              paddingLeft: insets.left,
              paddingRight: insets.right,
            },
          ]}
        >
          {/* 内容容器 */}
          <View style={styles.contentContainer}>
            {children}
          </View>
        </Animated.View>
      </TouchableWithoutFeedback>
    </Modal>
  );
};

const styles = StyleSheet.create({
  overlay: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    // HarmonyOS 设备可能有异形屏，安全区域由 insets 处理
  },
  contentContainer: {
    // 可根据需要添加 padding、borderRadius 等
    backgroundColor: 'transparent',
  },
});

export default Overlay;

四、使用示例

在你的页面中调用 Overlay：

jsx 复制代码

// App.js
import React, { useState } from 'react';
import { View, Text, Button, StyleSheet } from 'react-native';
import Overlay from './src/components/Overlay';

const App = () => {
  const [showOverlay, setShowOverlay] = useState(false);

  return (
    <View style={styles.container}>
      <Button title="显示遮罩层" onPress={() => setShowOverlay(true)} />

      <Overlay
        visible={showOverlay}
        onClose={() => setShowOverlay(false)}
        overlayColor="rgba(0, 0, 0, 0.6)"
      >
        <View style={styles.modalContent}>
          <Text style={styles.title}>HarmonyOS Overlay 示例</Text>
          <Button title="关闭" onPress={() => setShowOverlay(false)} />
        </View>
      </Overlay>
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  modalContent: {
    width: 280,
    padding: 20,
    backgroundColor: '#fff',
    borderRadius: 12,
    alignItems: 'center',
  },
  title: {
    fontSize: 18,
    fontWeight: '600',
    marginBottom: 16,
  },
});

export default App;

五、HarmonyOS 特定优化建议

手势冲突处理 ：HarmonyOS 支持全局手势（如返回手势），确保 Modal 不拦截系统手势。可通过 gestureResponseDistance 调整。
深色模式适配 ：使用 Appearance API 检测主题，动态调整遮罩颜色。
多设备适配 ：在平板或折叠屏上，Overlay 内容可居中或侧边展示，利用 Dimensions 判断屏幕尺寸。
性能优化 ：HarmonyOS 强调流畅体验，避免在 Overlay 中执行 heavy 计算，使用 useMemo 和 React.memo 优化子组件。

六、结语

虽然 React Native 在 HarmonyOS 上仍处于社区探索阶段，但通过合理的组件封装和平台适配，我们完全可以构建出符合 HarmonyOS 设计语言（如"简洁、自然、一致"）的高质量应用。Overlay 作为基础 UI 组件，是提升用户体验的关键一环。

提示：未来随着 ArkTS 和声明式 UI 的普及，建议关注 ArkUI + React Native 混合开发的官方进展。

源码地址 ：GitHub - react-native-harmony-overlay-demo（示例仓库）

欢迎在评论区分享你在 HarmonyOS 上使用 React Native 的经验！

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net