前阵子运营同事突然找我，说第二天上午全站要切黑白模式，而且要求能一键恢复、一键再切过去，最好运营自己也能操作。我当时第一反应就是给html加一行filter: grayscale(1)，但真正落地的时候才发现，原生 HTML 做黑白模式这件事，表面是 CSS 一行，背后全是细节：fixed 定位乱了、Logo 要去彩色、图片没变灰、动画卡顿……这篇就把我从头到尾的完整方案和踩坑过程写清楚，纯原生 HTML/CSS/JS 实现，不引第三方库，适合所有前端同学参考。
1. 整站黑白不是改个颜色，而是一套状态方案
1.1 哪些场景需要全站黑白
先说需求。网站黑白模式最常见的触发场景是特殊纪念日、重要仪式感时刻、产品下架停服、活动页面归档、极简阅读模式等。这类需求有几个共同特点：时间敏感、范围全站、必须可逆。
时间敏感意味着可能今天告知、明天生效，留给你准备的时间很短；范围全站意味着不是某个按钮、某张图变色，而是所有页面、所有组件、所有弹窗全部统一变灰；必须可逆意味着活动结束或指定时间过后，要能一秒恢复正常，不能改完代码再重新发布。
很多刚入行的同学容易把这件事理解成“全局加个样式”，实际上运营要的是一套能随时开关的机制。你不可能每次需求来了都改代码发版，更好的做法是做成一个内置于页面中的“开关”——平时关闭、特殊时刻一键开启。这也是标题里“一键”两个字的真实含义。
1.2 为什么坚持用原生 HTML/CSS/JS
市面上其实有不少第三方插件和库能实现网站置灰，比如有的站点直接引入一个 widget 脚本，会自动给页面挂灰度滤镜。但我的建议始终是：能原生解决的场景，尽量别引第三方。
原因有三条。
第一，可控性。原生方案完全掌握在自己手里，滤镜加在哪一层、排除哪些元素、什么时候启用、什么时候关掉，全部由你的代码决定，不会出现第三方脚本在某个页面报错导致整站变灰失败的尴尬。
第二，性能与安全。第三方脚本本质上是在你的页面上执行一段外部代码，你无法完全确认它做了什么，而且它通常还会额外请求资源。特殊时期全站访问量大，每多一个请求就多一分风险。原生方案零请求、零依赖，一个 class 就能搞定，干净利落。
第三，兼容性可自行兜底。第三方方案如果遇到老浏览器不兼容，你很被动；原生方案你可以自己写 SVG 滤镜兜底，心里有数。
1.3 “一键”的三个层次
把需求拆开看，“一键”其实可以理解成三个层次：
- 手动一键：页面上放个按钮，访客或运营点击，整站切换黑白；
- 自动一键：到了约定日期自动变灰，过了日期自动恢复，不需要人工干预；
- 强制一键：运营通过链接参数强制指定某个页面变灰，方便紧急情况下快速生效。
三个层次并不互斥，好的方案应该同时支持。后面我会给出一个三通道结合的完整实现，先把核心原理讲清楚，再一步步落地。
2. grayscale 滤镜的底层逻辑与最简实现
2.1 一张彩色图片是怎么变成黑白的
要理解整站变灰，首先得知道 CSS 的filter: grayscale()到底做了什么。其实它内部可以理解为一个颜色矩阵的变换：把像素的 RGB 三个通道按照一定权重计算出一个灰度值，然后把这个灰度值同时赋给 R、G、B 三个通道，最终得到一个“没有饱和度”的像素。
常见的灰度算法有三种：最大值法、平均值法、加权平均法。CSS 用的是基于 sRGB 亮度感知的加权算法，简单说就是绿色对亮度的贡献最大，蓝色最小，这样处理出来的黑白更接近人眼对画面明暗的真实感受。
这里要区分另一个容易混淆的属性：filter: saturate(0)。grayscale(1)和saturate(0)效果看起来非常像，都是去色变灰，但底层逻辑略有不同：grayscale 是按灰度算法重新映射颜色，saturate(0) 是直接把饱和度降为零。实际显示效果上两者差别很小，但 grayscale（灰度）在语义上更准确，而且兼容性更好，所以我推荐使用grayscale。
还有一点需要留意：filter: grayscale(1)的括号里可以是0到1或者0%到100%。我习惯用1表示全灰度，因为grayscale(0.5)代表半灰度，日常切换更多是二值的，直接给1最干脆。
2.2 从“一行 CSS”到“一个 class”
最直白的写法是在样式表里加上这段：
html { filter: grayscale(1); -webkit-filter: grayscale(1); }这段代码在绝大多数现代浏览器里都能让整个页面变灰，也是网上流传最广的“一行实现”方案。但我不建议直接把样式写死在html上，因为你要考虑一键切换和恢复。更好的做法是定义一个状态 class：
html.gray-mode { filter: grayscale(1); -webkit-filter: grayscale(1); }这样切换逻辑就从“改样式”变成了“增删一个 class”，语义非常清楚。后期不管是交给按钮交互、定时器，还是 URL 参数，统一都是操作这个 class，维护起来省心很多。
2.3 老浏览器兼容：SVG 滤镜兜底方案
如果项目还需要照顾比较老的浏览器（比如某些政府类、传统的企业内部系统，还在用很久以前的浏览器版本），filter属性可能不认。这种情况可以准备一份 SVG 滤镜兜底。
思路是：定义一个 SVG 灰度滤镜，在 CSS 里通过filter: url(#grayscale)引用它。具体做法是在页面中放一个隐藏的 SVG 标签：
<svg style="position:absolute; width:0; height:0; overflow:hidden;"> <filter id="grayscale"> <feColorMatrix type="saturate" values="0" /> </filter> </svg>然后在 CSS 里这样写：
html.gray-mode { filter: url(#grayscale); -webkit-filter: grayscale(1); }feColorMatrix的saturate类型配合values="0"，效果就是彻底去饱和，和grayscale(1)基本等效。兜底方案不需要锦上添花，只要老浏览器里页面能正常变灰、内容可读即可。
2.4 给变灰加一点过渡
如果直接加 class，页面会“啪”地一下瞬间变灰，视觉上有点突兀。可以在 CSS 里补一个过渡：
html { transition: filter 0.3s ease; }filter是一个可过渡属性，切换时会有一个柔和的变化过程。不过要注意，全站级别的 filter 过渡在低端设备上可能造成掉帧，因为浏览器需要重新计算整页的颜色矩阵。如果项目里动画元素很多，建议过渡时间控制在 0.3s 以内，或者干脆不加过渡，直接硬切，反而更稳。
3. 一键切换的完整交互实现：按钮、持久化、自动触发
3.1 核心脚本：一个按钮切换全站黑白
我们先实现最基础的一键切换交互。HTML 结构如下：
<!doctype html> <html lang="zh-cn"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>原生html一键实现网站黑白模式</title> <style> html { transition: filter 0.3s ease; } html.gray-mode { filter: grayscale(1); -webkit-filter: grayscale(1); } .gray-toggle { position: fixed; right: 20px; bottom: 20px; padding: 10px 18px; border: 1px solid #ccc; background: #fff; cursor: pointer; z-index: 9999; } </style> </head> <body> <button class="gray-toggle" id="grayToggle" type="button">开启黑白模式</button> <script> var toggleBtn = document.getElementById('grayToggle'); var rootEl = document.documentElement; toggleBtn.addEventListener('click', function () { rootEl.classList.toggle('gray-mode'); var isGray = rootEl.classList.contains('gray-mode'); toggleBtn.textContent = isGray ? '关闭黑白模式' : '开启黑白模式'; }); </script> </body> </html>这个版本已经可以用了，点击按钮后整站变灰，再点恢复。按钮固定在右下角，方便演示和手动测试，实际生产环境可以把这个按钮隐藏，只保留切换逻辑。
这里有个容易忽略的点：不要直接给document.body.style.filter赋值。body的滤镜只作用于 body 自身渲染的内容，某些浏览器下html本身的背景色和滚动条区域不会被覆盖，页面可能出现“顶部白条”或“滚动条不变灰”的情况。挂在document.documentElement（也就是html根元素）上，覆盖范围才是真正的整站。
3.2 记住用户选择：localStorage 持久化
手动切换做了，但刷新页面之后状态就丢了，体验不够完整。运营希望这次切了，用户下次访问还是灰的，这就需要把状态持久化。最轻量的方式是localStorage：
var rootEl = document.documentElement; var KEY = 'gray-mode-enabled'; function applyGray(enable) { rootEl.classList.toggle('gray-mode', enable); var btn = document.getElementById('grayToggle'); if (btn) { btn.textContent = enable ? '关闭黑白模式' : '开启黑白模式'; } } (function init() { var saved = localStorage.getItem(KEY); if (saved === '1') { applyGray(true); } })();点击事件里加上写入逻辑：
toggleBtn.addEventListener('click', function () { var isGray = !rootEl.classList.contains('gray-mode'); applyGray(isGray); localStorage.setItem(KEY, isGray ? '1' : '0'); });这段逻辑注意几点：首次进入页面时从localStorage读状态并立即应用；选择权交给访客，访客关掉黑白之后，下次打开保持关闭状态；运营强制开启的场景见下面。
3.3 自动开启：日期判断与 URL 参数控制
除了用户手动切换，还要支持运营侧强制。我常用的方案是“URL 参数 + 日期判断”双通道。
URL 参数适合紧急控制：运营在活动页链接后面加?gray=1，页面加载后立即变灰。代码可以这样写：
function getQueryParam(name) { var match = new RegExp('[?&]' + name + '=([^&]*)').exec(window.location.search); return match ? decodeURIComponent(match[1]) : null; } (function init() { var forced = getQueryParam('gray'); if (forced === '1') { applyGray(true); return; } var saved = localStorage.getItem(KEY); if (saved === '1') { applyGray(true); } })();日期判断适合定时任务：比如页面上配置了某个日期范围，到了时间自动变灰。这个逻辑可以放在页面加载时：
function isInGrayPeriod() { var now = new Date(); var start = new Date('2025-10-01T00:00:00'); var end = new Date('2025-10-03T23:59:59'); return now >= start && now <= end; } (function init() { if (isInGrayPeriod()) { applyGray(true); return; } var forced = getQueryParam('gray'); if (forced === '1') { applyGray(true); return; } var saved = localStorage.getItem(KEY); if (saved === '1') { applyGray(true); } })();优先级我定成：日期范围 > URL 参数 > 用户选择。日期范围是最高优先级，因为纪念日场景必须无条件生效；URL 参数排第二，方便运营临时强切；用户选择排最末，日常使用时把选择权给访客。
3.4 防闪烁：脚本要放在 head 里提前执行
把初始化脚本放在</body>前有个问题：页面先渲染出彩色内容，JavaScript 再执行变灰，用户会看到一瞬的彩色，体感上很怪。尤其是在强切场景下，这种闪变不能接受。
解决办法是在<head>里用小段内联脚本提前执行。因为head里的脚本在 body 渲染之前就会执行，可以先给html加好 class，浏览器后续绘制时就直接按灰度渲染，全程无闪变：
<head> <style> html.gray-mode { filter: grayscale(1); -webkit-filter: grayscale(1); } </style> <script> (function () { var forced = /[?&]gray=1/.test(location.search); if (forced) { document.documentElement.classList.add('gray-mode'); } })(); </script> </head>注意：localStorage的读取也可以放这里，但要包一层 try/catch，因为某些隐私模式或者旧浏览器下访问localStorage可能抛出异常，不能让它阻断页面脚本。
4. 实测高频踩坑：变灰不彻底、fixed 错位、卡顿
4.1 为什么 position: fixed 元素“乱跑”了
这是我在实际项目中栽得最深的一个坑。当你给html加上filter后，问题立刻出现：页面里使用了position: fixed的弹窗、悬浮按钮、遮罩层，它们的定位基准变了。
原因在于：filter作用在某个元素上时，该元素会创建一个 containing block（包含块）。正常情况下，fixed元素的包含块是视口（viewport），但当祖先元素上有filter时，fixed元素的包含块会变成最近的那个有滤镜的祖先元素。也就是说，html上加了滤镜后，所有fixed定位元素就不再看浏览器窗口，而是看整个html根元素。
大多数情况下 html 根元素尺寸和视口一致，视觉上问题不明显。但一旦页面有滚动条、或者根元素尺寸因为某些原因比视口小，fixed 元素就可能出现在意料之外的角落。
更稳妥的做法是：不要直接给html加 filter，而是给一个包裹全站内容的容器加，比如：
<body> <div id="app"> <!-- 全站内容 --> </div> </body>#app.gray-mode { filter: grayscale(1); -webkit-filter: grayscale(1); }注意两个问题：如果页面内容超高，容器高度会超过视口，fixed 元素的包含块会变成这个容器，也可能出现类似问题；有些弹窗是从 body 直接 append 的，不在#app内，就需要额外处理。所以这个方案不能一劳永逸，需要根据自己的页面结构测试调整。
我的经验是：如果项目页面结构简单、fixed 元素不多，直接在html上加 filter 问题不大；但如果你有复杂弹窗体系，一定要先单测 fixed 元素的定位，再上灰度。
4.2 变灰后对比度下降，内容看不清
整站变灰之后，原本靠颜色区分的 UI 元素会变得很难辨认。最典型的是表格斑马纹、按钮主色状态、表单错误提示。全灰之后所有颜色都变成了不同深浅的灰色，如果原设计的颜色明度相近，变灰后可能完全分不清。
几种实际情况：红色错误提示变成灰色，用户分不清是提示还是普通文案；蓝色链接变成灰色，看起来像普通文本；带背景色的按钮和旁边的普通按钮灰度后几乎一样。
遇到这种情况，可以在灰度基础上加一点对比度补偿：
html.gray-mode { filter: grayscale(1) contrast(1.05); -webkit-filter: grayscale(1) contrast(1.05); }contrast(1.05)意思是把整体对比度稍微拉高一点，让不同明度的元素拉开差距。这个值不要给太大，否则页面会发“闷”，我测试下来1.03 ~ 1.08是比较安全的区间。
如果仍然有某些关键元素看不清，最直接的办法是给它们单独调灰度下的样式。比如错误提示原本是红色，可以在灰度模式下把它的文字加粗或者把背景加暗：
html.gray-mode .error-tip { font-weight: 600; background: #555; color: #fff; }4.3 图片和背景图“没变灰”？
正常来说，父级加了filter，里面的图片和背景图都会被一起变灰。如果你发现某些图片没有变灰，大概率是这几个原因：
- 图片元素自身设置了
filter: none或者更高的样式优先级，覆盖了全局 filter； - CSS 里对图片单独定义了
filter属性，比如某些特效代码里给 img 加了阴影、模糊或者saturate，导致灰度效果被部分抵消； - 图片是 canvas、iframe、video 或某些第三方组件。
filter对 canvas 和视频的渲染结果不一定都生效，尤其是部分老浏览器，iframe 内的文档属于独立文档，父页面的滤镜无法穿透到 iframe 内部； - background-image 使用了 CSS 渐变或者通过 JavaScript 动态绘制的图形，个别浏览器处理异常。
遇到 canvas 和 iframe 内容不变灰的情况，在原生方案下没有特别通用的解决办法。iframe 如果来自自己域名，可以给 iframe 内的 html 元素也加同样的灰度 class；如果是第三方域名，那就只能接受原样显示，或者用覆盖层处理。canvas 部分其实也算少见，目前大多数现代浏览器对 canvas 的滤镜处理是没问题的。
4.4 动画和滚动卡顿，性能怎么调
全站灰度叠加在动画复杂的页面里，低端设备会比较吃力。原因在于页面每次重绘时，浏览器都要对全站像素做一次颜色矩阵变换。动画越频繁，开销越大。
我能给到的实操建议：灰度期间，可以用 CSS 选择器临时禁掉高开销动画；降低动画元素数量；如果页面有will-change: transform之类的属性，在灰度模式下可以临时移除或调整为auto。
html.gray-mode *, html.gray-mode *::before, html.gray-mode *::after { animation-play-state: paused; }这个方案比较激进，会把所有动画都暂停。如果不想全部暂停，可以只针对已知的大面积动画元素做暂停：
html.gray-mode .particle-canvas, html.gray-mode .banner-carousel { animation: none !important; }灰度模式本来就是一种“克制”的视觉状态，动画暂停反而更符合氛围。所以我在实际项目中一般选择灰度期间暂停大部分装饰性动画，只保留文字呼吸等低开销效果。
4.5 排除元素：Logo 要保留彩色，真没那么简单
很多网站要求：全站变灰，但顶部 Logo 要保持彩色。这个需求看着简单，实现起来是个大坑。
先说结论：如果灰度滤镜加在整个html或body上，你没有办法通过给某个子元素加filter: none来还原它的彩色。因为filter不是继承属性，但它作用于整个渲染结果，子元素自身的filter: none只能取消它自己的滤镜，无法抵消祖先层级已经施加的灰度变换。
所以“保留 Logo 彩色”的正确做法，是从一开始就不要把 filter 加在全体元素上，而是在结构上分区域。比如把页面主体内容包在一个容器里，Logo 区单独放外面，然后只给内容容器加灰度：
<body> <header class="site-header"> <img src="logo.png" alt="logo" class="logo"> <!-- 保持彩色 --> </header> <div id="main" class="gray-area"> <!-- 这部分内容变灰 --> </div> </body>.gray-area { filter: grayscale(1); -webkit-filter: grayscale(1); }这个方案才是最可靠的。如果页面上要排除的元素散落在各个位置，不好统一包容器，那就用另一种思路：给除了排除元素之外的所有元素加灰度。思路比较粗暴，但可行：
html.gray-mode body *:not(.keep-color):not(.keep-color *) { filter: grayscale(1) !important; -webkit-filter: grayscale(1) !important; }注意这里有个很重要的细节：排除元素如果有子元素，要同时把.keep-color本身和它的所有后代都排除掉，不然 Logo 图片作为后代会再次被*的灰度规则击中。上面写法里:not(.keep-color *)就是干这个的。
但这个方案有性能隐患：选择器会匹配全站所有元素，给每个元素单独加滤镜，开销比整站加一个滤镜大得多。所以它只适合元素不算太多的页面；如果页面有几万个 DOM 节点，建议还是改结构、分区域加灰度。
5. 把“能用”的方案变成“好用”的方案：封装与上线清单
5.1 完整封装：一份可复制的独立脚本
综合上面所有逻辑，我整理了一份可以直接复制到项目里的独立脚本。它支持按钮切换、localStorage 记忆、URL 参数强切、日期范围自动切换，并且把防闪烁处理放在了 head 内联脚本里。
<!doctype html> <html lang="zh-cn"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>原生html一键实现网站黑白模式</title> <style> html { transition: filter 0.3s ease; } html.gray-mode { filter: grayscale(1) contrast(1.05); -webkit-filter: grayscale(1) contrast(1.05); } /* 需要排除彩色的元素 */ .keep-color, .keep-color * { filter: none !important; -webkit-filter: none !important; } </style> <script> (function () { var KEY = 'gray-mode-enabled'; function apply(enable) { document.documentElement.classList.toggle('gray-mode', enable); var btn = document.getElementById('grayToggle'); if (btn) btn.textContent = enable ? '关闭黑白模式' : '开启黑白模式'; } function getQuery(name) { var m = new RegExp('[?&]' + name + '=([^&]*)').exec(location.search); return m ? decodeURIComponent(m[1]) : null; } function inGrayPeriod() { var now = new Date(); var start = new Date('2025-10-01T00:00:00'); var end = new Date('2025-10-03T23:59:59'); return now >= start && now <= end; } try { if (inGrayPeriod()) { apply(true); } else if (getQuery('gray') === '1') { apply(true); } else if (localStorage.getItem(KEY) === '1') { apply(true); } } catch (e) { // localStorage 不可用时静默降级，不阻塞页面 } window.grayModeAPI = { on: function () { apply(true); try { localStorage.setItem(KEY, '1'); } catch (e) {} }, off: function () { apply(false); try { localStorage.setItem(KEY, '0'); } catch (e) {} }, toggle: function () { var isGray = document.documentElement.classList.contains('gray-mode'); isGray ? this.off() : this.on(); } }; })(); </script> </head> <body> <button class="gray-toggle" id="grayToggle" type="button">开启黑白模式</button> <script> document.getElementById('grayToggle').addEventListener('click', function () { window.grayModeAPI.toggle(); }); </script> </body> </html>这段代码暴露了一个window.grayModeAPI，除了给按钮用，运营也可以直接在控制台执行grayModeAPI.on()或grayModeAPI.off()，非常方便排查问题。如果你只需要某个单页临时强切，复制这段代码进去改一下日期即可。
5.2 上线前走一遍的灰度验证清单
经历过几次“切了之后才发现问题”之后，我给自己列了一份检查清单，每次上线前逐项打勾：
- 全站主要页面是否都正常变灰：首页、列表页、详情页、登录页；
- 页面上所有
position: fixed元素（弹窗、抽屉、悬浮按钮）定位是否正常； - Logo 等需要保留彩色的元素是否正常保持彩色，没有被父级灰度影响；
- 视频、canvas、iframe 是否达到预期效果；如果无法变灰，确认是否可以接受；
- 灰度模式下文字对比度是否可读，尤其是表格、表单错误提示、链接；
- 灰度模式下图片是否正常，特别是深色背景图和半透明 PNG；
- 移动端页面在低端 Android 机型上是否有明显卡顿；
- 从灰度切回正常模式后，页面状态是否完全恢复，没有残留样式。
这份清单很适合让测试同学照着验收，避免漏项。
5.3 黑白模式、暗黑模式别搞混
不少产品同学会把“黑白模式”和“暗黑模式（Dark Mode）”混为一谈。这两者目标完全不同：黑白模式强调的是“去色”，把所有彩色内容变成黑白灰，常用于纪念氛围或归档页面；暗黑模式强调的是“低亮度”，把亮色背景换成深色背景，同时通常仍然保留内容的色彩体系。
技术上也不同：黑白模式用filter: grayscale(1)就能做全员钝化；暗黑模式则需要大量适配，关掉 filter 的事。如果项目同时有暗黑模式和黑白模式需求，建议把它们做成两套独立控制，不要叠加。否则又暗又灰，页面基本没法看。
如果一个元素在暗黑模式有特定的深色样式，灰度模式下其实不用额外处理，灰度会把它压平；但如果这个元素刻意保留了彩色（比如灰度模式下的彩色 Logo），在暗黑模式下反而要单独验证显示效果。
5.4 配合自动化截图做回归检查
黑白模式这种“全站视觉变化”的需求，靠人肉测试很累，而且容易漏页面。我的做法是在项目的自动化测试里加一条截图对比用例：开启灰度模式后，抓取关键页面的截图，站在人工审核的角度快速扫一遍，确认没有布局错位、元素消失、fixed 元素乱跑。
没有自动化条件的项目，可以在浏览器控制台手动执行：
document.documentElement.classList.add('gray-mode');然后逐个页面过一遍检查清单上的重点项目。切回来就是：
document.documentElement.classList.remove('gray-mode');这种方式和跑完整套代码没区别，因为页面应用的就是同一套 class 逻辑。
我个人的习惯是：黑白模式这种功能平时就埋在项目里，用一个隐藏的全局变量控制默认关闭，只在特殊时期打开。这样每次上线前测试也能顺带回归到，而不是需求来了临时改代码，改完又要急着发版。灰度功能本身很简单，真正有价值的是把它沉淀成一套可靠、可复用、可验证的机制，下次再有类似需求时，你只需要把日期改一下就行。
