DCloud_App_Array
DCloud_App_Array
  • 发布:2020-02-27 18:14
  • 更新:2022-11-01 16:45
  • 阅读:24636

适配暗黑模式/夜间模式/深色模式/暗黑主题(DarkMode)

分类:HTML5+

此文档仅描述5+ App项目如何适配暗黑模式,uni-app项目请参考:https://uniapp.dcloud.net.cn/tutorial/darkmode

iOS13开始引入了暗黑模式(DarkMode),Android10 引入暗黑模式,在暗黑模式下,系统界面配色都会相应变暗,同时App也需要进行适配。

HBuilderX2.6.3+支持iOS平台适配暗黑模式
HBuilderX3.6.9+支持Android平台适配暗黑模式

特别说明

iOS平台

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

注意:必须iOS13+设备上才支持

Android平台

注意:必须Android10+设备上才支持

开启适配暗黑模式(DarkMode)

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

  • iOS平台
    在 "plus" -> "distribute" -> "apple" 节点下添加 defaultTheme 节点

    "plus": {  
    "distribute": {  
      "apple": {  
       "UIUserInterfaceStyle": "Automatic",   //不推荐使用,设置light或dark后将无法跟随系统  
       "defaultTheme": "light" | "dark" | "auto"   //HBuilderX 3.6.10及以上版本支持  
        //...  
      },  
      //...  
    },  
    //...
  • Android平台
    在 "plus" -> "distribute" -> "google" 节点下添加 defaultNightMode 节点

    "plus": {  
    "distribute": {  
      "google": {  
        "defaultNightMode": "light" | "dark" | "auto"  
        //...  
      },  
      //...  
    },  
    //...

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

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

启动页

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

iOS安全区域适配

开启安全区域占位

在 manifest.json文件的"plus" 节点下添加 "safearea" 适配iOS的安全区域,"background" 对应正常模式下安全区域外的背景颜色,"backgroundDark"对应暗黑模式下安全区域外的背景颜色

"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页面可通过CSS适配

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

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

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

获取当前系统外观模式

对于页面中的原生标题栏(TitleNView),则需获取当前的外观模式,动态修改样式进行适配。

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)项目,可在在页面中监听"uistylechange"事件

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

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

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

如系统提示框(plus.nativeUI.alert)

  • 深色(暗黑模式)样式效果
  • 浅色(普通模式)样式效果

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

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

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

受影响的5+ API弹出系统原生界面

受影响的uni-app弹出系统原生界面

1 关注 分享
1***@qq.com

要回复文章请先登录注册

j***@empower.cn

j***@empower.cn

什么时候能够支持获取安卓手机是否开启了深色模式
2022-11-01 16:45
genda_0927

genda_0927

plus.nativeUI.setUIStyle("dark");
调用了这个,再 showModal ,显示的也不是深色模式的弹窗啊
2022-11-01 16:05
ebixpro

ebixpro

回复 9***@qq.com :
"ios" : {
"UIUserInterfaceStyle" : "Automatic",

},
2022-09-07 17:45
ebixpro

ebixpro

回复 9***@qq.com :
你的配置错了吧
"ios" : {
"UIUserInterfaceStyle" : "Automatic",

},
2022-09-07 17:45
1***@qq.com

1***@qq.com

配置好之后,离线打包会生效吗?
2022-07-19 09:13
睡到自然醒呀

睡到自然醒呀

设置了"UIUserInterfaceStyle": "Automatic", 云打包后ios还是不生效啊,更改显示模式也监听不到,plus.navigator.getUIStyle()一直是light
2022-04-26 17:45
1***@qq.com

1***@qq.com

同问,安卓怎么实现暗黑模式
2022-02-22 17:00
3***@qq.com

3***@qq.com

安卓的怎么实现黑暗模式?plus.navigator.getUIStyle(); Android - ALL (不支持) :返回"light"。
2022-02-22 15:12
不老刘

不老刘

感觉要改的页面有点多啊?另外安卓的咋实现黑暗模式?
2021-12-21 13:37
2***@qq.com

2***@qq.com

APP在暗色模式下,窗口的背景色需要修改,目前setBackgroundColor无法修改呀,请处理下呗
2021-08-24 19:25