Docusaurus v2 如何实现暗黑模式下index.js中SVG图片的切换
Docusaurus v2 页面内嵌SVG暗黑模式适配落地方法
以下方案适配你提到的场景:SVG文件存放在站点src/pages/index.js源码内、不属于Markdown文档内嵌资源、JS基础薄弱、官方文档未覆盖通用内嵌图片的暗黑适配逻辑,全程不需要复杂JS编写。
方案1:纯CSS双图自动切换(零JS逻辑,新手友好度最高)
这个方案和官方导航栏、页脚图片的适配底层逻辑完全一致,完全依赖Docusaurus原生的主题状态标记实现,不需要额外写事件监听、状态判断逻辑。
- 操作步骤:
- 把明暗两套SVG文件放到项目
static/img/目录下,比如明模式文件命名为light-banner.svg,暗模式文件命名为dark-banner.svg,不需要配置额外的Webpack打包规则。 - 打开
src/pages/index.js,找到原来插入图片的位置,替换为以下结构:
如果你之前是用<div className="theme-aware-svg"> {/* 明模式显示的SVG */} <img src="/img/light-banner.svg" alt="页面主视觉SVG" className="light-svg" /> {/* 暗模式显示的SVG */} <img src="/img/dark-banner.svg" alt="页面主视觉SVG" className="dark-svg" /> </div>import方式引入SVG的,只需要把src的值替换成你import的变量名即可,外层结构不需要改动。
3. 打开全局样式文件src/css/custom.css,追加以下样式:.theme-aware-svg { position: relative; /* 保持你原图片的宽高规则即可,比如aspect-ratio、max-width等 */ } .theme-aware-svg img { position: absolute; top: 0; left: 0; width: 100%; } /* 明模式下隐藏暗模式SVG */ [data-theme='light'] .theme-aware-svg .dark-svg { display: none; } /* 暗模式下隐藏明模式SVG */ [data-theme='dark'] .theme-aware-svg .light-svg { display: none; } - 把明暗两套SVG文件放到项目
- 实现原理:Docusaurus切换暗黑模式时,会自动给页面根
<html>标签增加/移除data-theme="dark"的属性标记,上面的CSS选择器直接匹配这个属性值,就能自动完成图片切换,不会出现主题切换延迟、 hydration 报错的问题。
方案2:单SVG内联样式适配(无需拆分两套图片文件)
如果你的SVG是直接在index.js里以内联标签形式书写的,不需要准备两套图片,可以直接通过CSS控制SVG的颜色实现适配。
- 操作步骤:
- 给你的内联SVG标签加上自定义class,比如
className="theme-aware-icon" - 在
src/css/custom.css中追加对应主题的样式,直接修改SVG的填充、描边属性即可:
/* 明模式下的SVG颜色规则 */ .theme-aware-icon path { fill: #24292f; stroke: #24292f; } /* 暗模式下自动切换为适配深色背景的颜色 */ [data-theme='dark'] .theme-aware-icon path { fill: #f0f6fc; stroke: #f0f6fc; } - 给你的内联SVG标签加上自定义class,比如
- 适用场景:这个方法适合图标类的简单SVG,不需要额外加载两个图片文件,加载性能更好;如果是复杂的插画类SVG,还是推荐用方案1的双图切换逻辑。
避坑注意事项
- 不要自行编写JS逻辑监听主题按钮点击事件、判断当前页面主题状态。Docusaurus原生已经维护了全局的
data-theme属性状态,自行编写JS很容易和原生逻辑冲突,出现页面首次加载时的图片闪烁、 hydration 报错问题。 - 该适配逻辑为通用实现,不受官方文档仅覆盖导航栏、页脚图片场景的限制,
index.js及其他所有React组件内的内嵌图片,都可以复用同样的逻辑。
内容的提问来源于stack exchange,提问作者Ignacio Díaz R.
相关产品推荐
相关产品推荐

