在 Capacitor 中无需插件实现 Edge-to-Edge 显示

想在 Capacitor 应用中实现 edge-to-edge 显示？ 无需任何 hack、插件或变通方案。Capacitor 通过以下方式官方支持 edge-to-edge 显示： adjustMarginsForEdgeToEdge 配置选项——只是目前缺乏广泛的文档说明。

Capacitor 应用中的沉浸式（edge-to-edge）布局让许多开发者感到头疼，尤其是在适配 Android 15+ 时。他们通常不得不依赖自定义插件或 CSS Hack 来实现现代化的沉浸式视觉效果。但其实有一种更优雅的原生方案。

什么是 Edge-to-Edge 显示？

沉浸式显示允许应用内容延伸至系统栏（状态栏和导航栏）下方，从而打造更具沉浸感、更现代的 UI 体验。从 Android 15 开始，Google 正推动将沉浸式布局作为所有应用的标配。

官方解决方案：adjustMarginsForEdgeToEdge

Capacitor 提供了专门用于此目的的 adjustMarginsForEdgeToEdge 配置选项。这在官方 Capacitor 配置文档中有所说明，但很容易被忽略。

如何配置

将此添加到你的 capacitor.config.ts 或 capacitor.config.json:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'My App',
  webDir: 'dist',
  android: {
    adjustMarginsForEdgeToEdge: 'auto' // or 'force' or 'disable'
  }
};

export default config;

或者使用 JSON 格式：

{
  "appId": "com.example.app",
  "appName": "My App",
  "webDir": "dist",
  "android": {
    "adjustMarginsForEdgeToEdge": "auto"
  }
}

配置选项

本指南中介绍的 adjustMarginsForEdgeToEdge 该选项接受三个值：

1. `"auto"` （推荐）

adjustMarginsForEdgeToEdge: 'auto'

功能说明： 自动检测 Android 15+ 及相关 windowOptOutEdgeToEdgeEnforcement 设置。根据设备和配置智能调整边距。

适用场景： 适用于大多数生产级 App，旨在支持设备上实现沉浸式体验，同时兼顾旧版 Android 的兼容性。

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

功能说明： 无论 Android 版本或其它设置如何，强制进行边距调整以实现沉浸式体验。

适用场景： 希望在所有支持的 Android 版本上实现沉浸式（edge-to-edge）体验的应用。

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

功能说明： 完全禁用自动边距调整。

适用场景： 手动处理沉浸式布局或不需要沉浸式体验的应用。

注意： 目前 "disable" 是默认设置，但之后将更改为 "auto" 在 Capacitor 8 中。

为什么这对 Android 15+ 很重要

从 Android 15 开始，Google 将强制要求将沉浸式显示作为默认行为。未能正确处理沉浸式布局的应用可能会遇到如下 UI 问题：

内容被系统状态栏遮挡
间距与内边距显得很突兀
不同设备上的显示效果不一致
用户体验差

通过使用官方的 adjustMarginsForEdgeToEdge 配置，可以确保您的应用能够正确处理这些变化，无需编写自定义的 code。

完整示例

以下是现代 Capacitor 应用的完整配置示例：

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.myapp',
  appName: 'My Awesome App',
  webDir: 'www',
  server: {
    androidScheme: 'https'
  },
  android: {
    // Enable edge-to-edge automatically on supported devices
    adjustMarginsForEdgeToEdge: 'auto',

    // Other Android config options...
    backgroundColor: '#ffffff'
  }
};

export default config;

CSS 注意事项

在使用沉浸式全屏显示时，您可能需要添加一些 CSS 来处理安全区域 (safe areas)：

/* Add padding for system bars */
body {
  padding-top: env(safe-area-inset-top);
  padding-bottom: env(safe-area-inset-bottom);
  padding-left: env(safe-area-inset-left);
  padding-right: env(safe-area-inset-right);
}

/* Or use viewport-fit */
meta[name="viewport"] {
  content: "width=device-width, initial-scale=1, viewport-fit=cover";
}

测试您的配置

配置完成后 adjustMarginsForEdgeToEdge，在以下设备上测试您的应用：

Android 15+ 设备 - 检查内容是否正确避开了系统状态栏和导航栏
旧版 Android 版本 - 确保向下兼容性
不同的屏幕尺寸 - 验证布局在不同设备上的适配情况
浅色和深色主题 - 测试两种主题模式

应避免的常见错误

不要为此使用插件

您不需要像以下这类第三方插件： capacitor-edge-to-edge 或类似方式。Native config 可以优雅地处理这些问题。如果你在启用后需要对系统 Chrome 进行精细化控制， adjustMarginsForEdgeToEdge, @capgo/capacitor-navigation-bar 以及 @capgo/home-indicator 可以在不替换 native config 的前提下对其进行补充。

不要与手动实现混用

如果你在使用 adjustMarginsForEdgeToEdge，请移除你之前添加的所有手动 window insets 处理或 CSS hack。

不要忘记 Safe Area CSS

Config 会处理 margin 调整，但你仍需使用 CSS safe area insets 来确保内容内边距正确。

迁移指南

如果你目前正在使用插件或 hack 来实现 edge-to-edge：

移除所有 edge-to-edge 插件 并从依赖项中删除
添加配置选项 其添加到你的 capacitor.config.ts
清理并重新构建 你的 Android 项目
进行彻底测试 在目标设备上

# Clean the Android project
npx cap sync android
cd android
./gradlew clean
cd ..

# Rebuild
npx cap copy android
npx cap open android

面向未来

请记住 Capacitor 8 将设为 "auto" 默认值。准备工作：

使用以下内容进行测试 "auto" 刚刚 以便尽早发现问题
更新您的 CSS 以正确处理安全区域
检查您的布局 在开启沉浸式体验的设备上

总结

Capacitor 中的沉浸式显示无需插件、黑科技或复杂的变通方案。只需 adjustMarginsForEdgeToEdge 该配置选项提供了一个官方支持且面向未来的原生解决方案。

从这里开始 "auto" 对于大多数应用，请在不同设备上进行彻底测试，并添加适当的安全区域 CSS。只需极少的工作量，您的应用即可适配 Android 15 及更高版本。

有疑问或遇到问题？ Capacitor 社区和官方文档都是获取额外帮助的绝佳资源。

继续阅读：在 Capacitor 中无需插件实现全屏显示

如果你正在使用 在 Capacitor 中无需插件实现 Edge-to-Edge 显示 来规划原生媒体和界面行为，并将其与使用 @capgo/capacitor-live-activities 用于使用 @capgo/capacitor-live-activities 时的原生能力， @capgo/capacitor-live-activities 在 @capgo/capacitor-live-activities 中的实现细节，使用 @capgo/capacitor-video-player 用于使用 @capgo/capacitor-video-player 时的原生能力， @capgo/capacitor-video-player 在 @capgo/capacitor-video-player 中的实现细节，以及使用 @capgo/capacitor-native-navigation 用于使用 @capgo/capacitor-native-navigation. 时的原生能力