@bingtang-rn/react-native-extended-stylesheet for HarmonyOS

本项目基于 react-native-extended-stylesheet 开发，为 React Native 鸿蒙（OpenHarmony）适配版本。如果在使用过程中有任何问题，可以在GitCode提Issue，会及时跟进。issue地址：issues。

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 见发布记录 | 0.12.0 | 0.72+ | 是/否 | API17+ |

安装

npm install @bingtang-rn/react-native-extended-stylesheet

使用

import EStyleSheet from 'react-native-extended-stylesheet';

// 1. 注册样式表（含 $var / rem / percent / operation / @media / 下划线样式）
const styles = EStyleSheet.create({
  $accent: '#007aff',           // 局部变量
  card: {
    backgroundColor: '$cardBg', // 全局变量引用
    padding: '0.8rem',          // rem 单位
    marginHorizontal: '4%',     // 百分比
    '@media harmony': {         // 平台媒体查询（鸿蒙端命中）
      borderWidth: 2,
      borderColor: '$accent',
    },
  },
  title: {
    fontSize: '1.2rem',
    color: '$textColor',
    '@media (max-width: 350)': { fontSize: '1rem' },
    '@media (min-width: 500)': { fontSize: '1.4rem' },
  },
  _underscored: {                // 下划线样式保留计算后原始值，可读 styles._underscored.fontSize
    fontSize: '1.5rem',
    color: '$accent',
  },
});

// 2. 设置全局变量并计算所有样式表，触发 'build' 事件
EStyleSheet.build({
  $theme: 'light',
  $textColor: '#1a1a1a',
  $cardBg: '#ffffff',
  $rem: 16,
  $scale: 1,
});

// 3. 单值即时计算
const halfWidth = EStyleSheet.value('0.5 * 100%', 'width');
const accent = EStyleSheet.value('$accent');
const remPx = EStyleSheet.value('1.5rem');

// 4. 伪类（first / even / odd / last）
<View style={EStyleSheet.child(styles, 'row', index, count)} />

// 5. 订阅 build 事件
EStyleSheet.subscribe('build', () => { /* 主题切换后刷新 */ });
EStyleSheet.unsubscribe('build', listener);

// 6. 清缓存（主题切换 / HMR）
EStyleSheet.clearCache();
EStyleSheet.build(darkTheme);

// 7. 代理的 StyleSheet 静态属性（与 RN StyleSheet 等价）
const hairline = EStyleSheet.hairlineWidth;
const flatten = EStyleSheet.flatten;

import 时使用原库名 'react-native-extended-stylesheet'，而非鸿蒙包名 @bingtang-rn/react-native-extended-stylesheet（由 harmony.alias 自动映射）。

平台差异：

• HarmonyOS 上 Platform.OS 返回 'harmony'；写 @media harmony 即可在鸿蒙端命中分支，@media ios / @media android 在鸿蒙不命中（预期行为）。
• setStyleAttributePreprocessor 在新版 RN 已废弃，鸿蒙端可能为 undefined；库用 getter 读取，不抛错。

权限要求：

• 本库为纯 JS 实现，无任何运行时权限需求。

Link

| 版本 | 是否支持 Autolink | |------|------------------| | 当前版本 | 是/否 |

如使用版本支持 Autolink 且工程已接入，可跳过手动配置。

说明：本模块需要同时在 C++ 侧和 ETS 侧注册 Package。

1. Overrides RN SDK

在工程根目录 oh-package.json5 添加：

{
  "overrides": {
    "@rnoh/react-native-openharmony": "./react_native_openharmony"
  }
}

2. 引入原生端依赖

打开 entry/oh-package.json5，添加：

"dependencies": {
  "@bingtang-rn/react-native-extended-stylesheet": "file:../../node_modules/@bingtang-rn/react-native-extended-stylesheet/harmony/extended_stylesheet.har"
}

执行 ohpm install。

3. 配置 CMakeLists

打开 entry/src/main/cpp/CMakeLists.txt，添加：

set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

