iOS端Flutter Web构建的PWA设置black-translucent状态栏不生效

原因说明 #

apple-mobile-web-app-status-bar-style 配置为 black-translucent 时，本身不会主动读取 theme-color 的值：该属性的效果是让状态栏呈现半透黑色背景、白色文字，同时页面视口会延伸到状态栏下方，最终状态栏呈现的颜色是页面顶部背景色叠加半透黑的效果。

修复步骤 #

• 第一步：补充HTML全局样式配置
  在你的index.html的<head>标签内新增如下样式块，确保页面初始背景色和你的主题色一致：

<style>
  html, body {
    background-color: #8C3144;
    margin: 0;
    padding: 0;
    height: 100%;
    width: 100%;
    overflow: hidden;
  }
</style>

• 第二步：校验manifest.json配置
  确保你的manifest.json文件中同时配置了以下两个字段，值统一设置为你的主题色：

{
  "theme_color": "#8C3144",
  "background_color": "#8C3144"
}

• 第三步：（可选）实色状态栏适配
  如果你不需要状态栏半透效果，想要完全实色匹配主题色，可以将原配置：

<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">

修改为：

<meta name="apple-mobile-web-app-status-bar-style" content="default">

修改后状态栏会直接读取theme-color的值作为背景色，文字颜色会根据主题色深浅自动适配。

生效注意事项 #

iOS对PWA的配置有强缓存逻辑，修改完所有配置后必须执行以下操作才能生效：

1. 清空Safari浏览器缓存
2. 删除之前已经添加到主屏幕的PWA图标
3. 重新在Safari打开页面，再次添加到主屏幕进行测试

内容的提问来源于stack exchange，提问作者Kalias 29