企业官网建设流程全解析

Bilibili-Evolved 样式组件解析：隐藏视频标题层（hideVideoTopMask）的实现原理与使用指南

【免费下载链接】Bilibili-Evolved强大的哔哩哔哩增强脚本项目地址: https://gitcode.com/gh_mirrors/bi/Bilibili-Evolved

Bilibili-Evolved 是面向 B 站页面的增强脚本，其功能以"组件"形式组织，其中大量功能是纯样式类组件。本文聚焦其中的hideVideoTopMask（隐藏视频标题层）组件，讲解它解决了什么界面问题、如何在源码层面通过instantStyles注入 CSS、针对新旧两代播放器如何选择选择器，以及它只在哪些页面生效。读完本文，你既能熟练启用与验证这一功能，也能理解 Bilibili-Evolved 样式组件"元数据声明 + 按需注入"的底层工作机制。

一、功能定位：鼠标经过时右上角出现的覆盖层

该组件在 registry/lib/components/style/hide/video/top-mask/index.md 中的官方描述只有一句话：

隐藏视频里鼠标经过时出现在右上角的覆盖层.

这句描述指向的是 B 站播放器的一个交互细节：当鼠标移入播放器区域时，播放器右上角会浮现一层半透明覆盖层，用来展示视频标题、清晰度入口等信息（即"标题层"）。对追求沉浸式观看或需要录屏、截图的用户而言，这层浮层属于干扰元素，因此该组件将其整体隐藏。

在组件设置面板中，它的显示名称为"隐藏视频标题层"，组件内部标识为hideVideoTopMask，与"隐藏视频分享"（hideVideoShare）、"隐藏视频笔记"等一同归属于style/hide/video这一组"隐藏视频元素"的样式功能族。

二、组件元数据：一段不到二十行的声明

该组件的全部逻辑定义在 index.ts 中，整个文件非常精简：

import { defineComponentMetadata } from '@/components/define' import { playerUrls } from '@/core/utils/urls' const name = 'hideVideoTopMask' export const component = defineComponentMetadata({ name, displayName: '隐藏视频标题层', entry: none, instantStyles: [ { name, style: () => import('./top-mask.scss'), }, ], tags: [componentsTags.style, componentsTags.video], urlInclude: playerUrls, })

逐字段拆解这段元数据，可以看出它属于典型的"纯样式组件"：

• name/displayName：内部标识hideVideoTopMask与面向用户的显示名"隐藏视频标题层"分离，前者用于注册、配置存储与功能文档索引（见 doc/features/features.md 中的hideVideoTopMask条目及 features.json 中对应的注册数据）。
• entry: none：声明本组件没有 JavaScript 入口函数。它不需要监听事件、不需要操作 DOM，唯一职责就是注入样式，因此省去了入口逻辑。
• instantStyles：即时样式注入列表，其类型定义见 src/components/types.ts 中的instantStyles?: (DomInstantStyleDefinition | ShadowDomInstantStyleDefinition)[]。这里通过() => import('./top-mask.scss')做了动态导入，只有在该组件被启用时才会真正加载并注入对应的 SCSS 编译产物。
• tags：打上style（样式）与video（视频相关）两个分类标签，便于设置面板按标签过滤与检索。
• urlInclude：限定组件只在匹配的页面生效，此处复用 src/core/utils/urls.ts 中导出的playerUrls，详见下文。

可见，一个样式组件的"声明式骨架"由defineComponentMetadata（定义于 src/components/define.ts）统一提供，组件作者只需要描述"何时注入、注入什么"，而加载、匹配、注入的机制全部由框架承担。

三、样式实现：两条选择器对应两代播放器

实际隐藏效果由 top-mask.scss 完成，完整内容如下：

.bpx-player-top-wrap, .bilibili-player-video-top { display: none !important; }

这段规则的要点在于它同时覆盖了 B 站两代播放器的标题层容器：

• .bpx-player-top-wrap：新版播放器（bpx 内核，即 B 站逐步推广的播放器体系）中位于顶部的包裹容器，鼠标悬停时承载标题等浮层内容。
• .bilibili-player-video-top：旧版播放器（bilibili-player体系）中对应的顶部浮层容器。

之所以必须写成两条并列选择器而非只针对其中之一，是因为不同版本、不同页面形态下 B 站播放器 DOM 结构并不一致；两条规则同时生效，才能保证无论命中新旧哪一代播放器，浮层都能被隐藏。display: none !important则确保不会被页面自身的样式规则覆盖，达到强制隐藏的目的。

从实现方式看，这正体现了 Bilibili-Evolved 中"样式组件 = 零 JS 逻辑 + 纯 CSS 注入"的典型模式：不依赖任何运行时逻辑，只要页面结构包含上述任一选择器，注入的样式就会立即生效，性能开销极小。

四、生效范围：playerUrls 到底覆盖哪些页面

urlInclude: playerUrls是决定"该样式在哪些页面注入"的关键。playerUrls定义于 src/core/utils/urls.ts：

export const playerUrls = [ '//player.bilibili.com', '//www.bilibili.com/html/player.html', ...videoUrls, ...bangumiUrls, ...cheeseUrls, ]

展开后，它聚合了四类 URL 模式：

也就是说，只要页面 URL 命中上述任一模式（视频、番剧、课堂或独立播放器页面），组件匹配逻辑就会认为"当前页含播放器"，并在满足启用条件时注入隐藏标题层的样式；而在首页、动态、专栏等其他页面则不会注入，避免无谓的样式干扰。匹配机制由 src/core/utils/urls.ts 中的matchCurrentPage等工具统一处理，playerUrls本身也被多个视频相关组件复用。

五、使用方式与效果验证

该组件随 Bilibili-Evolved 脚本一起分发，无需单独安装。启用步骤为：

1. 打开 B 站任意视频、番剧或课堂页面，呼出 Bilibili-Evolved 的设置面板；
2. 在"样式"分类（对应组件标签style，且可结合video标签过滤）下找到"隐藏视频标题层"；
3. 打开该组件开关，样式会即时注入并立即生效，无需刷新页面。

验证生效与否非常直观：进入任意视频播放页，将鼠标移入播放器区域，原本应出现在右上角的标题浮层将不再显示。若想确认样式确实被注入，可以打开浏览器开发者工具，检查页面<style>中是否包含.bpx-player-top-wrap/.bilibili-player-video-top的display: none !important规则。

该组件同样被收录进功能打包清单（见 pack.json 中的hideVideoTopMask条目），这意味着它与其他组件一样，可以通过 Bilibili-Evolved 的打包机制随脚本整体发布；功能注册信息也可在 features.md 与 features.json 中交叉检索，便于开发者了解组件在功能体系中的位置。

六、小结

hideVideoTopMask是一个体量极小但机制完整的样式组件范例：一行文档描述、一份元数据声明、一段双选择器 CSS，就完成了"跨新旧播放器隐藏右上角覆盖层"的目标。从它身上可以清晰看到 Bilibili-Evolved 组件体系的设计取向——用defineComponentMetadata统一描述组件能力，用instantStyles实现按需懒加载样式，用urlInclude精确划定生效页面，让"纯样式功能"也能以统一、可配置、可打包的方式融入整个脚本生态。对于想为 Bilibili-Evolved 贡献类似样式功能的开发者而言，hide/video/top-mask目录（index.ts + top-mask.scss）就是一份可以直接参考的最小模板。

【免费下载链接】Bilibili-Evolved强大的哔哩哔哩增强脚本项目地址: https://gitcode.com/gh_mirrors/bi/Bilibili-Evolved