Expo expo-status-bar 变更日志全解从版本演进看状态栏 API 的取舍与实现细节【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo本文以 Expo 官方仓库中packages/expo-status-bar/CHANGELOG.md为主线完整梳理expo-status-bar从 1.x 到 57.0.1 的版本演进脉络并结合模块源码JS 组件封装、Web 端 no-op 实现、Android 生命周期监听、Config Plugin还原每一项变更记录背后的实现方式帮助读者在升级 SDK 时快速判断状态栏 API 的兼容性影响与正确用法。模块定位与当前版本expo-status-bar提供与 React NativeStatusBarAPI 相同的接口但为 Expo 环境提供了更合理的默认值。根据 README.md 与 package.json包当前版本为57.0.1与 CHANGELOG 顶部条目## 57.0.1 - 2026-07-15一致该版本标记为 “does not introduce any user-facing changes”对用户无可见变更属于维护性发布入口文件为build/StatusBar.js类型声明为build/StatusBar.d.tsexports字段中额外暴露./plugin子路径指向 plugin 构建产物与./app.plugin.jspeerDependencies要求expo、react、react-native均为*即版本需要与所用 Expo SDK 对齐。从 CHANGELOG 的版本号结构可以观察到一个显著特征早期条目为1.0.x3.0.x2020 至 2025-12随后自55.0.02026-01-21起版本号整体对齐了 Expo SDK 的大版本号55、56、57 与仓库中其他 Expo 模块的 SDK 主版本一致。这一跳变本身没有单独的功能说明属于发版策略层面的调整对使用 npm 语义化版本锁定的用户而言跨大版本升级时应以 SDK 版本对应表为准而不是假设 3.x 与 55.x 之间只有小步迭代。56.0.0一次集中清理的破坏性升级56.0.02026-05-05是近期唯一同时包含 Breaking changes 与新特性的版本是升级时最需要关注的条目。移除的 APICHANGELOG 明确列出了被删除的内容对应 PR #44196函数setStatusBarBackgroundColor、setStatusBarNetworkActivityIndicatorVisible、setStatusBarTranslucentStatusBarProps中的属性backgroundColor、networkActivityIndicatorVisible、translucent。这次删除并非突然发生。回看 55.x 的记录55.0.42026-02-25已经先一步把这些 props 与函数“Deprecated and turned into no-ops”废弃并转为空操作。也就是说55.0.4 起到调用它们不再报错也不再生效56.0.0 再把声明彻底删掉遵循了“先 no-op、后移除”的两阶段废弃路径。当前 types.ts 中的StatusBarProps仅剩style、animated、hidden、hideTransitionAnimation四个字段与变更记录相互印证。引入的静态方法56.0.0 将setStatusBarStyle与setStatusBarHidden迁移为StatusBar.setStyle和StatusBar.setHidden静态方法PR #44172旧的命名导出“仍可用但已废弃”。在 NativeStatusBarWrapper.tsx 中可以确认这一实现的准确形态StatusBar.setStyle (style: StatusBarStyle, animated?: boolean): void NativeStatusBar.setBarStyle(styleToBarStyle(style), animated); /** * deprecated Use StatusBar.setStyle instead. This will be removed in a future release. */ export const setStatusBarStyle StatusBar.setStyle;注意两个细节其一setStatusBarStyle只是StatusBar.setStyle的别名导出两者行为完全一致只是前者带deprecated标注其二组件渲染与命令式函数共用同一套styleToBarStyle映射逻辑见下文保证StatusBar styleauto /与StatusBar.setStyle(auto)的解析结果一致。新增的 Config Plugin56.0.0 同时新增了两项能力PR #43968、#44098、#44536带类型注解的 config plugin 函数可通过exports的./plugin子路径引入Android 与 iOS 的状态栏配置插件用于在 prebuild 时写入原生初始状态。此外56.0.0 还移除了对androidStatusBar配置的覆写行为PR #44469用于 Expo Go 同步并移除了react-native-is-edge-to-edge依赖PR #44196。这两条与上面新增的 config plugin 合在一起看可以推断 56.0.0 把“状态栏初始外观”的职责从运行时隐式覆写收敛到了显式的 config plugin 通道上。Config Plugin 源码解析hidden与style如何落到原生工程插件实现位于 plugin/src/withStatusBar.ts输入属性只有两个export type Props { /** Determines whether the status bar starts hidden. */ hidden?: boolean; /** Determines which style the status bar starts with. */ style?: light | dark; };iOS 侧写入 Info.plistsetIOSStatusBarInfoPlist第 75–86 行将属性映射为 Info.plist 键值hidden→UIStatusBarHiddenstyle: dark→UIStatusBarStyleDarkContentstyle: light→UIStatusBarStyleLightContent。withStatusBar-test.ts 的测试覆盖了关键边界会覆盖已有的UIStatusBarHidden/UIStatusBarStyle值、空 props 时不做任何修改、且保留 plist 中其他条目如CFBundleName。Android 侧写入应用主题样式setAndroidStatusBarStyles第 45–66 行向 AppTheme 写入两个样式项插件属性写入的样式名取值作用hiddenexpoStatusBarHiddenString(hidden)自定义主题属性供运行时读取styleandroid:windowLightStatusBarString(style dark)style为dark时置true即深色状态栏文字浅色背景源码注释说明这是为了与setStyle(dark)的语义保持一致测试 withStatusBar-test.ts 还验证了两个幂等性行为重复赋值会重定义已有项redefine而非追加且当某属性被清空时对应样式项会被整体移除remove style when prop is unset。运行时闭环Android 生命周期监听器读取主题属性expoStatusBarHidden这个主题属性在运行时由 StatusBarReactActivityLifecycleListener.kt 消费它在onCreateJS 引擎启动之前通过theme.obtainStyledAttributes(R.attr.expoStatusBarHidden)读取布尔值若为true则用WindowInsetsControllerCompat.hide(statusBars())隐藏状态栏。这条“config plugin 写入 → 主题属性 → Activity 生命周期监听”的链路正是 56.0.0 新增 config plugin 的完整落地方式。与 Expo Go 的衔接withStatusBar主函数第 94–107 行在应用修改前还做了一件事把解析后的 props 提升为config.extra[expo-status-bar]源码注释写明 “Elevate props to a static value on extra so Expo Go can read it”即 Expo Go 通过extra读取这些静态配置。插件最终用createRunOncePlugin包装防止重复执行。resolveProps第 26–43 行对undefined/空对象/仅含undefined值的 props 统一返回undefined插件随即直接放行原 config 不做任何修改——这一点由测试returns undefined for nullish or empty props保证。声明式组件与命令式 API 的现状组件 props 与auto/inverted语义当前组件实现NativeStatusBarWrapper.tsx接受StatusBarProps的四个字段定义见 types.tsProp类型说明styleauto \| inverted \| light \| dark默认autoauto按当前 color scheme 选择浅色模式下dark-content深色模式下light-contentinverted与此相反animatedboolean传递到原生StatusBar的animatedhiddenboolean是否隐藏状态栏hideTransitionAnimationnone \| fade \| slide仅 iOSnone时不传递showHideTransitionstyleToBarStyleNativeStatusBarWrapper.tsx#L79-L95是映射核心auto在浅色主题解析为dark、深色主题解析为lightinverted相反最终统一翻译为原生可识别的light-content/dark-content。该逻辑由 NativeStatusBarWrapper-test.tsx 的五个用例逐一验证auto 跟随主题、inverted 反转主题、light/dark 直接映射。Web 端的降级实现StatusBar.web.ts 是 Web 平台的入口组件直接返回nullsetStyle/setHidden以及两个废弃的命名导出全部是空函数。这与 CHANGELOG 中 1.0.2 的修复“Provide web fallback for styleToBarStyle in order to not produce a warning”一脉相承——Web 端从一开始就定位为非空操作、不产生警告的占位实现。类型导出面对外类型由 src/StatusBar.ts 统一导出StatusBarStyle、StatusBarAnimation、StatusBarProps以及StatusBar、setStatusBarStyle、setStatusBarHidden三个值导出。升级 56.x 后新项目建议直接使用StatusBar.setStyle/StatusBar.setHidden把两个废弃的命名导出视为兼容层。边缘状态栏edge-to-edge相关演进CHANGELOG 中有一条贯穿 2.x56.0.0 的清晰线索记录了这个模块如何跟进而后脱离 edge-to-edge 依赖2.1.02025-04-04开始对潜在的 edge-to-edge 干扰发出警告PR #344782.2.02025-04-11在 edge-to-edge 启用时改用react-native-edge-to-edge的 system bars 能力PR #360872.2.12025-04-14在 edge-to-edge 启用时支持来自SystemBars的命令式函数PR #361563.0.02025-08-13移除react-native-edge-to-edge依赖PR #38768同时完成“Migrate to package exports”PR #3729856.0.0进一步移除react-native-is-edge-to-edge依赖PR #44196注意是-is-系列的另一个包。从变更记录的走向可以推断edge-to-edge 能力逐步内化后模块不再需要以运行时依赖的方式引入第三方包相关行为改由 56.0.0 引入的 config plugin 与 Android 原生代码如上述生命周期监听器承接。其余值得留意的历史条目以下条目虽为小版本但对应了 API 契约或构建层面的实际变化版本日期变更说明3.0.02025-08-13迁移到 package exports移除react-native-edge-to-edge依赖当前 package.json 中exports带expo-source条件字段monorepo 内解析到src/StatusBar.ts源码与本次迁移对应2.0.12025-01-10补齐缺失的react/react-nativepeer 依赖与当前peerDependencies内容一致2.0.02024-10-22“Minimize modules”PR #31088模块瘦身无 API 变更说明1.10.02023-11-14setStatusBarHidden的animation参数改为可选与文档一致对应 types.ts 与 NativeStatusBarWrapper.tsx#L71-L72 中animation?: StatusBarAnimation的可选签名1.9.02023-10-17发布未转译的 JSXPR #24889支持消费方自定义jsx/createElement处理1.8.02023-09-15减小 Web bundle 体积对应 Web 端独立入口文件的拆分1.7.02023-07-28setStatusBarStyle支持animated参数与当前setStyle(style, animated?)签名一致1.4.32023-02-03AndroidcompileSdkVersion/targetSdkVersion提升到 33原生构建配置升级1.0.22020-06-25为 Web 提供styleToBarStyle回退消除警告早期 Web 兼容修复55.0.0、55.0.1、55.0.2、55.0.3、55.0.5、55.0.6、56.0.0 之后的一系列 56.0.156.0.4、57.0.0、57.0.1 均标注为无用户可见变更通常对应依赖升级、锁定文件同步等仓库级维护工作。升级检查清单结合 CHANGELOG 与当前源码结构从 55.x 或更早版本升级到 57.x 时可核对以下几点清理废弃调用搜索项目中的setStatusBarBackgroundColor、setStatusBarNetworkActivityIndicatorVisible、setStatusBarTranslucent与backgroundColor/networkActivityIndicatorVisible/translucentprops——它们在 55.0.4 起已是 no-op56.0.0 起直接不存在迁移命令式 API将setStatusBarStyle(...)/setStatusBarHidden(...)改为StatusBar.setStyle(...)/StatusBar.setHidden(...)旧导出虽仍可编译通过但已标记废弃核对初始状态需求若需要控制应用启动时状态栏是否隐藏/深浅样式使用 56.0.0 新增的 config pluginhidden、style两个属性了解其在原生侧分别映射为 Info.plist 键与 Android 主题样式确认 Web 行为不变Web 端组件返回空、命令式函数为空操作升级不会引入新的 Web 端行为版本对齐该包版本号现已跟随 Expo SDK 大版本55/56/57依赖锁定时应以所用 SDK 对应的expo-status-bar大版本为准。参考路径索引变更日志主体packages/expo-status-bar/CHANGELOG.mdJS 组件与命令式 API 实现packages/expo-status-bar/src/NativeStatusBarWrapper.tsx类型定义packages/expo-status-bar/src/types.tsWeb 端实现packages/expo-status-bar/src/StatusBar.web.tsConfig Plugin 实现与测试packages/expo-status-bar/plugin/src/withStatusBar.ts、packages/expo-status-bar/plugin/src/tests/withStatusBar-test.tsAndroid 运行时监听器packages/expo-status-bar/android/src/main/java/expo/modules/statusbar/StatusBarReactActivityLifecycleListener.kt组件行为测试packages/expo-status-bar/src/tests/NativeStatusBarWrapper-test.tsx包元数据与导出配置packages/expo-status-bar/package.json【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考