企业官网建设流程全解析

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负责把组件注册进 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 编译产物。这类样式会在 DOMContentLoaded（DCL）之前尽快注入，避免页面首屏出现“先显示横幅、后被隐藏”的闪烁。
• tags: [componentsTags.style]：将组件归类到「样式」标签下，便于在设置面板中按类别筛选（与always-show-duration、dark-mode等样式组件同属一类）。
• urlInclude: mainSiteUrls：生效的 URL 范围。mainSiteUrls定义于 src/core/utils/urls.ts：

export 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-layer：Bilibili-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相关的还有两个值得一提的协作点：

1. 自定义顶栏联动：若用户同时启用 custom-navbar 组件，banner.scss 中的.custom-navbar .blur-layer规则会主动隐藏自定义顶栏的模糊背景层，保证视觉效果统一；
2. 与 dark-mode 的协作：通过body.dark &嵌套选择器（SCSS 语法），组件在 Bilibili-Evolved 暗色模式开启时自动切换文字颜色，无需额外配置，体现了样式组件之间通过全局body.dark类协同工作的约定。

五、使用与配置

该组件作为 Bilibili-Evolved 的内置/在线仓库组件，无需修改仓库即可使用：

1. 安装并打开 Bilibili-Evolved 的设置面板；
2. 在「样式」分类（tags中的style标签）下找到「隐藏顶部横幅」组件（hideBanner）；
3. 开启开关后，组件会通过instantStyles机制立即注入banner.scss编译产物，横幅即刻消失；
4. 关闭开关时，框架会依据样式 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