Edge-to-Edge Display in Capacitor Without Plugins

您正在尝试在Capacitor应用中实现全边缘显示吗? Capacitor支持全边缘显示，通过官方的 adjustMarginsForEdgeToEdge targetLanguage":"Simplified Chinese","protectedTokens":["Cloudflare","Capacitor","GitHub","Capgo","code","API","SDK","CLI","npm","bun"],"texts":["配置选项 - 它并不是很广泛地文档化。",

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

什么是边缘到边缘显示？

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

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

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

或

Add this to your 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 版本的兼容性。 它做什么：

2. `"force"`

adjustMarginsForEdgeToEdge: 'force'

无论 Android 版本或其他设置如何，都强制边缘调整。 该选项接受三个值：

适合: 需要在所有支持的 Android 版本上实现全屏行为的应用。

3. `"disable"`

adjustMarginsForEdgeToEdge: 'disable'

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

适合: 手动处理全屏布局或不需要全屏行为的应用。

注意: 目前是默认值，但将在 Capgo 8 中更改为 "disable" 为什么 Android 15+ 中的这一点很重要 "auto" in Capacitor 8.

当前

在 Capgo 8 中将更改为

系统栏后面的内容
不协调的间距和填充
设备间不一致的外观
糟糕的用户体验

通过使用官方 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 或类似。原生配置处理得很干净。如果您需要在启用后对系统浏览器进行细粒度控制 adjustMarginsForEdgeToEdge, @capgo/capacitor-navigation-bar 和 @capgo/home-indicator 补充原生配置而不替换它。

不要与手动实现混用

如果您正在使用 adjustMarginsForEdgeToEdge，请移除任何手动窗口内边距处理或CSS黑客您可能添加的内容。

不要忘记安全区域CSS

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

迁移指南

如果您当前正在使用插件或hack来实现边缘到边缘：

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

# 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 正确处理安全区域
检查布局 在边缘到边缘启用的设备上

额外资源

结论

Edge-to-edge display in Capacitor doesn’t require plugins, hacks, or complicated workarounds. The adjustMarginsForEdgeToEdge 配置选项提供了一个干净、原生的解决方案，得到官方支持并且是未来可行的。

从 "auto" 对于大多数应用，测试在各个设备上，添加适当的安全区域CSS。您的应用将在最小努力下准备好Android 15和以后。

有问题或遇到问题? The Capacitor community and 官方文档是获取额外帮助的好资源。

从边缘到边缘的显示屏在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-video-player的实现细节中，使用@capgo/capacitor-native-navigation 为使用@capgo/capacitor-native-navigation的原生能力

Capacitor在不使用插件的情况下实现全边缘显示