react-native-dark-mode

本项目基于 react-native-dark-mode开发。如果在使用过程中有任何问题，欢迎在AtomGit提交Issue，会及时跟进。

项目介绍

@hxa-rn/react-native-dark-mode 用于在 React Native 应用中检测 HarmonyOS 系统的深色或浅色模式，并在模式变化时更新 Context、Hooks、动态值和动态样式。当前版本为 0.2.2-beta.1。

本包包含 HarmonyOS 原生 TurboModule RNDarkMode。原生侧读取系统颜色模式、提供初始模式与支持状态，并向 JS 层发送模式变化事件；因此它不是 js-only 包。

集成指南

安装 HarmonyOS 适配包：

npm install @hxa-rn/react-native-dark-mode

harmony.alias 为 react-native-dark-mode，业务代码仍使用原包名导入：

import { useDarkMode } from 'react-native-dark-mode';

应用工程需提供以下 peer dependencies：

• react-native >=0.72
• react（版本由应用工程提供）

本包包含原生实现，并声明了 RNOH Autolinking 配置；支持 Autolinking 的工程无需手工注册。

使用说明

以下示例根据当前模式切换文字和样式，并允许局部子树固定为深色模式：

import React from 'react';
import { Text, View } from 'react-native';
import {
  DarkModeProvider,
  DynamicStyleSheet,
  DynamicValue,
  useDarkMode,
  useDarkModeContext,
  useDynamicStyleSheet,
  useDynamicValue,
} from 'react-native-dark-mode';

const dynamicStyles = new DynamicStyleSheet({
  container: {
    flex: 1,
    backgroundColor: new DynamicValue('#ffffff', '#000000'),
  },
  text: {
    color: new DynamicValue('#000000', '#ffffff'),
  },
});

function ThemedContent() {
  const mode = useDarkModeContext();
  const isDark = useDarkMode();
  const styles = useDynamicStyleSheet(dynamicStyles);
  const label = useDynamicValue('浅色模式', '深色模式');

  return (
    <View style={styles.container}>
      <Text style={styles.text}>
        {label}：{mode}（isDark={String(isDark)}）
      </Text>
    </View>
  );
}

export default function App() {
  return (
    <DarkModeProvider>
      <ThemedContent />
      <DarkModeProvider mode="dark">
        <ThemedContent />
      </DarkModeProvider>
    </DarkModeProvider>
  );
}

可通过 eventEmitter 直接监听系统模式变化：

import { eventEmitter } from 'react-native-dark-mode';

const handler = (mode: 'light' | 'dark') => {
  console.info(`current mode: ${mode}`);
};

eventEmitter.on('currentModeChanged', handler);
eventEmitter.off('currentModeChanged', handler);

接口文档

模式常量与事件

| API | 调用形式或类型 | 功能与语义 | |---|---|---| | Mode | 'light' \| 'dark' | 公开的模式类型。 | | initialMode | Mode | TurboModule 创建时读取的系统模式快照；运行期间的变化不会改写该常量。 | | supportsDarkMode | boolean | 表示系统是否支持深色模式；HarmonyOS 实现固定返回 true。 | | eventEmitter | DarkModeEventEmitter | 通过 on、once、off 等事件方法订阅或取消订阅 currentModeChanged；事件回调接收一个 Mode 字符串，currentMode 保存最近模式。 |

Context 与 Hooks

| API | 参数 | 返回值与语义 | |---|---|---| | DarkModeContext | React Context | 默认值为内部标记 current，通常应通过 DarkModeProvider 和 Hooks 使用。 | | DarkModeProvider | { mode?: Mode; children: ReactNode } | 返回 Provider 元素；未传 mode 时跟随系统，传入后固定子树模式。 | | useDarkModeContext() | 无 | 返回当前 Context 的 Mode。 | | useDarkMode() | 无 | 当前模式为 dark 时返回 true，否则返回 false。 | | useDynamicStyleSheet(sheet) | DynamicStyleSheet<T> | 返回当前模式对应的 NormalizeStyles<T>。 | | useDynamicValue(value) | DynamicValue<T> | 返回当前模式对应的 T。 | | useDynamicValue(light, dark) | 两个 T 值 | 浅色模式返回 light，深色模式返回 dark。 |

动态值、样式与公开类型

| API | 构造参数或类型 | 功能与语义 | |---|---|---| | new DynamicValue(light, dark) | 两个 T 值 | 保存 .light 与 .dark 两个只读值。 | | new DynamicStyleSheet(styles) | 可在样式属性中使用 DynamicValue 的对象 | 构造时生成 .light 与 .dark 两套 React Native 静态样式。 | | NormalizeStyles<T> | TypeScript 类型 | 表示移除样式中 DynamicValue 包装后的静态样式结果。 | | DynamicViewStyle | TypeScript 类型 | 支持 DynamicValue 的 ViewStyle。 | | DynamicTextStyle | TypeScript 类型 | 支持 DynamicValue 的 TextStyle。 | | DynamicImageStyle | TypeScript 类型 | 支持 DynamicValue 的 ImageStyle。 |

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18 | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 12+ |

运行步骤

1. 克隆仓库

git clone https://gitcode.com/hxa-rn/react-native-dark-mode.git
cd react-native-dark-mode
git checkout br_rnoh0.72

2. 安装仓库开发依赖

npm install --legacy-peer-deps

Example 已改为从 npm 公仓安装 @hxa-rn/[email protected]，不再使用本地 file:../xxx.tgz，运行 Example 不必再执行 npm pack。

3. 进入 example 目录，安装依赖

cd example
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。

约束与限制

• 兼容性：react-native peer dependency 要求 >=0.72；两个 Demo 当前均使用 React Native 0.72.5 和 RNOH 0.72.139。两个 Demo 的 compatibleSdkVersion 均为 5.0.1(13)，即 HarmonyOS API 13。
• 运行环境：包声明 Node.js >=18；实际应用工程还需满足自身工具链要求。
• 权限：插件 module.json5 的 requestPermissions 为空，无额外系统权限。
• 平台差异：HarmonyOS 的 supportsDarkMode 固定为 true；系统颜色模式未设置或不可用时按浅色模式处理。
• 事件行为：currentModeChanged 的载荷为 'light' 或 'dark'；相同模式不会重复发送，应用回到前台时会补检系统模式。
• 初始值限制：initialMode 仅代表模块创建时的模式，持续响应变化应使用 Hooks、Context 或 eventEmitter。

开源license

本项目基于 MIT 协议，详见 LICENSE 文件。

问题反馈渠道

使用过程中如有问题，欢迎通过 AtomGit 社区提交 Issue，也可在以下 GitCode 仓库反馈：

• https://gitcode.com/hxa-rn/react-native-dark-mode
• https://gitcode.com/hxa-rn/react-native-dark-mode/issues