BewlyBewly Adapted Styles 开发指南：编写深色模式与主题色适配样式的规范与实践

前端【免费下载链接】BewlyBewlyJust make a few small changes to your Bilibili homepage. (English | 简体中文 | 正體中文 | 廣東話)项目地址https://gitcode.com/gh_mirrors/be/BewlyBewly点击查看免费下载导读BewlyBewly 是一个对 Bilibili 首页及相关页面进行深度改造的开源浏览器扩展项目。为了让改造后的界面与用户自定义主题色、深色模式保持一致项目维护了一套独立的样式体系——Adapted Styles。本文以 src/styles/adaptedStyles/adaptedStyles-cmn_TW.md 为核心结合仓库中真实源码系统讲解 Adapted Styles 的目录结构、样式文件书写规范、页面路由正则匹配机制以及--bew-*CSS 变量体系的使用方法。读完本文你将能够为 BewlyBewly 新增或修改任意 Bilibili 页面的深色模式与主题色适配样式。一、Adapted Styles 是什么Adapted Styles适配样式是 BewlyBewly 中专门用于承载深色模式Dark ModeCSS与主题色Theme Color替换的一组样式文件。其定位非常明确由于 Bilibili 原站页面已经自带一套完整的原始样式BewlyBewly 无法直接以页面专属的纯 CSS覆盖之而是需要一套可复用的、按页面路由动态加载的适配规则。整个样式体系围绕两个问题展开如何确定当前页面在 src/styles/adaptedStyles/index.ts 中编写一系列正则表达式来匹配当前 URL从而判断正在访问的是 Bilibili 的哪个具体页面如何书写覆盖样式针对不同页面分别提供 SCSS 文件按照统一的书写规范将主题色适配与深色模式适配两块逻辑分区域组织。因此Adapted Styles 既是一套样式文件组织约定也是一套运行时路由分发机制。下面分别展开。二、目录结构与加载机制2.1 目录布局Adapted Styles 的所有代码集中在 src/styles/adaptedStyles/ 下分为四个子目录加一个入口路径作用common/全站通用适配样式顶栏、评论、页脚、弹窗、按钮、用户卡片、播放器、登录弹窗等pages/按页面拆分的专属适配样式首页、视频页、搜索页、番剧页等shadowDom/作用于 Shadow DOM 内部的样式评论、用户资料卡thirdParties/针对第三方脚本如 bilibili-evolved、bilibili-enhance-video-list的适配index.ts入口按 URL 正则动态加载各页面样式并在html上挂载对应的 classforceDark.scss强制深色样式用于创作中心等无法常规适配的页面其中common/与shadowDom/、thirdParties/均为无条件静态引入见 common/index.ts、shadowDom/index.ts 与 thirdParties/index.ts而pages/下的各页面样式则通过入口文件按需动态import()。2.2 入口文件的运行逻辑src/styles/adaptedStyles/index.ts 的整体流程如下静态引入通用、Shadow DOM 与第三方适配样式读取document.URL按顺序对 URL 执行一系列正则匹配if / else if链命中某个页面规则后动态import()对应页面的 SCSS并在document.documentElement上添加形如homePage、videoPage、searchPage的 class页面级样式文件中通过.bewly-design.pageName选择器挂载适配规则。以首页为例匹配逻辑为const currentUrl document.URL // homepage 首页 if (isHomePage()) { await import(./pages/homePage.scss) document.documentElement.classList.add(homePage) }isHomePage()定义于 src/utils/main.ts用于判断是否为 Bilibili 首页。2.3 页面路由正则速查表以下正则均来自 src/styles/adaptedStyles/index.ts用于按 URL 分发到 pages/ 下对应的 SCSS 文件页面URL 正则节选挂载 class对应样式文件首页isHomePage()homePagepages/homePage.scss消息页/https?:\/\/message\.bilibili\.com\.*/notificationsPagepages/notificationsPage.scss动态页 / 新版专栏页/https?:\/\/t\.bilibili\.com\.*/或/https?:\/\/www\.bilibili\.com\/opus\/.*/momentsPagepages/momentsPage.scss历史记录页/https?:\/\/(?:www\.)?bilibili\.com\/(?:account\/)?history.*/historyPagepages/historyPage.scss稍候再看页/...\/watchlater\/(?:list|#\/list).*/watchLaterPagepages/watchLaterPage.scss笔记页/https?:\/\/space\.bilibili\.com\.*\/v\/note-list/notePagepages/notePage.scss空间页/https?:\/\/space\.bilibili\.com\.*/userSpacePagepages/userSpacePage.scss搜索结果页/https?:\/\/search\.bilibili\.com\.*/searchPagepages/searchPage.scss视频页 / 合集 / 收藏播放页/...\/video\/.*/等videoPagepages/videoPage.scss番剧 / 电影播放页/...\/bangumi\/play\/.*/animePlaybackAndMoviePagepages/animePlaybackMoviePage.scss番剧页 / 国创动漫/...\/(?:anime|guochuang).*/animePagepages/animePage.scss分区页影视/综艺等/...\/(?:tv|movie|variety|mooc|documentary).*/channelPagepages/channelPage.scss专栏相关/...\/read.*/articlesPagepages/articlesPage.scss话题页/...\/v\/topic\/detail\/.*/topicPagepages/topicPage.scss404 页/^https?:\/\/(?:www\.)?bilibili\.com\/404.*$/error404Pagepages/error404Page.scss创作中心/^https?:\/\/member\.bilibili\.com\/platform.*$/forceDarkcreativeCenterPageforceDark.scss pages/creativeCenterPage.scss账户设置页/^https?:\/\/account\.bilibili\.com\/(?!big).*$/accountSettingsPagepages/accountSettingsPage.scss大会员页/^https?:\/\/account\.bilibili\.com\/big.*$/premiumPagepages/premiumPage.scss登录页/^https?:\/\/passport\.bilibili\.com\/login.*$/loginPagepages/loginPage.scss值得注意的细节正则使用非捕获分组(?:...)与.*通配兼顾www前缀有无、路径子级差异账户设置页正则中的(?!big)是否定前瞻用于把大會員頁big排除在账户设置页之外避免两个规则互相覆盖创作中心页面同时挂载forceDark与creativeCenterPage两个 class其中forceDark对应的 src/styles/variables.scss 会注入--bew-filter-force-dark滤镜变量用于对无法逐条适配的页面做整页反向滤镜强转深色。三、样式文件书写规范核心模板文档中给出了页面级 SCSS 的标准模板这是所有pages/下文件必须遵循的骨架。以下为完整模板原文逐条保留并附带每一区域的注释说明.bewly-design.pageName { // 在此處實施對頁面的特定修改例如調整佈局並將那些樣式放在這裡。 .right-side-bar .catalog { line-height: 3em; } // ... // #region theme color adaption part // 透過在 :not() 中寫入一個不存在的選取器來提高內部樣式的優先級。 :not(foobar) { a, b, c { color: var(--bew-theme-color); } d, e, f { // 請注意使用 !important 應該是最後萬不得已的手段 color: var(--bew-theme-color) !important; } g, h, i { background-color: var(--bew-theme-color); } j, k, l { background-color: var(--bew-theme-color) !important; } // ... } // #endregion // #region dark mode adaption part .dark { aa, bb, cc { color: var(--bew-text-1); } dd, ee, ff { color: var(--bew-text-1) !important; } // ... } // #endregion }模板的结构可以拆解为三层顶层选择器.bewly-design.pageName.bewly-design是全局设计命名空间pageName是 index.ts 在html上挂载的页面 class如homePage、videoPage。两相结合确保样式只作用于当前被匹配的页面不会泄漏到其他页面#region theme color adaption part主题色适配区处理所有与主题色用户自定义主色相关的颜色#region dark mode adaption part深色模式适配区通过.dark处理深色模式下的文字、背景与边框颜色。3.1 主题色适配区:not(foobar)提升优先级原文档特别强调主题色适配区内的所有规则都包裹在一个:not(foobar)选择器中。foobar是一个不存在的元素因此:not(foobar)永远匹配所有元素。这个写法的唯一目的就是提高内部选择器的优先级specificity使适配样式能够覆盖 Bilibili 原站同权重的样式而无需到处使用!important。在该区域内按颜色用途将选择器分组color: var(--bew-theme-color);—— 文字/图标类颜色直接使用主题色color: var(--bew-theme-color) !important;—— 需要强制覆盖的文本颜色慎用background-color: var(--bew-theme-color);—— 背景填充类颜色background-color: var(--bew-theme-color) !important;—— 需要强制覆盖的背景色。3.2 深色模式适配区.dark深色模式适配区使用.darkSCSS 嵌套等价于.bewly-design.pageName.dark作为作用域颜色统一取自--bew-text-1等语义化文本变量而不是硬编码白色。同样按文字色与背景色分组!important仅作为最后手段。3.3!important的使用红线文档中明确强调使用!important应该是最後萬不得已的手段LAST RESORT。能通过:not(foobar)提升优先级解决的绝不使用!important以保证样式可维护性与覆盖的可控性。四、为什么必须采用这套书写风格原文档用专节解释了为什么要用上述写法这是理解整套规范的关键。核心原因有三4.1 原站已有完整样式无法从零覆盖Bilibili 的页面并非由 BewlyBewly 的样式初始化而是自带一套完整的原始样式。因此不能简单地写xxx { border: 1px solid white; color: black; }这种写法既无法保证优先级也没有考虑原站样式的差异直接写会难以稳定覆盖。4.2 深色模式维护的本质是颜色三要素深色模式适配本质上只需要处理三类颜色字体颜色、背景颜色、边框颜色。如果样式书写毫无组织、每条规则各自为政当用户切换主题或深色模式时就无法批量、统一地调整颜色。4.3 按颜色类型分组 高效可维护文档给出的结论是根据字体颜色、背景颜色和边框颜色对选择器进行分组是最高效的将同类选择器放在一起、用统一方法处理便于后续维护。当需要调整某类颜色时只需修改对应分组中的对应选择器即可无需在成百上千行规则中逐个翻找。五、--bew-*CSS 变量体系适配样式的颜料盒Adapted Styles 中的所有颜色都通过 CSS 变量引用这套变量统一定义在 src/styles/variables.scss 中。理解这些变量是正确编写适配样式的前提。5.1 主题色与语义色变量含义与典型用法--bew-theme-color用户自定义的主题色默认hsl(195 100% 42%)即 Bilibili 蓝--bew-theme-color-10~--bew-theme-color-90主题色的 10%~90% 透明版本通过color-mix(in oklab, ...)实现用于 hover 态如--bew-theme-color-80、淡色背景等--bew-info-color/--bew-success-color/--bew-warning-color/--bew-error-color信息、成功、警告、错误四类语义色同样配套-10~-90透明梯度--bew-theme-color-auto亮色模式下取黑色、深色模式下取白色的自动主题色透明梯度变量的存在让主题色适配区可以优雅地处理主色 透明度的组合例如按钮 hover 使用--bew-theme-color-80。5.2 文本色变量用途--bew-text-1一级文本色深色模式下接近白色亮色模式下接近黑色是深色模式适配区的主力变量--bew-text-2次级文本色也可用于已关注/已订阅状态的文字--bew-text-3三级文本色--bew-text-4弱化/禁用文本色--bew-text-auto自动文本色5.3 背景、填充与边框色页面背景--bew-bg非首页背景、--bew-homepage-bg首页背景Bilibili 首页使用单独的背景色变量见 variables.scss内容背景--bew-content、--bew-content-solid及各自的-hover、-alt变体。不含solid的用于毛玻璃元素默认--bew-content-opacity: 0.68含solid的用于平面元素浮层背景--bew-elevated系列用于弹窗、下拉等更高层级填充色--bew-fill-1~--bew-fill-4灰色半透明用于顶层元素、hover、禁用态、毛玻璃遮罩边框色--bew-border-color。5.4 毛玻璃与阴影滤镜适配样式尤其是顶栏、头部经常会用到毛玻璃效果相关的滤镜与阴影变量包括--bew-filter-glass-1blur(20px) saturate(180%)用于普通组件毛玻璃--bew-filter-glass-2blur(30px) saturate(180%)用于弹窗毛玻璃--bew-shadow-1~--bew-shadow-4四级阴影卡片、顶栏、弹层、对话框--bew-shadow-edge-glow-1/-2毛玻璃边缘高光模拟--bew-filter-icon-glow用于把 Bilibili 品牌蓝/粉图标转化为跟随主题色的发光效果见 variables.scss。上述所有颜色变量都在深色模式下由 variables.scss 中的:root.dark分支整体替换为深色值因此适配样式只需引用变量名就能自动跟随主题切换。六、实战对照真实页面样式的写法解读6.1 首页适配pages/homePage.scss以首页样式为例看模板如何落到实际代码中.bewly-design.homePage { // 大屏下修复推荐容器未填满的问题 .recommended-container_floor-aside .container { max-width: 100% !important; } // 改造 Bilibili 原站固定头部毛玻璃 悬浮阴影 .header-channel { background-color: transparent; backdrop-filter: var(--bew-filter-glass-1); background: var(--bew-elevated); box-shadow: var(--bew-shadow-2), var(--bew-shadow-edge-glow-1); } .header-channel-fixed-right-item { background-color: var(--bew-fill-1); border-color: var(--bew-border-color); :hover { background-color: var(--bew-fill-2); } } .dark { .floor-card .floor-title { color: var(--bew-text-1); } .single-card.floor-card .badge { background-color: var(--bew-content-solid); } } }这段代码完整体现了模板的三个要点顶层.bewly-design.homePage限定作用域页面专属布局修改大屏容器修复放在最前颜色无关深色模式区域使用.dark--bew-text-1/--bew-content-solid且没有滥用!important。6.2 全站公共适配common/topBar.scss全站公共样式同样遵循规范但顶层选择器直接使用.bewly-design不带页面 class并完整呈现了主题色适配区的实际写法.bewly-design { // 顶栏毛玻璃 .bili-header .slide-down, .bili-header .mini-header { background-color: var(--bew-elevated) !important; backdrop-filter: var(--bew-filter-glass-1); } // #region theme color adaption part // 通过 :not(foobar) 提升优先级 :not(foobar) { .bili-header .header-upload-entry { background-color: var(--bew-theme-color); } .bili-header .header-upload-entry:hover { background-color: var(--bew-theme-color-80); } } // #endregion // #region dark mode adaption part // .dark { // } // #endregion }这段代码展示了主题色适配区的典型场景上传入口按钮使用主题色--bew-theme-colorhover 时切换到--bew-theme-color-80以表达悬浮态——这正对应 variables.scss 注释中用--bew-*-color作基础色、--bew-*-color-80作 hover 态的约定。6.3 主题色如何接管Bilibili 原站变量Adapted Styles 不仅引入新的--bew-*变量还会在 variables.scss 中把 Bilibili 原站使用的大量变量--brand_pink、--brand_blue、--text_link等统一重映射到--bew-theme-color并在深色模式下variables.scss将--bg1、--text1、--line_light等原站变量重映射到--bew-*体系。这意味着适配样式无需逐一覆盖 Bilibili 的每一个组件只要原站组件本身使用了这些 CSS 变量就会被主题色与深色模式自动接管。七、动手实践新增一个页面的适配样式结合上述机制为 BewlyBewly 新增一个页面的完整流程如下在 src/styles/adaptedStyles/index.ts 中新增正则分支在setupStyles()的if / else if链末尾添加对该页面 URL 的匹配规则await import(./pages/xxxPage.scss)并在document.documentElement上挂载对应 class在 pages/ 下新建 SCSS 文件如xxxPage.scss以.bewly-design.xxxPage为顶层选择器套用标准模板把页面专属布局修改放在顶部用#region theme color adaption part:not(foobar)处理主题色用#region dark mode adaption part.dark处理深色模式颜色一律引用--bew-*变量variables.scss 中定义不要硬编码十六进制或white/black克制使用!important优先依靠:not(foobar)提升优先级。完成上述步骤后新页面即可自动获得主题色跟随与深色模式能力且与现有 18 个页面pages/ 下每个 SCSS 对应一个保持一致的维护模式。八、总结BewlyBewly 的 Adapted Styles 体系可以用一句话概括用正则路由把哪个页面和怎么写样式解耦用--bew-*变量把颜色值与主题/深色模式解耦再用.bewly-design.pageName:not(foobar).dark的组合把覆盖范围、优先级和模式切换收拢到可控的维度。这套规范的核心价值在于作用域清晰每个页面的适配互不干扰全站公共部分单独沉淀在common/颜色可维护所有颜色引用语义化变量主题色与深色模式一键联动优先级可控用:not(foobar)这类巧妙的优先级提升替代散落的!important。如果你计划为 BewlyBewly 贡献样式或深度定制某个页面的外观请从阅读 adaptedStyles.md英文原版与本文件开始并对照 index.ts、variables.scss 与 pages/homePage.scss 三个真实样例即可快速上手。赞分享前端【免费下载链接】BewlyBewlyJust make a few small changes to your Bilibili homepage. (English | 简体中文 | 正體中文 | 廣東話)项目地址https://gitcode.com/gh_mirrors/be/BewlyBewly点击查看免费下载相关推荐BewlyBewly 暗色模式与主题色适配Adapted Styles 目录结构与 SCSS 编写规范实战指南BewlyBewly 暗色模式与主题色适配Adapted Styles 目录结构与 SCSS 编写规范实战指南 本篇技术指南以 src/styles/adap前端BewlyBewly 适配样式体系Adapted Styles深度指南暗色模式与主题色定制的 SCSS 写作规范BewlyBewly 适配样式体系Adapted Styles深度指南暗色模式与主题色定制的 SCSS 写作规范 BewlyBewly 通过向 Bilib前端BewlyBewly Adapted Styles 实战指南为 Bilibili 页面编写可维护的暗色模式与主题色适配样式BewlyBewly Adapted Styles 实战指南为 Bilibili 页面编写可维护的暗色模式与主题色适配样式 本文以 BewlyBewly 仓库前端上一篇redux-observable性能优化使用操作符组合减少冗余代码下一篇深入解读 miniredis v2 演进史纯 Go 内存 Redis 测试服务器的能力边界与实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考