Edge-to-Edge Display in Capacitor Without Plugins

尝试在Capacitor应用中实现全屏显示吗? 您不需要任何hack、插件或工作绕过。Capacitor支持全屏显示的官方配置选项 - 它只是不被广泛文档化。 adjustMarginsForEdgeToEdge 许多开发者在__CAPGO_KEEP_0__应用中实现全屏布局时遇到困难，尤其是在针对Android 15+时。他们经常使用自定义插件或CSS hack来实现现代全屏显示的外观。但是有更好的、native的方法。

Many developers struggle with edge-to-edge layouts in Capacitor apps, especially when targeting Android 15+. They often resort to custom plugins or CSS hacks to achieve the modern edge-to-edge look. But there’s a better, native way.

What is Edge-to-Edge Display?

边缘到边缘显示允许您的应用内容延伸到系统栏（状态栏和导航栏）后面，创建一个更沉浸、更现代的UI体验。从Android 15开始，Google将边缘到边缘作为所有应用的标准。

官方解决方案：调整边缘到边缘的边距

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 大多数生产应用程序，希望在支持的设备上实现边缘到边缘，同时保持与旧版 Android 版本的兼容性。

它做什么： 无论 Android 版本或其他设置如何，都强制边缘调整。

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

适合： 希望在所有支持的 Android 版本上实现边缘行为的应用程序。

它做什么： 无论 Android 版本或其他设置如何，都强制边缘调整。

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

What it does: 完全禁用自动边距调整。

Best for: 手动处理边缘到边缘布局或不希望边缘到边缘行为的应用。

Note: 目前 "disable" 是默认值，但将在Capgo 8中更改为 "auto" in Capacitor 8.

从 Android 15 开始，Google 开始强制边缘到边缘显示为默认行为。未正确处理边缘到边缘布局的应用可能会遇到以下 UI 问题：

内容被系统栏遮挡

不适合的间距和填充
Currently
设备间不一致的外观
用户体验差

通过使用官方 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来处理安全区域：

/* 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";
}

测试您的配置

配置后，测试您的应用程序在： adjustMarginsForEdgeToEdgeAndroid 15+设备

测试您的配置后，确保您的应用程序在以下设备上正常运行： - 确保内容正确处理系统栏
旧版 Android 版本 - 确保向后兼容
不同屏幕尺寸 - 验证布局在不同设备上正常工作
浅色和深色主题 - 测试两种主题模式

常见错误

避免使用此类插件

您不需要像 capacitor-edge-to-edge 或类似的第三方插件。native 配置可以干净地处理此类问题。

避免与手动实现混淆

如果您正在使用 adjustMarginsForEdgeToEdge,请移除任何手动窗口边距处理或CSShack。

记住安全区域CSS

配置文件处理了边距调整，但您仍需要使用CSS安全区域边距来获得正确的内容填充。

迁移指南

如果您当前正在使用边缘到边缘的插件或hack:

从您的依赖项中移除任何边缘到边缘的插件 添加配置选项
到您的 清理并重新构建 capacitor.config.ts
您的Android项目 __CAPGO_KEEP_0__
进行彻底的测试 在目标设备上

# 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中的全屏显示不需要插件、hack或复杂的工作-around。配置选项提供了一个干净、原生的解决方案，这是官方支持的和未来可靠的。 adjustMarginsForEdgeToEdge 对于大多数应用程序，首先测试在设备上，添加适当的安全区域CSS。您的应用程序将以最小的努力准备好Android 15和更高版本。

问题或遇到问题？ "auto" __CAPGO_KEEP_0__社区和

官方文档 Capacitor不需要插件、hack或复杂的工作-around来实现全屏显示。配置选项提供了一个干净、原生的解决方案，这是官方支持的和未来可靠的。对于大多数应用程序，首先测试在设备上，添加适当的安全区域CSS。您的应用程序将以最小的努力准备好Android 15和更高版本。 are great resources for additional help.

继续使用无插件的Capacitor从边缘到边缘显示

如果您正在使用 无插件的Capacitor从边缘到边缘显示 来规划原生媒体和界面行为，连接它与使用@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-视频播放器的实现细节，使用 @capgo/capacitor-原生导航为了 @capgo/capacitor-原生导航的原生能力，

无需插件的Capacitor全屏显示