原生移动开发 / 知识点

Android 项目目录与文件用途速查

界面与资源文件

为夜间模式提供 values 资源覆盖,系统进入 Dark Mode 后可自动选择;主题或颜色只在深色模式异常时应检查这里。

values-night 目录

res/values-night/ 是带 night 配置限定符的 values 资源目录。设备或应用处于夜间模式时,Android 资源系统会优先从这里选择匹配资源;没有对应覆盖项时,仍会回退到普通 res/values/,因此不需要复制全部资源。

怎么判读

线索 含义 建议动作
values/ 与 values-night/ 存在同名资源 日间和夜间使用不同值 对照两处资源值是否符合设计要求
只有 values/ 中定义资源 夜间没有专门覆盖 确认默认值在深色背景下是否仍可用
只在深色模式出现颜色或主题异常 夜间资源可能覆盖错误 优先检查 values-night/ 中的同名项
修改普通 values/ 后深色模式仍不变 更具体的 night 资源正在生效 搜索 values-night/ 中是否存在同名资源

Android 按资源类型和名称进行匹配,而不是按文件名覆盖整个文件。例如 values/colors.xml 和 values-night/colors.xml 可以只共享其中几个颜色名称。

主示例

普通模式先提供默认颜色:

xml
<!-- res/values/colors.xml -->
<resources>
    <color name="screen_background">#FFFFFF</color>
    <color name="primary_text">#202124</color>
</resources>

夜间目录只覆盖需要变化的值:

xml
<!-- res/values-night/colors.xml -->
<resources>
    <color name="screen_background">#121212</color>
    <color name="primary_text">#F1F3F4</color>
</resources>

布局或主题继续引用相同资源名,例如 @color/screen_background。进入夜间模式后无需修改调用代码,资源系统会选择 values-night 中更匹配的值。

预期结果:普通模式使用浅色背景和深色文字;夜间模式使用深色背景和浅色文字。实际显示还会受到主题、动态颜色以及组件自身样式影响。

出现条件与范围

night 属于 Android 的 uiMode 配置限定符。系统深色模式通常会改变该配置;使用 AppCompat 等方案时,应用也可以主动设置自身的夜间模式,因此不能只根据系统设置推断最终资源选择结果。

目录中可以放置颜色、样式、尺寸等 values 类型 XML,但只有需要随夜间模式变化的资源才应覆盖。不要为了保持两个目录结构一致而复制所有默认值,否则容易造成后续修改只更新一处。

排查顺序

深色模式异常时,先确认问题资源的实际名称,再搜索 values-night/ 是否存在同名定义;随后检查主题属性是否间接引用了另一项资源。若删除夜间覆盖后表现恢复正常,通常说明问题来自更具体的 night 资源,而不是基础 values/。

测试与构建产物

仓库整理与安全检查

目录与阅读设置

记录一个想法

Android 项目目录与文件用途速查

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通