iOS13适配暗黑模式/夜间模式/深色模式/暗黑主题（DarkMode）

本文为转载：原创请点击https://ask.dcloud.net.cn/article/12861

分类：HTML5+

DarkMode 深色外观 暗黑模式 iOS13 iOS

iOS13开始苹果引入了暗黑模式（DarkMode），在暗黑模式下，系统界面配色都会相应变暗，同时App也需要进行适配。
HBuilderX2.6.3+版本开始支持对暗黑模式的适配处理。

苹果近日对App Store商店的审核指南做了一次更新并发了一份公告，要求所有的APP 在4月30号前使用iOS 13 SDK开发应用，很多开发者错误理解成使用iOS 13 SDK开发应用就必须适配暗黑模式，实际上苹果的官方开发者文档从未强制要求应用必须适配深色样式（暗黑模式），完整解读参考：iOS苹果3月4号新发公告解读 - DCloud问答。
重点：不适配暗黑模式，一样可以正常上Appstore。但是适配了暗黑模式，没适配利索，页面有黑有白，就可能会被拒绝上架。

开启适配暗黑模式（DarkMode）

为了保证应用的兼容性，HBuilderX打包生成的App默认已关闭兼容暗黑模式，需按以下方法配置开启适配暗黑模式。
开启适配暗黑模式后，弹出系统授权框将按当前系统设置的外观样式显示（可在 "设置" -> "显示与亮度" -> "外观" 中更改），应用中的页面则需要开发者根据下面的API获取当前系统外观模式进行适配处理。
注意：如果未开启适配黑暗模式，将无法获取当前系统的外观样式
打开项目的manifest.json文件，切换到“源码视图”项

• uni-app项目
  在 "app-plus" -> "distribute" -> "ios" 节点下添加 UIUserInterfaceStyle 节点

  复制代码"app-plus": {  
  "distribute": {  
    "ios": {  
     "UIUserInterfaceStyle": "Automatic",  
      //...  
    },  
    //...  
  },  
  //...

• 5+ App（WAP2APP）项目
  在 "plus" -> "distribute" -> "apple" 节点下添加 UIUserInterfaceStyle 节点

  复制代码"plus": {  
  "distribute": {  
    "apple": {  
     "UIUserInterfaceStyle": "Automatic",  
      //...  
    },  
    //...  
  },  
  //...

保存后，提交云端打包后生效

暗黑模式适配主要包括三部分，一部分是应用中的页面，另一部分是特定功能弹出系统原生界面（如alert提示框）和安全区域外背景颜色，下面会详细说明分别如何适配。

安全区域适配

一、开启安全区域占位

在 "app-plus" 节点下添加 "safearea" 适配iOS的安全区域，"background" 对应正常模式下安全区域外的背景颜色，"backgroundDark"对应暗黑模式下安全区域外的背景颜色

复制代码"app-plus" : {  
    "safearea": { //iOS平台的安全区域  
        "background": "#ffffff",  
        "backgroundDark": "#2f0508", // HX 3.1.19+支持  
        "bottom": {  
            "offset": "auto"  
        }  
    }  
...  
}

二、关闭安全区域站位

将 "offset" 置为 “none” 关闭安全区域的站位，注：关闭安全区域占位在刘海屏页面内容可能会被 “homeBar” 挡住，需要自行适配，具体请参考文档 iOS刘海屏适配

复制代码"safearea": {    
    "bottom": {    
        "offset": "none"    
    }    
}

更多关于 "safearea" 的说明请参考 manifest.json 说明

应用中页面如何适配暗黑模式

在应用中需要获取当前系统设置的外观模式格是否为暗黑模式，如果是则需要调整应用整体UI风格样式进行适配。

html/vue页面可通过CSS适配

推荐使用CSS中的媒体查询 prefers-color-scheme 进行适配

复制代码@media (prefers-color-scheme: dark){  
    .content {  
        background-color: #1B1C1E;  
        color: white;  
    }  
}

注意：如果未开启适配黑暗模式，以上媒体查询样式将不会生效

获取当前系统外观模式

对于页面中的原生标题栏（TitleNView）以及uni-app中的nvue页面，则需获取当前的外观模式，动态修改样式进行适配。

HBuilderX2.6.3+开始新增5+ API：plus.navigator.getUIStyle获取当前系统外观模式。
返回"dark"表示当前为深色样式（DarkMode），即暗黑模式；"light"表示当前为浅色样式（LightMode），即普通模式。

复制代码function getUIStyle(){  
  var style = plus.navigator.getUIStyle();  
  if('dark'==style){  
    console.log('当前为暗黑模式');  
  }else{  
    console.log('当前为普通模式');  
  }  
}

5+ App（WAP2APP）、uni-app项目都可以调用以上API获取当前系统外观模式

监听系统外观模式改变

应用启动后，用户有可能改变系统外观，这时候可以通过监听切换暗黑模式事件进行处理

• 5+ App（WAP2APP）项目
  在页面中监听"uistylechange"事件

  复制代码document.addEventListener('uistylechange', function(){  
  var style = plus.navigator.getUIStyle();  
  console.log(('dark'==plus.navigator.getUIStyle())?'切换为暗黑模式':'切换为普通模式');  
  }, false);

• uni-app项目

  复制代码uni.onThemeChange(function (res) {  
      console.log(res.style);  
  });

  详情 uni.onThemeChange(CALLBACK) | uni-app官网

启动页

官方提供的默认启动页已适配 '暗黑模式'，会自动跟随系统模式改变背景颜色；自定义启动页请参考文档 自定义启动页

系统原生界面如何适配暗黑模式

应用开启适配暗黑模式后，系统原生界面（plus.nativeUI）默认会自动适配系统设置的外观样式。
如果系统当前设置为深色外观（暗黑模式），则plus.nativeUI弹出的所有界面自动显示为深色（暗黑模式）样式；如果系统当前设置为浅色外观，则plus.nativeUI弹出的所有界面显示为浅色样式。

如系统提示框（plus.nativeUI.alert)）

• 深色（暗黑模式）样式效果

  正在上传…重新上传取消

• 浅色（普通模式）样式效果

  正在上传…重新上传取消

如果不想自动适配系统设置的外观样式，可以调用plus.nativeUI.setUIStyle强制设置原生界面的外观样式。
以下示例强制应用弹出原生界面为深色（暗黑模式）外观样式，即使系统没有设置为深色外观（暗黑模式）：

复制代码plus.nativeUI.setUIStyle('dark');  // ‘light’表示浅色外观样式

即使应用没有开启适配暗黑模式，此API也可生效