GitZip Pro 源码解析：一个 GitHub 文件/文件夹下载扩展是如何工作的（二）GitHub 页面注入与文件选择

项目地址：fthux/GitZipPro。这一篇基于 GitZip Pro 的开源源码，继续分析它如何增强 GitHub 文件列表页面。

上一篇从manifest.json看了 GitZip Pro 的整体装配关系。这一篇进入第一个真正的业务入口：source/content.js。

content.js的职责可以概括成一句话：在 GitHub 仓库文件页里找到文件列表，给每一行加上可选择能力，再把用户选中的文件或文件夹交给下载器。

它不直接生成 zip，也不直接保存下载历史。它更像一个页面适配层，负责把 GitHub 原本的文件浏览界面改造成 GitZip Pro 可以操作的下载界面。

注入入口

content.js不是用户主动打开的页面，而是由manifest.json注入到 GitHub 页面：

"content_scripts":[{"matches":["https://github.com/*"],"js":["constants.js","i18n.js","jszip.min.js","downloader.js","content.js"],"css":["content.css"],"run_at":"document_idle"}]

这里的顺序决定了content.js可以直接使用几个前置能力：GZP_CONSTANTS提供配置，GZP_I18N提供翻译，JSZip提供压缩能力，window.GZPDownloader提供下载入口。也就是说，content.js并不是孤立脚本，它是在前面几个模块准备完成后，最后接管 GitHub 页面交互。

页面注入总流程

这条链路可以帮助我们把content.js里的函数分成几类：页面识别函数、DOM 查询函数、行增强函数、按钮函数、导航监听函数和设置应用函数。

判断当前页面是否可处理

GitHub 页面很多，仓库首页、issues、pull requests、actions、releases 都在github.com下。GitZip Pro 只应该在仓库文件列表页工作，所以第一步是判断页面类型。

isRepoFilePage()的作用就是做这个过滤。它会根据当前location.pathname判断路径是否像仓库文件页。典型路径包括：

/{owner}/{repo} /{owner}/{repo}/tree/{branch} /{owner}/{repo}/tree/{branch}/{path}

而 issues、pull、wiki、settings、actions 等页面不属于文件列表页，不应该注入选择框和下载按钮。

这种判断很重要。content script 虽然会在所有https://github.com/*页面加载，但加载不等于每个页面都要执行增强逻辑。先判断页面类型，可以避免对非仓库文件页造成 DOM 干扰。

查找 GitHub 文件列表行

页面确认之后，下一步是找到 GitHub 的文件/目录行。对应函数是getFileRows()。

GitHub 的前端 DOM 并不是固定不变的，项目中并没有只依赖一个选择器，而是为不同结构准备了多种匹配方式。content.js里还有getTargetCell(row)这样的辅助函数，用来找到每一行里最适合插入复选框的单元格。

这种写法说明content.js面对的不是一个由自己完全控制的页面，而是 GitHub 官方页面。扩展只能“贴”在别人已有的 DOM 上，因此需要兼容不同页面结构、响应式布局以及 GitHub 后续可能调整过的 class。

从一行中提取路径

行被找到之后，还需要知道这一行对应哪个文件或文件夹。这个工作由getPathFromRow(row)完成。

GitHub 文件列表中的链接通常包含/tree/或/blob/：

/owner/repo/tree/main/src /owner/repo/blob/main/README.md

tree代表目录，blob代表文件。content.js在页面层不需要完整解析 owner、repo、branch、path，它只要把 href 收集起来即可。真正的结构化解析会交给downloader.js的parseGitHubUrl()。

这也是一个明显的分层：页面层只收集 GitHub 链接，下载层再把链接解析成下载任务。

给文件行插入复选框

核心增强逻辑在attachRowBehavior(row)和createCheckbox(row)。

attachRowBehavior(row)会先判断这一行是否已经初始化过：

if(row.classList.contains('gzp-row-initialized'))return;

这是为了避免重复插入。GitHub 页面会因为导航、局部刷新、滚动等原因反复触发 DOM 处理，如果没有这个标记，同一行可能被插入多个复选框。

接着它会跳过父目录行，也就是..或 “Go to parent directory” 这种返回上一级的行。因为这类行不是实际下载目标，不应该出现在选择列表里。

真正创建复选框的是createCheckbox(row)。它会创建一个span.gzp-cb-wrapper包裹input.gzp-checkbox。当复选框状态变化时，代码会更新一个核心状态：

selectedItems.set(row,getPathFromRow(row));

如果取消选择，则从selectedItems中删除。这里的selectedItems是Map，key 是当前 DOM 行，value 是对应的 GitHub href。这个结构同时保留了页面元素和下载路径，后续既可以更新 UI，也可以把路径传给下载器。

双击选择与选中态

除了直接点击复选框，attachRowBehavior(row)还支持双击选择。它通过记录lastClickTime判断两次点击是否发生在 500ms 内。如果设置项doubleClickSelect开启，就切换复选框状态，并主动派发change事件，让状态更新逻辑复用复选框的处理流程。

选中后，行会添加样式类：

row.classList.add('gzp-row--selected');

取消后再移除。视觉样式由content.css负责，这样 JS 只控制状态，具体呈现交给 CSS。

浮动下载按钮

当用户选择了至少一个文件或目录，页面需要出现下载按钮。这部分由ensureDownloadButton()和updateDownloadButton()负责。

updateDownloadButton()会读取selectedItems.size。如果数量大于 0，就显示按钮并更新 badge；如果数量为 0，并且按钮处于 idle 状态，就隐藏按钮。

点击下载按钮时，content.js会调用：

window.GZPDownloader.start(selectedItems,callbacks)

注意这里传进去的不是数组，而是前面维护的Map。下载器会遍历其中的 href，逐个解析成 GitHub 下载任务。

右键菜单信息同步

content.js中还有setupRowContextMenu(row)。当用户在某一行上右键时，它会读取这一行的 href 和展示名称，然后向 background 发送消息：

chrome.runtime.sendMessage({type:'GZP_UPDATE_CONTEXT_MENU',href,itemName});

background 收到后会更新右键菜单标题。这样浏览器右键菜单里的“下载当前项目”就能知道用户刚刚右键的是哪一个文件或文件夹。

适配 GitHub 的 SPA 导航

GitHub 页面不是传统的每次导航都完整刷新。仓库内部切换目录时，页面可能发生局部更新。content.js里有interceptLinkClicks()、onNavigate()、attachAllRows()等函数，用来在导航后重新扫描文件行、清理旧状态并重新注入 UI。

可以把这一层理解为 GitHub 页面适配器：

如果没有这层处理，扩展可能只在首次打开页面时有效，进入子目录后就失效。

本篇小结

content.js是 GitZip Pro 的页面入口。它的核心工作不是下载，而是把 GitHub 文件列表改造成一个可交互的选择界面。

这一篇可以得到一条清晰的源码主线：

init() -> loadSettings() -> isRepoFilePage() -> getFileRows() -> attachRowBehavior(row) -> createCheckbox(row) -> updateDownloadButton() -> GZPDownloader.start(selectedItems)

下一篇进入downloader.js的前半部分，看 GitZip Pro 如何把页面中收集到的 GitHub 链接解析成 owner、repo、branch、path，并通过 GitHub API 请求文件和目录数据。

完整源码见 fthux/GitZipPro。如果这篇对你理解浏览器扩展 content script 有帮助，也欢迎给 GitZip Pro 一个 Star。

如果你也好奇这个 Pro 版为什么会做起来，可以接着看这篇项目缘起：用了 GitZip 这么多年，我动手做了一个「Pro」版。