Edge-to-Edge Display in Capacitor Without Plugins

尝试在Capacitor应用中实现边缘到边缘显示吗? 您不需要任何hack、插件或工作-around。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开始，谷歌将边缘到边缘作为所有应用的标准。

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

__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;

如何配置Capacitor以支持边缘到边缘显示

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

配置选项

选项接受三个值: adjustMarginsForEdgeToEdge （推荐）

1. `"auto"` 它做了什么：

adjustMarginsForEdgeToEdge: 'auto'

context 自动检查 Android 15+ 和 windowOptOutEdgeToEdgeEnforcement 根据设备和配置智能调整边距。

最佳选择: 大多数生产应用程序，希望在支持的设备上实现边缘到边缘，同时保持与旧版 Android 版本的兼容性。

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

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

最佳选择: 希望在所有支持的 Android 版本上实现边缘到边缘行为的应用程序。

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

它做了什么: 完全禁用自动边距调整。

最佳选择: 手动处理边缘到边缘布局的应用程序或不希望实现边缘到边缘行为的应用程序。

注意： 目前 "disable" 将会变更为 "auto" 在 Capacitor 8 中

为 Android 15+ 的重要性

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

内容被系统栏遮挡
不合理的间距和填充
设备间不一致的外观
用户体验差

使用官方 adjustMarginsForEdgeToEdge 配置文件，您可以确保您的应用程序正确处理这些变化而无需自定义 code。

完整示例

Here’s a complete example configuration for a modern Capacitor app:

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

测试您的配置

配置后 adjustMarginsForEdgeToEdge, 在以下设备上测试您的应用:

Android 15+设备 - 检查内容是否正确尊严系统栏
旧版Android版本 - 确保向后兼容
不同屏幕尺寸 - 验证布局在不同设备上正常工作
轻暗主题 - 测试两种主题模式

常见错误

不要使用插件

您不需要第三方插件，如 capacitor-edge-to-edge 或类似的。native config可以清晰地处理此类问题。如果您需要对系统chrome的细粒度控制，启用 adjustMarginsForEdgeToEdge, @capgo/capacitor-导航栏和 @capgo/home-indicator @__CAPGO_KEEP_0__/首页指示器

补充native config而不替换它。

If you’re using adjustMarginsForEdgeToEdge移除任何手动窗口边距处理或 CSS hack

记住安全区域 CSS

迁移指南

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

移除任何边缘到边缘插件

从您的依赖项中 添加配置选项
到您的 清理并重建 capacitor.config.ts
您的 Android 项目 Don’t Forget Safe Area CSS
彻底测试 在目标设备上测试

# 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
以正确处理安全区域 检查您的布局
在边缘到边缘启用的设备上 Review your layouts on edge-to-edge enabled devices

結論

在Capacitor中，邊緣到邊緣顯示不需要插件、技巧或複雜的工作周轉。該配置選項提供了一個乾淨、原生解決方案，官方支持且未來可靠。 adjustMarginsForEdgeToEdge 開始

對於大多數應用程式，進行測試，跨多個設備，添加適當的安全區域CSS。您的應用程式將以最小的努力準備好Android 15和未來版本。 "auto" 有任何問題或遇到問題?

__CAPGO_KEEP_0__社區和 The Capacitor community and __CAPGO_KEEP_0__ are great resources for additional help.

继续在Capacitor中使用无插件的Edge-to-Edge显示

If you are using Edge-to-Edge Display in Capacitor Without Plugins Edge-to-Edge显示在__CAPGO_KEEP_0__中无需插件 Using @capgo/capacitor-live-activities 使用@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-视频播放器的实现细节使用 @capgo/capacitor-原生导航为使用 @capgo/capacitor-原生导航的原生能力

Capacitor无需插件的全屏显示

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

__CAPGO_KEEP_0__提供

如何配置它

配置选项

1. `"auto"` 它做了什么：

2. `"force"`

3. `"disable"`

为 Android 15+ 的重要性

完整示例

CSS注意事项

测试您的配置

常见错误

不要使用插件

补充native config而不替换它。

记住安全区域 CSS

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

未来化

更多資源

結論

继续在Capacitor中使用无插件的Edge-to-Edge显示

Capacitor无需插件的全屏显示

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

__CAPGO_KEEP_0__提供

如何配置它

配置选项

1. "auto" 它做了什么：

2. "force"

3. "disable"

为 Android 15+ 的重要性

完整示例

CSS注意事项

测试您的配置

常见错误

不要使用插件

补充native config而不替换它。

记住安全区域 CSS

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

未来化

更多資源

結論

继续在Capacitor中使用无插件的Edge-to-Edge显示

1. `"auto"` 它做了什么：

2. `"force"`

3. `"disable"`