227 lines
14 KiB
Markdown
227 lines
14 KiB
Markdown
# 云仓视频溯源 · 单号注入扩展
|
||
|
||
Chrome / Edge 扩展(**Manifest V3 + 原生 JS,零构建**)。
|
||
|
||
它注入到**第三方 WMS / 后台页面**里,按规则找到「运单号」这类字段,在它**旁边**渲染一个
|
||
「▶ 查看打包视频」按钮(宿主元素一个字都不改);点击按钮打开溯源页面,把编号作为关键词带过去。
|
||
|
||
> 首个取样站点:`https://wms.wms.gztbyc.com/order/orderManagement`
|
||
> 运单号长这样:
|
||
> ```html
|
||
> <span class="click-copy-link" role="button" tabindex="0"
|
||
> title="点击复制并查看快递单号二维码">321408064481776</span>
|
||
> ```
|
||
> 扩展会在它后面插一个按钮(插在 `+1` 展开按钮之前):
|
||
> ```html
|
||
> <span class="click-copy-link" …>321408064481776</span>
|
||
> <button class="pst-trace-mark pst-trace-btn" data-pst-code="321408064481776"
|
||
> data-pst-url="https://www.baidu.com/?keyword=321408064481776">查看打包视频</button>
|
||
> ```
|
||
> 点按钮 → 小窗打开 `https://www.baidu.com/?keyword=321408064481776`。
|
||
> 原来的运单号仍保留 WMS 自带的「点击复制二维码」行为。
|
||
|
||
---
|
||
|
||
## 1. 安装
|
||
|
||
1. 打开 `chrome://extensions`(Edge 是 `edge://extensions`)。
|
||
2. 右上角打开 **开发者模式**。
|
||
3. 点 **加载已解压的扩展程序**,选择本目录 `extension/`。
|
||
4. 刷新一下已经打开的 WMS 页面(扩展只对**安装之后**加载的页面生效)。
|
||
|
||
图标缺失时重新生成:`powershell -ExecutionPolicy Bypass -File tools\make-icons.ps1`
|
||
|
||
## 2. 目录结构
|
||
|
||
```
|
||
extension/
|
||
├── manifest.json # MV3 声明;权限只有 "storage"
|
||
├── icons/ # 16/32/48/128,由 tools/make-icons.ps1 生成
|
||
├── src/
|
||
│ ├── lib/rules.js # ★ 规则引擎(配置归一化 / 正则编译 / DOM 加工 / 地址拼接)
|
||
│ ├── content.js # 注入脚本:扫描 + 加工 + 点击拦截 + MutationObserver 补标
|
||
│ ├── content.css # 注入样式(全部 .pst- 前缀 + !important)
|
||
│ ├── background.js # service worker:只负责把算好的地址打开(小窗 / 新标签页)
|
||
│ ├── popup.html/.css/.js # 工具栏弹窗:开关、本页命中清单、重新扫描
|
||
│ └── options.html/.css/.js # ★ 规则配置页:基本设置 / 规则编辑 / 试跑 / 导入导出
|
||
├── test/wms-mock.html # 自测页:按真实结构复刻的表格
|
||
└── tools/make-icons.ps1 # 生成图标(纯 ASCII,见文件头说明)
|
||
```
|
||
|
||
**没有构建步骤**:`rules.js` 挂在 `globalThis.PSTRules` 上,content script / popup / options 各自
|
||
用 `<script src>` 或 `manifest.content_scripts.js` 按顺序加载它。改完代码在 `chrome://extensions` 点一下
|
||
刷新即可(改 `manifest.json` 才需要重装)。
|
||
|
||
## 3. 匹配方式 × 加工方式
|
||
|
||
**匹配(怎么找)**
|
||
|
||
| 方式 | 适用 | 关键字段 |
|
||
| --- | --- | --- |
|
||
| **CSS 选择器** | 元素本身好定位,**或编号在属性里** | `selector` + `attr`(空 = 取元素文本)+ 可选 `pattern` |
|
||
| **文本正则** | 页面结构会变、但有稳定的编号格式(`YT1234…`) | `pattern` + `flags`(必填,可用 `exclude` 排除) |
|
||
|
||
- `pattern` 的**第 1 个捕获组**会被当成编号(`{code}` 的值);没写捕获组就用整个匹配。
|
||
- 选择器模式下 `pattern` 是**可选**的:填了就从「`attr` 取到的值 / 元素文本」里**再抽一次**编号。
|
||
- ⚠️ **属性里的值只能用选择器模式**:文本正则只遍历文本节点,拿不到属性值。
|
||
|
||
### 例:编号藏在 `javascript:` 链接里
|
||
|
||
```html
|
||
<a href="javascript:MM_openTrace('../system/view-trace!viewTrace.jspb?postNum=202610101621&wareHouseId=5400')">
|
||
202610101621
|
||
</a>
|
||
```
|
||
|
||
这条的编号既在链接文字里、也在 `href` 的 `postNum=` 参数里。两种写法都行:
|
||
|
||
| 写法 | selector | attr | pattern | 说明 |
|
||
| --- | --- | --- | --- | --- |
|
||
| **从属性抽(推荐)** | `a[href*="postNum="]` | `href` | `postNum=([0-9A-Za-z_-]+)` | 不依赖链接文字,文字被改成「查看轨迹」也照样能取到编号 |
|
||
| 取链接文字 | `a[href*="postNum="]` | *(空)* | *(空)* | 简单;引擎会对取到的文本 `trim()`,那一大串换行/制表符会被去掉 |
|
||
|
||
内置示例规则不再默认带着这种结构(2026-10-17 已移除);真要处理 旧版 JSP 轨迹链接,在配置页自己加一条规则(下表两种写法都行)。
|
||
因为是 `button` 加工方式,按钮插在 `<a>` **之后**,`<a>` 自己那个 `javascript:MM_openTrace(...)` 照旧能用。
|
||
|
||
**加工(找到之后干什么)**
|
||
|
||
| 方式 | 行为 | 适合 |
|
||
| --- | --- | --- |
|
||
| **`button`(默认)** | 命中元素**一个字都不改**,只在它旁边插一个「查看打包视频」兄弟按钮 | 元素本身有自己的点击行为(比如「点击复制二维码」),不能抢 |
|
||
| **`chip`** | 命中元素**自己**变成可点(加类名 / 改写 `title` / 接管点击);可配下划线 / 高亮 / 胶囊 + ▶ 角标 | 命中处本来只是普通文字 |
|
||
|
||
- `button` 方式是**零侵入**的:
|
||
- 不加类名、不改 `title`、不动 `role` / `tabindex`、**不接管它的点击** → 页面原有的行为完全不受影响;
|
||
- 只往宿主元素上写 `data-pst-code` / `data-pst-rule` 两个属性当「已处理」记号
|
||
(`data-*` 对事件和渲染没有任何影响),撤销时一并摘掉;
|
||
- 按钮插在命中元素之后;若命中元素在 `<a>` 里,则退到那个 `<a>` 之后
|
||
—— `<button>` 嵌进 `<a>` 是非法嵌套。
|
||
- `chip` 方式下点击会被脚本在捕获阶段拦掉(`preventDefault + stopImmediatePropagation`),
|
||
所以**原元素自己的点击不会再触发**;想用原功能就按住修饰键点(见「行为约定」)。
|
||
- `text` 正则 + `button`:因为要把按钮放到「命中位置的旁边」,必须包一层**纯定位**的
|
||
`<span class="pst-trace-anchor">`(无任何视觉、不带可点类名、不拦点击);它是原文照抄的,
|
||
所以被匹配到的那段文字没变。
|
||
- 按钮文案在**基本设置**里配(默认「查看打包视频」);全局和单条规则都能设 `actionMode`,规则留空则跟随全局。
|
||
- 提醒:按钮是真实 DOM,所以**容器元素的 `textContent` 会多出按钮文案** —— 这是插入 UI 的必然结果,
|
||
被匹配的那段文字本身没有被改动。
|
||
|
||
### 内置规则
|
||
|
||
**只内置一条**(实测这一条就能盖住真实页面的单号):
|
||
|
||
| id | 说明 | 生效站点 | 默认 |
|
||
| --- | --- | --- | --- |
|
||
| `express` | 文本规则 `\b(?:YT\|SF\|JD\|ZTO\|YTO\|STO\|EMS\|DBL\|32\|77)\d{10,16}\b`(`gi`) | 全部 | 开 |
|
||
|
||
- **前缀表就是唯一要维护的地方**:在 `src/lib/rules.js` 的 `EXPRESS_PREFIXES` 里往数组里追加新前缀即可
|
||
(以前没出现过、又确实出现在单号开头的就加进去)—— 正则会跟着拼出来,**不用改正则本身**:
|
||
```js
|
||
const EXPRESS_PREFIXES = [ 'YT', 'SF', 'JD', 'ZTO', 'YTO', 'STO', 'EMS', 'DBL', '32', '77' ];
|
||
const EXPRESS_PATTERN = '\\b(?:' + EXPRESS_PREFIXES.join('|') + ')\\d{10,16}\\b';
|
||
```
|
||
- 前缀后面必须跟 **10~16 位数字**(`\d{10,16}`):所以 `321408064481776`(WMS 运单号,`32` 开头)会被命中,
|
||
而同一行的波次号 `E2026101600069`、发货单号 `JY2026101619599`、平台交易单号、17 开头的毫秒时间戳都不会;
|
||
- ⚠️ **数字前缀(`32` / `77`)最容易被内部 ID、订单号一起点亮** —— 发现误标就把那个前缀拿掉,或者给规则加 `exclude`;
|
||
- 其它匹配方式(CSS 选择器 / 从 `href` 抽编号 / 按 `data-*` 取值)**不再内置示例**,需要时在配置页自己加一条即可,写法见上面的例子;
|
||
- **升级迁移(config version 1 → 2)**:扩展升级后第一次打开配置页/页面时,会
|
||
① 把已移除的示例规则(`wms-waybill` / `numeric` / `legacy-postnum` / `dom-attr`)从你的规则里剔掉,
|
||
② 内置的 `express` 如果还是老正则(说明你没改过它)就换成带新前缀表的正则 ——
|
||
**你自己加的规则、以及你改过的 `express` 都不动**(见 `upgradeRules()`)。
|
||
|
||
## 4. 目标地址模板
|
||
|
||
在**基本设置**里改一处即可切到真实打包视频页,占位符:
|
||
|
||
| 占位符 | 含义 |
|
||
| --- | --- |
|
||
| `{code}` | 提取到的编号,**URL 编码**后填入 |
|
||
| `{rawcode}` | 同上但不编码 |
|
||
| `{host}` | 当前站点 host |
|
||
|
||
```
|
||
默认:https://www.baidu.com/?keyword={code}
|
||
将来:https://video.example.com/trace?keyword={code}&from=wms
|
||
```
|
||
|
||
单条规则还可以设**专属地址**(留空则用全局模板)。点击后按「打开方式」呈现:
|
||
**独立小窗**(默认)或**新标签页**。
|
||
|
||
## 5. 调规则:别刷页面,用「试跑」
|
||
|
||
配置页里的 **规则试跑** 用的是**当前表单里还没保存**的规则,所以可以边调边看:
|
||
|
||
- 输入类型选 `HTML 片段`,粘一段真实 DOM,点「试跑」;
|
||
- 它会模拟一个站点(默认 `wms.wms.gztbyc.com`,用于校验规则的「生效站点」),
|
||
列出**命中的编号 + 最终目标地址**,并给出**二次加工后的 HTML**;
|
||
- 0 命中时会把每条启用规则的「生效站点 / 选择器 / 正则」列出来,方便判断是**站点被过滤了**还是**没匹配上**;
|
||
- 点「填入 WMS 取样」可以一键载入内置样例。
|
||
|
||
工具栏弹窗则用来确认**线上是否真的生效**:显示「本页命中 N」+ 编号清单(点一条可直接打开)。
|
||
|
||
## 6. 自测页
|
||
|
||
```powershell
|
||
# 任选一种方式打开 test/wms-mock.html
|
||
npx --yes http-server extension/test -p 7310 # → http://127.0.0.1:7310/wms-mock.html
|
||
```
|
||
(也可以直接双击打开 `file://`,但要在扩展详情里额外开启「允许访问文件网址」。)
|
||
|
||
预期:表格里 **3 个运单号**旁边各多一个「▶ 查看打包视频」按钮(插在运单号和 `+1` 之间),
|
||
其余 9 个蓝色文本不受影响;页面底部那行 `SF1234567890123` 也会被文本正则命中并插按钮。
|
||
|
||
## 7. 行为约定
|
||
|
||
- **默认(button)模式下完全不碰宿主元素**:命中元素的点击、样式、`title` 全部原样,
|
||
只有我们自己新插的那个按钮会响应点击。
|
||
- **chip 模式下**点击拦截在捕获阶段完成(`preventDefault + stopImmediatePropagation`),
|
||
不会触发宿主页的委托逻辑,也不会让外层 `<a>` 跳走;此时可以用修饰键放行 ——
|
||
按住 <kbd>Ctrl</kbd> / <kbd>⌘</kbd> / <kbd>Alt</kbd> / <kbd>Shift</kbd> 点击就不拦,交还给页面原本的行为。
|
||
- **SPA 友好**:`MutationObserver`(默认 400ms 防抖)盯着新增节点和文本变化自动补标;
|
||
自己也写了 DOM 会触发观察器,用 `quietUntil` 时间窗把这类回声挡掉,避免无限重扫。
|
||
- **完整可撤销**:关掉总开关、改规则、或当前站点不在生效范围时会 `unmark()`——
|
||
wrap 模式把 `<span>` 换回纯文本,selector 模式把类名 / `data-pst-*` / 被覆盖的 `title` / 加过的 `tabindex` 全部还原。
|
||
- **上限保护**:单次扫描最多看 `maxNodes`(默认 5000)个文本节点、单页最多标 `maxMarks`(默认 400)处,
|
||
超了会截断并在弹窗里显示 `N+`。
|
||
|
||
## 8. 权限与安全
|
||
|
||
| 权限 | 用途 |
|
||
| --- | --- |
|
||
| `storage` | 存规则配置(优先 `storage.sync`,超 8KB 单项配额自动退到 `storage.local` 并提示) |
|
||
| content script `matches: http(s)://*/*` | 需要注入任意第三方系统,无法预先枚举域名 |
|
||
|
||
- 不请求 `tabs` / `scripting` / `cookies`,**不读页面 cookie,不发任何请求**:
|
||
点击只是把算好的 URL 交给 `chrome.tabs.create` / `chrome.windows.create`。
|
||
- 注入走隔离世界(ISOLATED),不注入页面上下文,不受宿主页 CSP 影响。
|
||
- 想收窄范围:改 `manifest.json` 里 `content_scripts[0].matches` 为具体域名(如 `https://wms.wms.gztbyc.com/*`),
|
||
重新加载扩展即可;规则层面的范围由「生效站点」控制。
|
||
- 页面上不想要的可加 `data-pst-skip` 属性(能改页面时),引擎会整棵子树跳过。
|
||
|
||
## 9. 踩过的坑(都已修,改代码时注意)
|
||
|
||
- **`border-color` 不能放进 `transition`**:`border-bottom-color` 未指定时计算值是 `currentColor`
|
||
(宿主页链接色,实测 `#409eff`),一旦参与过渡,标记出来的**第一帧**是不确定的宿主色
|
||
——每标一处都闪一下蓝。实测 `0ms = rgb(64,158,255)` → `150ms = rgb(14,165,164)`,去掉后立即正确。
|
||
- **`tools/make-icons.ps1` 必须保持纯 ASCII**:PowerShell 5.1 在中文机器上把**无 BOM** 的 `.ps1`
|
||
按 GBK 读,UTF-8 中文变乱码;乱码落进 `("{0}" -f $x)` 这类格式串里会直接报
|
||
`Input string was not in a correct format` 而中断脚本。
|
||
- **`acceptTextNode` 的「已处理」判断必须看 `data-pst-code`,不能只看类名**:button 模式不给宿主元素加类名,
|
||
只看类名会让 text 正则规则把同一个编号再包一遍,插出第二个按钮。
|
||
- **button 模式要能跨重扫去重**:`applyMarks` 只处理「还没标过」的节点,而 button 模式的宿主元素**永远不带 markClass**,
|
||
每轮增量重扫都会重新命中它 → 靠 `data-pst-code` 记号 + `existingButton()`(看 `nextElementSibling`)两道保险,
|
||
实测连续 `applyMarks` 5 次仍然是 3 个按钮。
|
||
- **命中数不能只看 `applyMarks` 的返回值**:它只处理「还没标过的」节点,滚动/翻页是增量补标,
|
||
返回值只是本轮新增。所以 `status` 里的清单是**直接数 DOM 上的 `.pst-trace-mark`**(`collectItems`)。
|
||
- **`chrome.tabs.sendMessage` 要指定 `frameId: 0`**:页面里多个 iframe 都注入过脚本,
|
||
不定帧会拿到不确定的那个回复。
|
||
- **`unmark` 的账要记清**:`tabindex` / `title` 可能本来就是页面自己的,只有我们记过账
|
||
(`data-pst-tab` / `data-pst-title`)的才还原。
|
||
- nunjucks 无关但同类教训:**新加的类名前缀统一用 `pst-`**,避免和宿主页或本项目其它样式撞名。
|
||
|
||
## 10. 下一步(还没做)
|
||
|
||
- 把目标地址换成真实的打包视频页(后端需要提供 `GET /api/.../trace?keyword=<运单号>` 之类的接口)。
|
||
- 需要「先查有没有视频、再决定是否标记」时,把 `content.js` 的 `runScan()` 前接一次
|
||
`fetch`(要加对应域名的 `host_permissions`),或改成点击时才查。
|
||
- 一次报多张运单(`+1` 那个展开按钮)目前只取折叠时显示的第一个编号。
|