Bilibili-EvolvedCSS变量命名约定：BEM与命名空间
【免费下载链接】Bilibili-Evolved 强大的哔哩哔哩增强脚本 项目地址: https://gitcode.***/gh_mirrors/bi/Bilibili-Evolved
在现代前端开发中，CSS变量（Custom Properties）的命名规范直接影响代码的可维护性和团队协作效率。Bilibili-Evolved作为一款功能强大的哔哩哔哩增强脚本，其CSS架构采用了BEM（Block-Element-Modifier）命名规范与命名空间相结合的设计模式，确保样式代码的模块化和可扩展性。本文将深入解析这一命名体系的具体实现和应用场景。
命名空间设计：功能模块的边界划分
Bilibili-Evolved的CSS变量系统首先通过命名空间前缀实现功能模块的隔离。核心命名空间包括：
-
--be-：全局通用变量（Bilibili-Evolved缩写） -
--ui-：UI组件专用变量 -
--video-：视频播放器相关变量 -
--danmaku-：弹幕系统样式变量
这种划分方式在源码中有着明确体现，例如在src/ui/_***mon.scss中定义的基础交互变量：
:root {
--be-transition-speed: 0.2s;
--be-ease-function: ease-in-out;
--ui-border-radius: 4px;
--video-control-height: 48px;
}
命名空间冲突解决方案
当多个功能模块存在样式交叉时，Bilibili-Evolved采用双命名空间叠加策略。以直播模块为例，在src/***ponents/live/live-control-bar.ts中可以看到：
// 为直播控件注入复合样式变量
const styleVars = {
'--live-video-be-control-height': 'var(--video-control-height)',
'--live-ui-border-radius': 'var(--ui-border-radius)'
};
BEM命名规范的CSS变量实践
Bilibili-Evolved将BEM规范创新性地应用于CSS变量命名，形成了--namespace-block__element--modifier的四级结构。这种命名方式在src/ui/_effects.scss中尤为典型：
// Block: toast (提示框)
// Element: container (容器)
// Modifier: error (错误状态)
--ui-toast__container--error-bg: #ff4d4f;
--ui-toast__container--su***ess-bg: #52c41a;
// Block: button
// Element: text
// Modifier: primary/large
--ui-button__text--primary-color: #fff;
--ui-button__text--large-size: 16px;
变量命名与DOM结构的映射关系
BEM变量命名与组件DOM结构保持高度一致，以下是src/***ponents/settings-panel/SettingsPanel.vue中的对应关系示例：
<template>
<div class="settings-panel"> <!-- Block -->
<div class="settings-panel__header"> <!-- Element -->
<h2 class="settings-panel__title--main">设置面板</h2> <!-- Modifier -->
</div>
</div>
</template>
<style scoped>
:root {
--ui-settings-panel__header-height: 56px;
--ui-settings-panel__title--main-size: 18px;
}
</style>
响应式变量与主题系统
Bilibili-Evolved通过变量修饰符实现响应式设计和主题切换，在src/core/theme-color/index.ts中定义了主题变量的动态切换逻辑：
// 根据系统主题自动切换变量值
export function setupThemeVariables(isDarkMode: boolean) {
const root = document.documentElement;
root.style.setProperty('--be-background', isDarkMode ? '#18191c' : '#f4f4f4');
root.style.setProperty('--be-text-color', isDarkMode ? '#fff' : '#18191c');
}
多主题变量定义
在src/ui/_tabs.scss中可以看到完整的主题变量集：
// 浅色主题
--ui-tabs__indicator-color: #fb7299;
--ui-tabs__text--active-color: #fb7299;
// 深色主题
--ui-tabs__indicator-color--dark: #ff85ad;
--ui-tabs__text--active-color--dark: #ff85ad;
实战应用：变量命名的最佳实践
1. 变量命名的层级关系
正确的变量层级应遵循"业务功能 > 视觉表现"的原则，例如src/***ponents/video/video-control-bar.ts中的音量控制变量：
// 推荐：明确业务功能和元素关系
const volumeVars = {
'--video-control__volume--hover-width': '120px',
'--video-control__volume--muted-opacity': '0.7'
};
// 避免：仅描述视觉表现的命名
const badExample = {
'--wide-slider-width': '120px',
'--faded-icon-opacity': '0.7'
};
2. 变量复用与扩展
在src/***ponents/utils/categories/raw.json中定义的分类数据，通过CSS变量与样式系统关联：
{
"categories": [
{
"id": "anime",
"name": "动画",
"colorVar": "--category-anime-color"
}
]
}
对应的样式定义在src/ui/_markdown.scss：
:root {
--category-anime-color: #fb7299;
--category-game-color: #7289da;
}
命名规范的工具链支持
Bilibili-Evolved通过ESLint插件eslint-plugin-css-variables中配置了自定义规则：
module.exports = {
rules: {
'css-variables/naming-convention': [
'error',
{
pattern: '--[a-z]+(-[a-z]+)*(__([a-z]+(-[a-z]+)*))*(--([a-z]+(-[a-z]+)*))?',
message: 'CSS变量必须遵循BEM命名规范: --namespace-block__element--modifier'
}
]
}
};
这一配置确保所有新增的CSS变量都符合项目的命名约定，降低了人工审查成本。
总结与扩展阅读
Bilibili-Evolved的CSS变量命名体系通过命名空间隔离和BEM结构化命名，成功解决了大型前端项目中的样式冲突和维护难题。这种模式特别适合用户脚本类项目，既能保证与宿主页面的样式隔离，又能实现内部样式的高度复用。
深入了解相关实现：
- 设计规范文档：doc/features/features.md
- 组件样式源码：src/ui/
- 主题系统实现：src/core/theme-color/index.ts
通过这套命名规范，Bilibili-Evolved实现了样式代码的"一次定义，多处复用"，为后续功能扩展和主题定制奠定了坚实基础。
【免费下载链接】Bilibili-Evolved 强大的哔哩哔哩增强脚本 项目地址: https://gitcode.***/gh_mirrors/bi/Bilibili-Evolved
