@expo-harmony/expo-splash-screen 55.0.21-harmony.1

package/README.md

@@ -0,0 +1,40 @@
+# @expo-harmony/expo-splash-screen
+
+[**GitHub 仓库**](https://github.com/renbaoshuo/expo-harmony/tree/master/packages/expo-splash-screen)
+
+为 HarmonyOS 上的 React Native 应用提供 Expo SplashScreen 的原生实现，与官方同版本的 `expo-splash-screen` 配套使用。支持控制启动画面的自动隐藏、手动隐藏和淡出过渡，以及通过配置插件设置启动图片、背景色和深色模式资源。
+
+如果需要在预构建时配置 HarmonyOS 原生启动画面，请在 `app.json` 的 `plugins` 中传入 `@expo-harmony/expo-splash-screen`：
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@expo-harmony/expo-splash-screen",
+        {
+          "backgroundColor": "#FFFFFF",
+          "image": "./assets/splash.png",
+          "imageWidth": 160,
+          "resizeMode": "contain",
+          "dark": {
+            "backgroundColor": "#000000",
+            "image": "./assets/splash-dark.png"
+          }
+        }
+      ]
+    ]
+  }
+}
+```
+
+`resizeMode` 支持 `contain`、`cover` 和 `native`。修改配置后需要重新 prebuild，使用 `dark` 资源跟随系统外观时，请将 `expo.userInterfaceStyle` 设置为 `automatic`。
+
+运行时可通过 `SplashScreen.preventAutoHideAsync()` 保持启动画面，待应用准备就绪后调用 `SplashScreen.hide()` 或 `SplashScreen.hideAsync()` 隐藏，也可通过 `SplashScreen.setOptions()` 设置淡出效果和时长。
+
+## Author
+
+**expo-harmony** © [Baoshuo](https://github.com/renbaoshuo), Released under the MIT License.<br>
+Authored and maintained by Baoshuo with help from [contributors](https://github.com/renbaoshuo/expo-harmony/contributors).
+
+> [Personal Website](https://baoshuo.ren) · [Blog](https://blog.baoshuo.ren) · GitHub [@renbaoshuo](https://github.com/renbaoshuo) · Twitter [@baoshuo](https://twitter.com/baoshuo)

package/app.plugin.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./plugin/withSplashScreen');

package/expo-module.config.json

@@ -0,0 +1,7 @@
+{
+  "platforms": ["harmony"],
+  "harmony": {
+    "modules": ["ExpoSplashScreenModule"],
+    "rootViewComponents": ["ExpoSplashScreenView"]
+  }
+}

package/harmony/library/oh-package.json5

@@ -0,0 +1,23 @@
+{
+  "name": "@expo-harmony/expo-splash-screen",
+  "version": "55.0.21-harmony.1",
+  "description": "HarmonyOS port of expo-splash-screen",
+  "keywords": [
+    "react-native",
+    "expo",
+    "expo-harmony",
+    "harmonyos"
+  ],
+  "homepage": "https://github.com/renbaoshuo/expo-harmony/tree/master/packages/expo-splash-screen#readme",
+  "repository": "https://github.com/renbaoshuo/expo-harmony",
+  "author": {
+    "name": "Baoshuo",
+    "email": "i@baoshuo.ren",
+    "url": "https://github.com/renbaoshuo"
+  },
+  "main": "Index.ets",
+  "license": "MIT",
+  "dependencies": {
+    "@expo-harmony/expo-modules-core": "55.0.25-harmony.1"
+  }
+}

package/index.d.ts

@@ -0,0 +1 @@
+export {};

package/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = Object.freeze({});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@expo-harmony/expo-splash-screen",
+  "version": "55.0.21-harmony.1",
+  "description": "HarmonyOS port of expo-splash-screen",
+  "keywords": [
+    "react-native",
+    "expo",
+    "expo-harmony",
+    "harmonyos"
+  ],
+  "homepage": "https://github.com/renbaoshuo/expo-harmony/tree/master/packages/expo-splash-screen#readme",
+  "bugs": "https://github.com/renbaoshuo/expo-harmony/issues",
+  "license": "MIT",
+  "author": "Baoshuo <i@baoshuo.ren>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/renbaoshuo/expo-harmony.git",
+    "directory": "packages/expo-splash-screen"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "harmony:clean": "expo-harmony-module prepare --clean-only",
+    "harmony:build": "expo-harmony-module prepare",
+    "prepack": "expo-harmony-module prepack"
+  },
+  "dependencies": {
+    "@expo-harmony/config-plugins": "55.0.10-harmony.1",
+    "@expo/config-plugins": "55.0.10"
+  },
+  "peerDependencies": {
+    "@expo-harmony/expo-modules-core": "55.0.25-harmony.1",
+    "expo-splash-screen": "55.0.21"
+  },
+  "devDependencies": {
+    "@expo-harmony/expo-module-scripts": "55.0.0-harmony.0",
+    "@expo-harmony/expo-modules-core": "55.0.25-harmony.1",
+    "@react-native-oh/react-native-harmony": "0.84.1",
+    "expo": "55.0.26",
+    "expo-modules-core": "55.0.25",
+    "expo-splash-screen": "55.0.21",
+    "react": "19.2.3",
+    "react-native": "0.84.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin/withSplashScreen.d.ts

@@ -0,0 +1,22 @@
+import type { ConfigPlugin } from '@expo/config-plugins';
+
+export type HarmonySplashResizeMode = 'contain' | 'cover' | 'native';
+
+export interface HarmonySplashScreenConfig {
+  backgroundColor?: string;
+  imageWidth?: number;
+  image?: string;
+  resizeMode?: HarmonySplashResizeMode;
+  dark?: {
+    backgroundColor?: string;
+    image?: string;
+  };
+}
+
+export interface SplashScreenPluginConfig extends HarmonySplashScreenConfig {
+  harmony?: HarmonySplashScreenConfig;
+}
+
+declare const withSplashScreen: ConfigPlugin<SplashScreenPluginConfig | null>;
+
+export = withSplashScreen;

package/plugin/withSplashScreen.js

@@ -0,0 +1,340 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { createRunOncePlugin } = require('@expo/config-plugins');
+const {
+  HarmonyConfigPluginError,
+  registerHarmonyConfigPlugin,
+  withColors,
+  withMedia,
+  withModuleJson,
+  withStrings,
+} = require('@expo-harmony/config-plugins');
+
+const pkg = require('../package.json');
+
+const MEDIA = 'expo_splash_screen';
+const BACKGROUND = 'expo_splash_screen_background';
+const RESIZE_MODE = 'expo_splash_screen_resize_mode';
+const IMAGE_WIDTH = 'expo_splash_screen_image_width';
+const RESIZE_MODES = new Set(['contain', 'cover', 'native']);
+const COLOR = /^#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?$/;
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.svg', '.webp', '.gif']);
+const TRANSPARENT_PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M/wHwAF/gL+3MxZ5wAAAABJRU5ErkJggg==', 'base64');
+const OWNERSHIP = Object.freeze({
+  ability: {
+    startWindowBackground: '$color:expo_splash_screen_background',
+    startWindowIcon: '$media:expo_splash_screen',
+  },
+  resources: {
+    colors: {
+      entry: [BACKGROUND],
+      entryDark: [BACKGROUND],
+    },
+    media: {
+      entry: [MEDIA],
+      entryDark: [MEDIA],
+    },
+    strings: {
+      entry: [
+        'expo_splash_screen_has_dark_image',
+        'expo_splash_screen_has_image',
+        'expo_splash_screen_image_width',
+        'expo_splash_screen_resize_mode',
+      ],
+    },
+  },
+});
+
+function setResource(items, name, value) {
+  const next = (Array.isArray(items) ? items : []).filter(item => item?.name !== name);
+
+  next.push({ name, value });
+  next.sort((left, right) => left.name.localeCompare(right.name, 'en'));
+
+  return next;
+}
+
+function removeResource(items, name) {
+  return (Array.isArray(items) ? items : []).filter(item => item?.name !== name);
+}
+
+function replaceMedia(files, base, file) {
+  for (const name of Object.keys(files)) {
+    if (path.parse(name).name === base) delete files[name];
+  }
+
+  if (file) files[file.name] = { ...file, replaceBase: true };
+}
+
+function normalizeColor(value, field, fallback) {
+  const color = value ?? fallback;
+  if (typeof color !== 'string' || !COLOR.test(color)) {
+    throw new TypeError(`${field} must be #RRGGBB or #RRGGBBAA.`);
+  }
+
+  const upper = color.toUpperCase();
+  if (upper.length === 9) {
+    // Expo config follows CSS/React Native #RRGGBBAA, while Harmony resource
+    // colors use #AARRGGBB. Six-digit opaque colors have the same ordering.
+    return `#${upper.slice(7, 9)}${upper.slice(1, 7)}`;
+  }
+
+  return upper;
+}
+
+function normalizeImageWidth(value) {
+  const width = value ?? 100;
+  if (typeof width !== 'number' || !Number.isFinite(width) || width <= 0) {
+    throw new TypeError('imageWidth must be a positive finite number.');
+  }
+
+  return width;
+}
+
+function normalizeImage(value, field) {
+  if (value == null) return null;
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new TypeError(`${field} must be a non-empty file path.`);
+  }
+
+  const ext = path.extname(value).toLowerCase();
+  if (!IMAGE_EXTENSIONS.has(ext)) {
+    throw new TypeError(`${field} must use png, jpg, jpeg, svg, webp, or gif.`);
+  }
+
+  return { value, extension: ext };
+}
+
+function normalizeObject(value, field) {
+  if (value == null) return {};
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${field} splash options must be an object.`);
+  }
+
+  return value;
+}
+
+function normalizeProps(config, props) {
+  if (props != null && (typeof props !== 'object' || Array.isArray(props))) {
+    throw new TypeError('expo-splash-screen plugin options must be an object or null.');
+  }
+
+  const expo = props == null ? normalizeObject(config?.splash, 'Expo app config') : {};
+  const options = { ...expo, ...(props ?? {}) };
+  const harmony = normalizeObject(options.harmony, 'harmony');
+  const dark = {
+    ...normalizeObject(options.dark, 'dark'),
+    ...normalizeObject(harmony.dark, 'harmony.dark'),
+  };
+  const resize = harmony.resizeMode ?? options.resizeMode ?? 'contain';
+
+  if (!RESIZE_MODES.has(resize)) {
+    throw new TypeError(`Unsupported Harmony splash resizeMode: ${String(resize)}.`);
+  }
+
+  return {
+    backgroundColor: normalizeColor(
+      harmony.backgroundColor ?? options.backgroundColor,
+      'backgroundColor',
+      '#FFFFFF'
+    ),
+    darkBackgroundColor: normalizeColor(
+      dark.backgroundColor,
+      'dark.backgroundColor',
+      harmony.backgroundColor ?? options.backgroundColor ?? '#FFFFFF'
+    ),
+    image: normalizeImage(harmony.image ?? options.image, 'image'),
+    darkImage: normalizeImage(dark.image, 'dark.image'),
+    imageWidth: normalizeImageWidth(harmony.imageWidth ?? options.imageWidth),
+    resizeMode: resize,
+  };
+}
+
+function resolveInterfaceStyle(config) {
+  const style = config?.harmony?.userInterfaceStyle ?? config?.userInterfaceStyle ?? 'light';
+  if (!['light', 'dark', 'automatic'].includes(style)) {
+    throw new TypeError(`Unsupported Harmony userInterfaceStyle: ${String(style)}.`);
+  }
+
+  return style;
+}
+
+function resolveQualifiedResources(options, style) {
+  if (style === 'dark') {
+    const image = options.darkImage ?? options.image;
+
+    return {
+      entryBackgroundColor: options.darkBackgroundColor,
+      entryDarkBackgroundColor: options.darkBackgroundColor,
+      entryImage: image,
+      entryDarkImage: image,
+    };
+  }
+
+  if (style === 'light') {
+    return {
+      entryBackgroundColor: options.backgroundColor,
+      entryDarkBackgroundColor: options.backgroundColor,
+      entryImage: options.image,
+      entryDarkImage: options.image,
+    };
+  }
+
+  return {
+    entryBackgroundColor: options.backgroundColor,
+    entryDarkBackgroundColor: options.darkBackgroundColor,
+    entryImage: options.image,
+    entryDarkImage: options.darkImage,
+  };
+}
+
+function resolveImage(root, image, field) {
+  if (!image) return null;
+
+  const source = path.resolve(root, image.value);
+  let stat;
+
+  try {
+    stat = fs.statSync(source, { throwIfNoEntry: false });
+  } catch (cause) {
+    throw new HarmonyConfigPluginError(
+      'ERR_HARMONY_CONFIG_INVALID',
+      `Unable to inspect Harmony splash ${field}: ${source}`,
+      { operation: 'resolve-splash-image', file: source, cause }
+    );
+  }
+
+  if (!stat?.isFile()) {
+    throw new HarmonyConfigPluginError(
+      'ERR_HARMONY_CONFIG_INVALID',
+      `${field} does not resolve to a file: ${source}`,
+      { operation: 'resolve-splash-image', file: source }
+    );
+  }
+
+  return { name: `${MEDIA}${image.extension}`, source };
+}
+
+function updateEntryAbility(json) {
+  const module = json.module;
+  if (!module || typeof module !== 'object' || !Array.isArray(module.abilities)) {
+    throw new HarmonyConfigPluginError(
+      'ERR_HARMONY_CONFIG_INVALID',
+      'Harmony splash configuration requires module.abilities.',
+      { operation: 'configure-splash-entry-ability' }
+    );
+  }
+
+  const main = module.mainElement;
+  const matches = module.abilities.filter((ability, index) => (
+    ability && typeof ability === 'object'
+    && (typeof main === 'string' ? ability.name === main : index === 0)
+  ));
+  if (matches.length !== 1) {
+    throw new HarmonyConfigPluginError(
+      'ERR_HARMONY_CONFIG_INVALID',
+      `Harmony splash configuration expected exactly one main Ability, found ${matches.length}.`,
+      { operation: 'configure-splash-entry-ability' }
+    );
+  }
+
+  const abilities = module.abilities.map((ability, index) => {
+    if (!ability || typeof ability !== 'object') return ability;
+
+    const selected = typeof main === 'string' ? ability.name === main : index === 0;
+    if (!selected) return ability;
+
+    return {
+      ...ability,
+      startWindowBackground: '$color:expo_splash_screen_background',
+      startWindowIcon: '$media:expo_splash_screen',
+    };
+  });
+
+  return { ...json, module: { ...module, abilities } };
+}
+
+const withHarmonySplashScreen = (config, props) => {
+  const enabled = config.harmony?.bundleName || config.platforms?.includes('harmony');
+  if (!enabled) return config;
+
+  config = registerHarmonyConfigPlugin(config, pkg.name, OWNERSHIP);
+
+  let cache;
+
+  const resolveOptions = () => {
+    if (cache) return cache;
+
+    const normalized = normalizeProps(config, props);
+
+    cache = {
+      normalized,
+      qualified: resolveQualifiedResources(normalized, resolveInterfaceStyle(config)),
+    };
+
+    return cache;
+  };
+
+  config = withModuleJson(config, (mod) => {
+    mod.modResults = updateEntryAbility(mod.modResults);
+
+    return mod;
+  });
+
+  config = withColors(config, (mod) => {
+    const { qualified } = resolveOptions();
+
+    mod.modResults.entry ??= {};
+    mod.modResults.entryDark ??= {};
+
+    mod.modResults.entry.color = setResource(
+      mod.modResults.entry.color,
+      BACKGROUND,
+      qualified.entryBackgroundColor
+    );
+    mod.modResults.entryDark.color = setResource(
+      mod.modResults.entryDark.color,
+      BACKGROUND,
+      qualified.entryDarkBackgroundColor
+    );
+
+    return mod;
+  });
+
+  config = withStrings(config, (mod) => {
+    const { normalized } = resolveOptions();
+    let strings = mod.modResults.entry?.string;
+
+    strings = setResource(strings, RESIZE_MODE, normalized.resizeMode);
+    strings = setResource(strings, IMAGE_WIDTH, String(normalized.imageWidth));
+    strings = removeResource(strings, 'expo_splash_screen_has_image');
+    strings = removeResource(strings, 'expo_splash_screen_has_dark_image');
+
+    mod.modResults.entry ??= {};
+    mod.modResults.entry.string = strings;
+
+    return mod;
+  });
+
+  config = withMedia(config, (mod) => {
+    const { qualified } = resolveOptions();
+    const root = mod.modRequest.projectRoot;
+    const image = resolveImage(root, qualified.entryImage, 'image');
+    const dark = resolveImage(root, qualified.entryDarkImage, 'darkImage');
+
+    mod.modResults.entry ??= {};
+    mod.modResults.entryDark ??= {};
+
+    replaceMedia(mod.modResults.entry, MEDIA, image ?? { name: `${MEDIA}.png`, content: TRANSPARENT_PNG });
+    replaceMedia(mod.modResults.entryDark, MEDIA, dark);
+
+    return mod;
+  });
+
+  return config;
+};
+
+module.exports = createRunOncePlugin(withHarmonySplashScreen, pkg.name, pkg.version);