纯静态三件套构建移动端升级指引页：CSS 变量主题与多机型适配

一、背景

在临床试验等场景中，参与人员使用的手机品牌、系统版本差异较大，App 升级与设备固件升级的操作路径各不相同。传统文字教程难以覆盖所有机型，容易出现操作遗漏。本文以一个实际项目「元方止鼾升级指南」为例，分享如何用纯静态 HTML/CSS/JS 构建一个支持多机型、可离线、自动适配亮暗主题的移动端指引页，全程无需任何后端框架与构建工具。

二、技术选型

项目的核心约束是「简单、离线可用、易部署」，因此技术栈刻意收敛到最基础的三件套：

单文件 index.html：零依赖、零构建，打开即用
CSS 自定义属性（Custom Properties）：实现完整主题系统
原生 JavaScript：处理主题切换与锚点导航
相对路径引用资源：保证本地与静态服务器部署行为一致

这套方案几乎没有学习成本，任何静态资源托管平台都能直接部署。

三、主题系统：三重机制

主题切换是这类页面的高频需求。项目中通过「CSS 变量 + prefers-color-scheme + data-theme 属性」三重机制实现，兼顾自动跟随与手动覆盖。

首先用 CSS 变量收敛全部颜色语义：

css
 
:root {
  --bg: #f4f7fb;
  --card: #ffffff;
  --text: #1f2933;
  --muted: #5f6b7a;
  --primary: #1890ff;
  --border: #e3e8ef;
}

再通过媒体查询实现系统级自动切暗色，同时用 :not([data-theme=“light”]) 避免覆盖用户手动选择：

css
 
@media (prefers-color-scheme: dark) {
  :root:not([data-theme=“light”]) {
    --bg: #0f1722;
    --card: #18222f;
    --text: #e6edf5;
    --primary: #4ba3ff;
  }
}

最后暴露少量 JS 供用户手动强制切换，本质只是改写根元素的 data-theme 属性：

js
 
function setTheme(t) {
  document.documentElement.dataset.theme = t;
}

所有组件的配色只引用变量，切换主题时无需改动任何组件样式，这份「关注点分离」是主题系统易维护的关键。

四、多机型适配与导航

不同品牌的升级流程差异较大，于是将每个机型的操作步骤拆分为独立卡片区块，通过锚点导航实现页面内快速跳转；所有操作截图均使用相对路径引用，确保本地预览与线上部署的加载行为完全一致。

五、部署与分发

由于是纯静态资源，部署方式非常灵活：既可直接双击 index.html 离线查看，也可通过任意静态服务器（http-server、python -m http.server）一键起服务，或上传至 OBS 等对象存储即可对外访问。

六、结语

对于中小型指引类页面，纯静态方案在易维护性、部署成本与加载性能上都有明显优势。当需求规模不大时，克制地选择最朴素的实现，往往比引入重型框架更经得起时间考验。

如果需要我调整主题（比如改成更偏向某一技术点、增加更多代码、或改为更短/更长的篇幅），告诉我即可。

21:50