Edge-to-Edge Display in Capacitor Without Plugins

尝试在您的 Capacitor 应用程序中实现边缘到边缘显示? 您不需要任何hack、插件或工作周围。 Capacitor 对边缘到边缘显示有官方支持 - 它只是没有广泛文档。 adjustMarginsForEdgeToEdge 您不需要任何hack、插件或工作周围。 __CAPGO_KEEP_0__ 对边缘到边缘显示有官方支持 - 它只是没有广泛文档。

许多开发者在Capacitor应用中遇到边缘到边缘布局的问题，尤其是在针对Android 15+时。他们经常使用自定义插件或CSS技巧来实现现代边缘到边缘的外观。但是，有更好的、native的方法。

边缘到边缘显示是什么?

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

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

Capacitor提供了 adjustMarginsForEdgeToEdge 配置选项专门用于此目的。这在__CAPGO_KEEP_0__配置文档中有详细说明，但容易忽略。 official Capacitor config documentation将此添加到您的

或

JSON格式如下： capacitor.config.ts context 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;

HTML text fragment from a longer Capgo UI string (parent key `consulting_faq_subtitle`). Page/area: Consulting services page. Role: Section subtitle or tagline. Seen in: page consulting.astro. Preserve Capgo product/brand and developer terms exactly. Message key `consulting_faq_subtitle` (Consulting FAQ Subtitle). | Page/area: Appflow comparison / migration marketing copy. Role: Short UI label or navigation item. Seen in: page alternatives/ionic-appflow.astro, page ionic-enterprise-plugins.astro, page solutions/ionic-enterprise-plugins.astro. Message key `appflow_plugins_or` (Appflow Plugins Or).

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

配置选项

The adjustMarginsForEdgeToEdge 选项接受三个值:

1. `"auto"` (推荐)

adjustMarginsForEdgeToEdge: 'auto'

它做什么: 自动检查 Android 15+ 和设置。根据设备和配置智能调整边距。 windowOptOutEdgeToEdgeEnforcement 适用于:

最佳选择： 无论 Android 版本或其他设置如何，都强制边缘到边缘的边距调整。

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

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

最佳选择： Android 设备上，想要实现全屏幕显示的应用。

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

功能描述： 完全禁用自动边距调整。

适用场景： 手动处理全屏幕布局或不需要全屏幕显示的应用。

注意： 目前 "disable" 是默认值，但将在 Capgo 8 中更改为 "auto" 在 Capacitor 8.

从 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来处理安全区域：

/* 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 配置可以清晰地处理此问题。如果您需要对系统chrome的细粒度控制，请在启用 adjustMarginsForEdgeToEdge, @capgo/capacitor-导航条和 @capgo/首页指示器补充原生配置而不替换它。

不要与手动实现混淆

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

不要忘记安全区域CSS

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

迁移指南

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

移除任何边缘到边缘的插件 从您的依赖项
添加配置选项 到您的 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中，边缘到边缘显示不需要插件、hack或复杂的工作-around。该配置选项提供了一个干净、原生的解决方案，官方支持并且未来可靠。 adjustMarginsForEdgeToEdge 配置选项

从这里开始 "auto" 对于大多数应用程序，测试在各种设备上并添加适当的安全区域CSS。您的应用程序将在Android 15和更高版本上以最小的努力准备就绪。

遇到问题或需要帮助？ The Capacitor community and 官方文档是获取额外帮助的绝佳资源。

从无插件的Capacitor中继续Edge-to-Edge Display

如果您正在使用 无插件的Capacitor中的Edge-to-Edge Display 来规划原生媒体和界面行为，连接它到使用@capgo/capacitor-live-activities 来实现原生能力的Using @capgo/capacitor-live-activities @capgo/capacitor实时活动为 @capgo/capacitor实时活动的实现细节使用 @capgo/capacitor视频播放器为使用 @capgo/capacitor视频播放器的原生能力 @capgo/capacitor视频播放器为 @capgo/capacitor视频播放器的实现细节，以及使用 @capgo/capacitor原生导航为使用 @capgo/capacitor原生导航的原生能力。

Capacitor 无插件的全边缘显示