BewlyBewly项目新页面适配开发指南

项目背景与适配意义

BewlyBewly是一个浏览器插件项目，主要功能是为特定网站提供主题定制和界面优化。在实际开发过程中，经常需要为新的页面路径添加适配支持，这涉及到多个技术环节的协同工作。

适配流程详解

1. 基础环境配置

开发者首先需要按照项目贡献文档完成开发环境搭建，包括Node.js环境、pnpm包管理器以及必要的依赖安装。

2. 页面URL匹配配置

在manifest.ts文件中，需要添加新页面的URL匹配规则。这里需要注意使用通配符(*)来适配不同的协议(http/https)和子域名，例如将具体URL转换为通用匹配模式。

3. 页面支持检测

在src/contentScripts/index.ts文件中，需要扩展isSupportedPages函数，添加对新页面的检测逻辑。这里使用正则表达式来匹配目标URL，建议添加清晰的注释说明适配的页面类型。

4. 样式文件创建与管理

在src/styles/adaptedStyles/pages目录下创建新的SCSS样式文件，采用驼峰命名法。然后在index.ts文件的setupStyles函数中添加对应的URL匹配逻辑和样式文件引用。

5. 样式编写规范

样式文件需要遵循特定的结构：

1. 固定修改区域：处理必须的布局调整，如隐藏特定元素
2. 主题颜色适配部分：使用CSS变量实现主题色适配
3. 深色模式特有样式：针对暗黑模式的特殊处理

颜色值必须使用项目定义的CSS变量(variables.scss)，禁止直接使用硬编码颜色值。

开发注意事项

1. 样式适配应专注于颜色和主题适配，避免过度"美化"或修改原有布局
2. 顶部导航栏的处理应统一在index.ts中完成，不建议在样式文件中单独处理
3. 使用VSCode的region标记(#region/#endregion)实现代码块折叠，提高可维护性
4. 开发过程中建议频繁使用pnpm dev命令测试，及早发现问题
5. 适配新页面前建议先进行讨论，评估维护成本

最佳实践建议

1. 保持样式最小化原则，只做必要的适配修改
2. 注释清晰明确，说明每个适配区块的作用
3. 遵循项目统一的命名规范和代码风格
4. 考虑不同主题模式下的显示效果
5. 测试时要覆盖各种可能的页面状态和用户场景

通过遵循这些指导原则，开发者可以高效地为BewlyBewly项目添加新页面支持，同时确保代码的可维护性和一致性。