# FaviconNav 

**Repository Path**: z212021/favicon-nav

## Basic Information

- **Project Name**: FaviconNav 
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-20
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FaviconNav 悬浮标签导航

一款 Firefox 浏览器扩展（WebExtensions API）：在网页上悬浮显示所有已打开的标签页，点击即切换，可自由拖拽位置、调节透明度，偏好设置本地持久化。

## 功能特性

| 功能 | 说明 |
| --- | --- |
| 悬浮标签面板 | 实时显示所有窗口中打开的标签页（标题 + 网站图标），可切换为仅图标模式 |
| 极简模式 | 只显示网址图标的纯净面板：无任何按钮控件、永不出现滚动条、高度随标签数量自适应，可拖拽右下角手柄调整宽度 |
| 一键切换标签 | 点击面板条目立即激活对应标签页并聚焦其窗口，带脉冲过渡动画 |
| 拖拽定位 | 按住面板标题栏（极简模式下按住面板任意位置）可将面板拖到页面任意位置，自动防止拖出视口 |
| 透明度调节 | 底部滑块实时调节面板不透明度，范围 30% - 100% |
| 偏好持久化 | 位置、透明度、显示模式、极简模式宽度、主题等均保存于 `storage.local`，重启浏览器后保留 |
| 更多 | 标签关闭按钮、固定标签标记、面板折叠、深色/浅色/跟随系统主题、响应式布局 |

## 安装

### 方式一：临时加载（开发/试用）

1. 打开 Firefox，地址栏输入 `about:debugging#/runtime/this-firefox`
2. 点击 **"临时载入附加组件…"**
3. 选择本仓库中的 `manifest.json`
4. 打开任意网页即可看到右上角悬浮面板

> 临时加载的扩展在浏览器重启后会被移除。

### 方式二：打包安装（长期使用）

未签名的扩展无法在正式版 Firefox 永久安装，可选择：

- **签名安装**：`npm run build` 打包后上传到 [addons.mozilla.org](https://addons.mozilla.org/developers/) 签名（可选"自行分发"获取已签名 `.xpi`）
- **开发者版 / Nightly**：在 `about:config` 将 `xpinstall.signatures.required` 设为 `false`，然后从 `about:addons` 选择"从文件安装附加组件"

## 使用说明

- **切换标签**：单击面板中的标签项（支持键盘 Enter / Space）
- **关闭标签**：悬停标签项，点击右侧 `×`
- **移动面板**：按住顶部标题栏拖拽，松开自动保存位置
- **调节透明度**：拖动底部"透明度"滑块（30% - 100%）
- **切换显示模式**：点击标题栏的模式按钮在三种模式间循环：图标+标题 → 仅图标 → 极简模式
- **极简模式**：只显示网址图标，无标题/按钮/滑块等任何控件；点击图标切换标签；按住面板任意位置拖动可移动；拖动右下角手柄调整宽度（高度随图标数量自动伸缩，永不出现滚动条）；通过工具栏弹窗或设置页可切回其他模式
- **折叠面板**：点击标题栏的箭头按钮，只保留标题栏
- **隐藏/恢复面板**：点击标题栏 `×` 隐藏；点击工具栏扩展图标，在弹窗中重新打开
- **重置位置**：工具栏弹窗或设置页中点击"重置面板位置"

## 兼容性

- Firefox 桌面版 140 及以上（覆盖最新稳定版及前两个版本）
- 已知限制：`about:` 等浏览器内置页面、`addons.mozilla.org` 因 WebExtensions 安全策略无法注入内容脚本，面板不会在这些页面显示（标签列表数据不受影响）

## 开发

```bash
npm test        # 运行单元测试（shared/utils.js，27 个用例）
npm run lint    # Mozilla 官方 web-ext lint 校验
npm run build   # 打包 zip 到 dist/
npm start       # web-ext run 启动临时 Firefox 实例调试
```

图标重新生成：`powershell -ExecutionPolicy Bypass -File tools/generate-icons.ps1`

## 文档

- [开发文档（架构与协议）](docs/DEVELOPMENT.md)
- [测试报告](docs/TESTING.md)

## 许可证

见 [LICENSE](LICENSE)。