HarmonyOS应用深色模式适配方案

概述

深色模式（Dark Mode）又称为暗色模式，是与日常使用过程中的浅色模式（Light Mode）相对应的一种UI主题。深色模式最早来源于人机交互领域的研究和实践，该模式并非简单地将页面背景变为黑色、文字内容变为白色，而是提供一整套适配该模式的应用配色主题。相较于浅色模式，深色模式视觉效果更加柔和，能有效降低屏幕亮度对眼睛造成的刺激和疲劳。此外，深色模式还能通过降低像素亮度减少设备能耗，从而提升续航表现。

在应用深色模式适配时，需遵循UX基础设计原则，保障页面内容的易读性、舒适性与视觉一致性，具体可参照专业深色模式设计规范。适配过程主要涉及三方面：字体颜色、元素背景色等颜色资源调整；图片图标等媒体素材的明暗对比优化；系统状态栏的适配处理。此外，还需针对使用Web组件加载的网页等特殊场景进行专项适配。

本文主要将介绍深色模式的适配过程，同时会列举出适配过程中的常见问题及解决方案。

实现原理

当系统切换到深色模式后，应用内可能会出现部分内容切换到深色主题的情况，例如状态栏、弹窗背景色、系统控件等，会导致应用内页面效果错乱。

为应对上述情况，需要对应用进行深色模式下的内容适配，目前该适配主要依靠资源目录。当系统对应的设置项发生变化后（如系统语言、深浅色模式等），应用会自动加载对应资源目录下的资源文件。

系统为深色模式预留了dark目录，该目录在应用创建时默认不存在，在进行深色模式适配时，需要开发者在src/main/resources中手动地创建出dark目录，将深色模式所需的资源放置到该目录下。对于浅色模式所需的资源，可以放入默认存在的src/main/resources/base目录下。

在进行资源定义时，需要在base目录与dark目录中定义同名的资源。例如在base/element/color.json文件中定义text_color为黑色，在dark/element/color.json文件中定义text_color为白色，那么当深浅色切换时，应用内使用了$('app.color.text_color ')作为颜色值的元素会自动切换到对应的颜色，而无需使用其他逻辑判断进行控制。

一般情况下深浅色模式切换不会导致应用界面产生结构上的变化，而是页面结构一致但是采用不同的主题配色、配图等，使得整个应用在切换到深色模式后依然保持自然美观，以下为深色模式适配的UX示例。

从上图中可以看到，在应用进行深色模式适配过程中主要的适配项有颜色资源适配、媒体资源适配、状态栏适配，除此之外若应用内使用了Web组件加载了Web内容，那么还需对Web页面适配深色模式，具体适配方案可点击对应链接跳转到具体章节查看。

目前业内应用向用户提供的深浅色模式切换有以下两种常见方式。

应用跟随系统深浅色模式切换

实现上，需要开发者使用setColorMode()方法将ColorMode设置为COLOR_MODE_NOT_SET（未设置颜色模式），然后应用在运行过程中就可以自动感知到系统颜色模式切换，若应用完成了深浅色模式适配，将自动切换到对应的颜色模式。

应用内提供手动控制深浅色的开关供用户自行选择

实现上，切换深色模式需要调用setColorMode()方法将ColorMode设置为COLOR_MODE_DARK（深色模式），切换浅色模式需要将ColorMode设置为COLOR_MODE_LIGHT（浅色模式），这样就可以完成对应用深浅色的手动控制。

综上分析，深色模式适配内容如下表所示。

深色模式适配

颜色资源适配

颜色资源适配是将页面元素的颜色抽离到限定词目录中，让应用在不同的深浅色模式下使用不同限定词目录中的颜色值，从而达成应用页面元素在深浅色下不同的颜色表现。若应用适配代码存在错误，那么在切换到深色模式后，页面元素会由于对比度过低导致用户识别困难，以下为颜色资源适配错误的效果示例。

上述页面效果在浅色模式下显示正常，但是当切换到深色模式后 ，弹窗内文字与弹窗背景色不满足背景色对比度不低于5:1，用户识别弹窗内容困难。上述效果的关键问题在于使用自定义弹窗时，若未手动指定弹窗背景色，系统默认对弹窗背景色做了深浅色适配，但是弹窗内的具体内容特别是开发者的自定义内容无法自动适配深色模式，于是当系统切换到深色模式下，弹窗背景色自动深色，而弹窗内容保持与浅色模式一致的颜色，导致内容无法看清，该类问题对应解决方案有以下两种。

方式一：使用系统资源（优先建议）。使用受支持的系统资源会自动适配深色模式，开发者可查看系统资源获取受支持的系统资源。

方式二：使用自定义主题，若开发者需要定制在深浅色模式下不同的颜色表现，就需要使用自定义主题。

媒体资源适配

媒体资源适配即在深浅模式下采用不同颜色表现的图片或图标等媒体资源，从而达成更好的用户体验，以下为应用内的图标未适配深色模式的效果示例，未适配内容以黄虚线框出。

上述错误示例效果的关键问题在于对于应用内的图标并未做深色模式下的适配，于是图标的颜色与应用浅色时一致，而两者对比度过低，导致切换到深色模式后应用内图标无法看清，媒体资源的适配有以下两种方式。

方式一：若适配简单图标并且图标格式为SVG类型，那么只需要结合颜色资源适配并使用Image组件的fillColor属性（若使用Symbol则使用SymbolGlyph的fontColor属性），在不同的深浅色下设置为不同的填充色即可完成深色模式的适配。

方式二：若需要适配图片或适配图标但图标不为SVG类型，那么就需要使用资源目录的方式进行深色模式的适配。

状态栏适配

状态栏适配即在深浅色模式下，采用不同的状态栏背景色与字体颜色。若应用未启用沉浸式，那么默认情况下，浅色模式下状态栏为白底黑字，深色模式下状态栏为黑底白字。当应用启用了沉浸式，状态栏背景色与应用背景色保持一致，而状态栏文字会默认在浅色模式下保持黑色，而在深色模式下保持白色，若应用在浅色模式下设置了深色背景或在深色模式下设置了浅色背景，都会导致状态栏背景色与状态栏字体颜色对比度过低，导致显示异常。错误效果示例如下图，应用设置了沉浸式并在浅色模式下具有纯黑色的背景色，导致状态栏的日期电量等文本内容无法看清。

上述错误效果的主要问题在于页面的背景色固定为黑色，当系统切换到浅色模式后，状态栏文字默认切换到黑色，此时状态栏背景色与文字颜色一致，于是状态栏中的文字就不可见了，此类问题修改方案有以下两种。

若可以将背景色做深浅色适配，则采用颜色资源适配的方案对应用背景色进行适配，背景色适配时需考虑到状态栏文字在深浅色模式下的默认表现。

若背景色无法做深浅色适配，或做了深浅色适配，但是沉浸式颜色与默认的状态栏文字颜色对比度较低，这种情况下需要获取当前的深浅色并动态设置状态栏字体颜色。

Web页面适配深色模式

Web页面的内容不会自动跟随系统颜色模式进行切换。

若需要Web内容进行深浅色适配，就需要在Web页面内通过媒体查询的方式单独设置深色模式下的页面样式，并通过Web组件的darkMode()属性来控制Web页面是否启用深色模式。

具体实现开发者可参考：Web组件设置深色模式。

总结

本文系统解析了深色模式适配的技术原理，并详细阐述了适配实施过程中的关键调整项，通过差异化的适配策略对界面元素进行针对性处理，即可实现完整的深浅色主题切换。