DCloud_App_Array
DCloud_App_Array
  • 发布:2020-02-27 18:14
  • 更新:2024-02-28 22:49
  • 阅读:41370

适配暗黑模式/夜间模式/深色模式/暗黑主题(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弹出系统原生界面

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

要回复文章请先登录注册

2***@qq.com

2***@qq.com

hello
2024-02-28 22:49
1***@163.com

1***@163.com

使用plus.nativeUI.setUiStyle设置为dark的时候为什么app会闪退? 浅色模式就没问题,求解!
2024-02-19 15:35
搬砖大老

搬砖大老

回复 搬砖大老 :
ios下正常
2023-12-25 11:15
搬砖大老

搬砖大老

安卓, 暗黑模式, showtoast 是黑色背景,容易和黑色背景的页面 混淆看不清。是没适配呢?还是我哪里没有配置对?
2023-12-25 11:14
5***@qq.com

5***@qq.com

uni小程序(APP-PLUS),需要的时小程序一直保持light模式,但是有的安卓机型不能生效,比如vivo
2023-12-06 14:44
charlence002

charlence002

回复 charlence002 :
我这边的需要是,强制"light"模式;并没有生效
2023-05-08 18:02
charlence002

charlence002

文档说明重点标注 plus.nativeUI.setUIStyle('light') “即使应用没有开启适配暗黑模式,此API也可生效”;
事件情况是:plus.nativeUI.setUIStyle('light') iOS 离线打包不生效,模拟器不生效;
2023-05-08 18:01
Star777

Star777

回复 1***@qq.com :
我先云端打包了一次,之后的离线打包没有生效
2023-01-24 22:35
DCloud_UNI_GSQ

DCloud_UNI_GSQ

回复 j***@qq.com :
这个是 5+的不是 uni-app 哦
2023-01-03 11:54
j***@qq.com

j***@qq.com

你们文档真的是乱写啊,暗黑模式安全区域的safearea明明是要放在app-plus里面才生效,你们文档却说放在plus里面。
https://uniapp.dcloud.net.cn/tutorial/darkmode.html#ios-%E5%AE%89%E5%85%A8%E5%8C%BA%E5%9F%9F%E9%80%82%E9%85%8D
2022-12-28 10:00