Bilibili-Evolved「隐藏首页顶部横幅」组件源码解析样式机制、多版本兼容与暗色模式适配【免费下载链接】Bilibili-Evolved强大的哔哩哔哩增强脚本项目地址: https://gitcode.com/gh_mirrors/bi/Bilibili-Evolved本文以 Bilibili-Evolved 增强脚本仓库中的 hide/banner 组件为对象从功能定位、组件注册元数据、CSS 样式实现三个层面展开完整讲解“隐藏首页顶部横幅”这一纯样式组件的实现原理与落地细节。读完本文你将理解 Bilibili-Evolved 中instantStyles即时样式机制如何工作、urlInclude如何限定组件生效范围以及该组件如何通过一组 CSS 规则同时兼容 B 站旧版/新版首页与国际版首页并正确处理暗色模式下的文字可读性问题。一、功能定位一句话文档背后的完整组件该组件的说明文档只有一句话——index.md 中写道隐藏首页顶部横幅.这看似简单的描述对应的是 Bilibili-Evolved「样式Style」分类下的一个完整组件。从仓库结构看它由三个文件组成文件作用index.ts组件元数据定义声明组件名称、生效 URL 范围、注入的样式资源banner.scss组件核心样式实现约 60 行 SCSSindex.md组件说明文档其中index.ts负责把组件注册进 Bilibili-Evolved 的组件体系而banner.scss才是真正实现“隐藏顶部横幅”这一视觉效果的关键。它并不像多数组件那样包含entry运行时代码即页面加载后执行的 JS 逻辑而是一个纯即时样式组件——通过注入 CSS 完成所有工作这是它最值得注意的设计特点。二、组件注册元数据与即时样式机制先看 index.ts 的完整实现import { defineComponentMetadata } from /components/define import { mainSiteUrls } from /core/utils/urls export const component defineComponentMetadata({ name: hideBanner, entry: none, displayName: 隐藏顶部横幅, instantStyles: [ { name: hideBanner, style: () import(./banner.scss), }, ], tags: [componentsTags.style], urlInclude: mainSiteUrls, })逐字段解读name: hideBanner组件的唯一标识符也是样式注入时使用的 ID用于开关组件时精确移除对应style标签。entry: none入口函数为none说明该组件没有运行时 JS 逻辑一切行为都由样式完成。entry在 组件类型定义 中是“主入口”这里显式置空强化了“纯样式组件”的定位。displayName: 隐藏顶部横幅显示在设置面板中的组件名称。instantStyles即时样式列表。类型定义见 src/components/types.ts其中style既可以是字符串也可以是“返回样式内容的函数”。这里用() import(./banner.scss)做按需懒加载——只有在组件被启用时才动态拉取并注入 SCSS 编译产物。这类样式会在 DOMContentLoadedDCL之前尽快注入避免页面首屏出现“先显示横幅、后被隐藏”的闪烁。tags: [componentsTags.style]将组件归类到「样式」标签下便于在设置面板中按类别筛选与always-show-duration、dark-mode等样式组件同属一类。urlInclude: mainSiteUrls生效的 URL 范围。mainSiteUrls定义于 src/core/utils/urls.tsexport const mainSiteUrls [ https://www.bilibili.com/v/, https://www.bilibili.com/c/, /^https:\/\/www\.bilibili\.com\/$/, /^https:\/\/www\.bilibili\.com\/([^\/])\.html$/, /^https:\/\/www\.bilibili\.com\/watchlater\/#\/list$/, https://www.bilibili.com/account/, ]即组件只在 B 站主站首页www.bilibili.com根路径、分区页/v/、/c/、*.html页面、稍后再看列表页与账号页生效在直播间live.bilibili.com、动态t.bilibili.com等子站不会运行避免误伤其他页面布局。这种“匹配 URL 才注入”的机制由urlInclude/urlExclude字段驱动是 Bilibili-Evolved 所有组件的通用行为。三、样式实现逐段拆解banner.scss 的兼容策略真正决定视觉效果的是 banner.scss。整份样式按“先全局隐藏横幅 → 再修补布局高度 → 最后修正文字颜色”的顺序组织分四个层次展开。3.1 核心隐藏横幅容器#banner_link, .z-top-container.has-banner .header, .custom-navbar .blur-layer, .bili-header__banner { display: none !important; }这一组选择器覆盖了 B 站历史上多种横幅形态#banner_link早期首页横幅的链接容器.z-top-container.has-banner .header旧版顶栏在“有横幅”状态下的头部容器.custom-navbar .blur-layerBilibili-Evolved 自带的「自定义顶栏」组件custom-navbar所渲染的模糊层——若用户同时启用了自定义顶栏此处一并隐藏其背景模糊层避免横幅消失后残留毛玻璃效果.bili-header__banner新版首页.bili-header体系的横幅节点。统一使用display: none !important确保优先级高于 B 站自身样式无论组件以何种顺序注入都能生效。3.2 修补消除横幅被隐藏后的留白隐藏元素后B 站样式仍可能为横幅预留了高度因此需要针对性重置#biliMainHeader { min-height: unset !important; } .header-v3 .z-top-container { min-height: 160px !important; } .bili-header { padding-top: 50px !important; min-height: 0 !important; }#biliMainHeader是旧版页面的主头部其min-height会因横幅存在而被撑高这里重置为unset.header-v3 .z-top-container属于 2019 年左右的 v3 顶栏方案横幅模式下容器被固定为 160px 高度因此显式写回 160px 以适配无横幅的紧凑布局.bili-header是新版顶栏容器将顶部内边距压缩为 50px、最小高度归零让顶栏内容导航、登录入口等直接贴顶显示不再为横幅让位。这三条规则分别对应不同年代的页面结构体现了组件对 B 站历次改版的兼容思路宁可多写几条历史选择器也不遗漏任一版本的用户。3.3 深挖遮罩层与背景图清理横幅往往伴随半透明背景遮罩或大图背景单靠隐藏容器并不彻底div.blur-bg, .b-header-mask-wrp .b-header-mask-bg { opacity: 0 !important; } .international-header .bili-banner, .international-home .bili-banner { visibility: hidden !important; height: 50px !important; min-height: unset !important; }div.blur-bg与.b-header-mask-wrp .b-header-mask-bg是横幅背后的大图背景/遮罩层用opacity: 0而非display: none隐藏避免破坏布局结构国际版首页.international-header、.international-home的横幅采用visibility: hidden 高度压缩为 50px 的方式处理与主站新版顶栏保持一致的紧凑观感。3.4 可读性修复白底上的文字颜色还原这是整份样式中最值得关注的部分。源码注释banner.scss说明了原因隐藏顶部横幅后, 新版首页顶栏 (.bili-header) 各入口仍停留在横幅上的白色文字/图标状态, 但背景已变白, 导致白底白字不可见 (需下滑才恢复). 逐类将文字与图标覆盖为深色 (暗色模式保持浅色).也就是说B 站新版首页的顶栏文字默认是为“深色横幅背景”设计的白色横幅一旦被移除顶栏露出白色背景白色文字便不可见。因此需要逐类覆盖.nav-link .nav-link-ul .nav-link-item .link, .nav-user-center .user-con .item .name { color: black !important; text-shadow: none !important; body.dark { color: #eee !important; } }旧版顶栏的导航链接与用户名统一改为黑色、去除文字阴影并嵌套body.dark 在 Bilibili-Evolved 暗色模式启用时切回#eee浅色保证暗色主题下文字依然清晰。新版顶栏.bili-header的处理更细致分为文字与图标两组.bili-header { .left-entry, .right-entry { .entry-title, .default-entry, .download-entry, .right-entry-text, .header-login-entry, .go-login-btn { color: black !important; text-shadow: none !important; body.dark { color: #eee !important; } } } // 图标为 SVG 且使用 currentColor, 设 color 即可连带修正 fill: 左侧小电视 logo 与右侧入口图标 .left-entry .zhuzhan-icon, .right-entry .right-entry-icon { color: black !important; body.dark { color: #eee !important; } } }其中有一个值得学习的 CSS 技巧左侧小电视 logo 与右侧入口图标是使用currentColor的 SVG因此只需设置color属性fill便会随之联动修正无需逐个覆盖fill。注释还特别说明粉色投稿按钮.header-upload-entry本就是白字白图标配粉底不在覆盖范围内见 issue #5496体现了实现者对细节边界的精确把握。四、组件体系中的定位与 hide 家族及其他样式组件的关系在registry/lib/components/style/hide/目录下banner与bangumi、home-carousel、trending-search、user-card、user-pendent、video等组件共同构成 Bilibili-Evolved 的「隐藏」系列目标都是“移除首页/视频页的干扰元素”。它们的实现范式高度一致文档一句话描述功能index.ts声明元数据CSS/SCSS 文件承载全部实现。与hide-banner相关的还有两个值得一提的协作点自定义顶栏联动若用户同时启用 custom-navbar 组件banner.scss 中的.custom-navbar .blur-layer规则会主动隐藏自定义顶栏的模糊背景层保证视觉效果统一与 dark-mode 的协作通过body.dark 嵌套选择器SCSS 语法组件在 Bilibili-Evolved 暗色模式开启时自动切换文字颜色无需额外配置体现了样式组件之间通过全局body.dark类协同工作的约定。五、使用与配置该组件作为 Bilibili-Evolved 的内置/在线仓库组件无需修改仓库即可使用安装并打开 Bilibili-Evolved 的设置面板在「样式」分类tags中的style标签下找到「隐藏顶部横幅」组件hideBanner开启开关后组件会通过instantStyles机制立即注入banner.scss编译产物横幅即刻消失关闭开关时框架会依据样式 IDhideBanner移除对应style标签相关逻辑见 src/components/user-component.ts 中对instantStyles的移除处理页面恢复原样。由于组件没有任何选项EmptyOptions无需任何参数配置其生效页面由urlInclude: mainSiteUrls决定在主站首页、分区页等场景自动运行进入直播间、动态等子站时自动停用。六、小结「隐藏首页顶部横幅」虽然文档仅一句话但实现却是一份严谨的兼容性工程通过instantStyles 动态import实现按需注入、避免首屏闪烁通过urlInclude精确限定生效范围避免影响子站页面用四层 CSS 策略隐藏容器 → 修补高度 → 清理遮罩 → 修复文字颜色同时兼容 B 站旧版顶栏、v3 顶栏、新版.bili-header与国际版首页通过body.dark 嵌套与currentColor技巧在暗色模式下保持文字与图标可读。这份组件是理解 Bilibili-Evolved“纯样式组件”编写范式的极佳范例一个看似微不足道的功能在源码层面同样遵循完整的元数据声明、懒加载注入与多版本兼容规范。读者若想实现类似的“隐藏页面元素”类功能可对照 index.ts 与 banner.scss 复刻这一模式。【免费下载链接】Bilibili-Evolved强大的哔哩哔哩增强脚本项目地址: https://gitcode.com/gh_mirrors/bi/Bilibili-Evolved创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考