Edge-to-Edge Display in Capacitor Without Plugins

您想在Capacitor应用中实现边缘到边缘的显示吗? 您不需要任何hack、插件或工作周围。Capacitor支持通过配置选项实现边缘到边缘的显示，但它并不是很广泛地文档化。 adjustMarginsForEdgeToEdge 许多开发者在__CAPGO_KEEP_0__应用中遇到边缘到边缘布局的问题，尤其是在针对Android 15+时。他们经常使用自定义插件或CSShack来实现现代边缘到边缘的外观。但是，有更好的、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.

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

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

__CAPGO_KEEP_0__提供了

配置选项，专门用于此目的。这在Capacitor的官方配置文档中有详细说明。 adjustMarginsForEdgeToEdge __CAPGO_KEEP_0__ 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 Automatically checks for Android 15+ and the setting. Adjusts margins intelligently based on the device and configuration.

最佳适用场景： 大多数生产应用程序，希望在支持的设备上实现边缘到边缘，而又保持与旧版 Android 版本的兼容性。

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

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

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

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 Considerations

使用全屏幕显示时，可能需要添加一些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";
}

配置后，测试您的应用程序：

Android 15+设备 adjustMarginsForEdgeToEdge- 检查内容是否正确尊严系统栏

旧版Android版本 - 确保向后兼容性
不同屏幕尺寸 - 验证布局在不同设备上工作
浅色和深色主题 - 检查内容是否正确响应主题变化
- 检查内容是否正确响应主题变化 - 测试两种主题模式

避免的常见错误

不要为此使用插件

您不需要第三方插件，如 capacitor-edge-to-edge 或类似。native配置处理此项清洁。如果您需要对系统浏览器进行细粒度控制后启用 adjustMarginsForEdgeToEdge, @capgo/capacitor-导航栏和 @capgo/主页指示器补充native配置而不替换它。

不要混合使用手动实现

如果您正在使用 adjustMarginsForEdgeToEdge,请删除任何手动窗口内边距处理或CSS黑客。

Don’t Forget Safe Area CSS

The config handles margin adjustments, but you still need to use CSS safe area insets for proper content padding.

Migration Guide

If you’re currently using plugins or hacks for edge-to-edge:

Remove any edge-to-edge plugins from your dependencies
Add the config option to your capacitor.config.ts
Clean and rebuild your Android project
Test thoroughly on target devices

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

# Rebuild
npx cap copy android
npx cap open android

Future-Proofing

Remember that Capacitor 8 will make "auto" 记住 __CAPGO_KEEP_0__ 8 将会设定

默认值。为了准备： "auto" 测试 现在
以捕捉早期问题 更新您的CSS
以适当处理安全区域 检查您的布局

在边缘到边缘启用的设备上

结论

在 Capacitor 中，使用全屏显示不需要插件、hack 或复杂的工作-around。该配置选项提供了一个干净、原生的解决方案，且已获得官方支持并且是未来可行的。 adjustMarginsForEdgeToEdge 开始

对于大多数应用程序，测试在设备上，添加适当的安全区域 CSS。您的应用程序将在 Android 15 和更高版本中以最小的努力准备就绪。 "auto" 问题或遇到问题？

在 __CAPGO_KEEP_0__ 社区和 The Capacitor community and 是获取额外帮助的好资源。继续使用 __CAPGO_KEEP_0__ 全屏显示而不使用插件

Keep going from Edge-to-Edge Display in Capacitor Without Plugins

如果您正在使用 边缘到边缘显示在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-video-player,和使用@capgo/capacitor-native-navigation 为原生能力在使用 @capgo/capacitor 原生导航。

Capacitor无需插件的全边屏幕配置