add_subdirectory("${OH_MODULES}/@bingtang-rn/react-native-extended-stylesheet/src/main/cpp" ./extended_stylesheet)

target_link_libraries(rnoh_app PUBLIC extended_stylesheet)

4. 注册 Package（C++ 侧）

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "ExtendedStylesheetPackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<ExtendedStylesheetPackage>(ctx),
    };
}

5. 注册 Package（ETS 侧）

打开 entry/src/main/ets/RNPackagesFactory.ets，添加：

import { ExtendedStylesheetPackage } from '@bingtang-rn/react-native-extended-stylesheet/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new ExtendedStylesheetPackage(ctx),
  ];
}

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | create(styles) | 创建扩展样式表，注册后立即计算 | styles: 对象（含 $var / rem / percent / operation / @media / 下划线样式） | 含原生 id + _下划线 计算值 + $var 局部变量的结果对象 | ✅ 完全支持 | | build(globalVars?) | 计算所有已注册样式表，设置全局变量/媒体查询，触发 build 事件 | rawGlobalVars?: 含 $var / @media 的对象 | void | ✅ 完全支持 | | value(expr, prop?) | 即时计算单个表达式 | expr: string | number | Function；prop?: string（percent 基准） | number | string | 原值 | ✅ 完全支持 | | child(styles, styleName, index, count) | 按 index/count 拼装伪类样式 | styles, styleName, index: number, count: number | 单 id 或 id 数组 | ✅ 完全支持 | | subscribe(event, listener) | 订阅事件（仅 'build'）；已 build 则立即回调一次 | event: 'build'，listener: Function | void | ✅ 完全支持 | | unsubscribe(event, listener) | 取消订阅 build 事件 | event: 'build'，listener: Function | void | ✅ 完全支持 | | clearCache() | 清除所有样式表缓存（主题切换/HMR 用） | 无 | void | ✅ 完全支持 | | flatten（代理） | 代理到 RN StyleSheet.flatten | ...styles: 数组 | 多参数 | 扁平样式对象 | ✅ 完全支持 | | hairlineWidth（代理） | 代理到 RN StyleSheet.hairlineWidth | 无 | number | ✅ 完全支持 | | absoluteFill（代理） | 代理到 RN StyleSheet.absoluteFill | 无 | 样式对象 | ✅ 完全支持 | | absoluteFillObject（代理） | 代理到 RN StyleSheet.absoluteFillObject | 无 | 样式对象 | ✅ 完全支持 | | setStyleAttributePreprocessor（代理） | 代理到 RN StyleSheet.setStyleAttributePreprocessor | — | — | ⚠️ 部分支持（新版 RN 已废弃，鸿蒙端可能为 undefined，库用 getter 读取不抛错） |

平台差异

• HarmonyOS 端 Platform.OS === 'harmony'：写 @media harmony 命中分支；@media ios / @media android 不命中（预期行为）。
• setStyleAttributePreprocessor 在新版 RN 已废弃，鸿蒙端可能为 undefined。

未实现功能

无。本库为纯 JS，鸿蒙端源码逐字节与原库一致，所有公开方法均可用。

使用限制

• percent.js 在模块加载时一次性捕获 Dimensions.get('window') 宽高，不监听方向变化；横竖屏切换后百分比基准不更新（库已知限制，非鸿蒙特有）。
• 库已标记 deprecated（原库 README deprecation notice），不再更新，但功能完整可用。

快速验证（运行 Example）

前置条件

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

运行步骤

1. 克隆仓库

git clone <仓库地址>
cd <仓库目录>

2. 安装依赖并构建

npm install --legacy-peer-deps
npm pack           # 生成 tgz 包（会自动触发 prepare 构建 JS 产物）

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。

约束与限制

兼容性

• RNOH: 0.72+
• HarmonyOS SDK: API 17+
• DevEco Studio: 5.0+

遗留问题

无（或列出已知问题）

开源协议

本项目基于 [原始库协议](原始库 LICENSE 链接)，详见 LICENSE 文件。