{"_id":"@plannotator/web-highlighter","_rev":"2-277631c7136ca971929b163bdaeb2a3a","name":"@plannotator/web-highlighter","dist-tags":{"latest":"0.8.1"},"versions":{"0.8.0":{"name":"@plannotator/web-highlighter","version":"0.8.0","keywords":["text","highlight","web","persistence","lightweight","selection","range"],"author":{"name":"alienzhou","email":"alienzhou16@163.com"},"license":"MIT","_id":"@plannotator/web-highlighter@0.8.0","maintainers":[{"name":"backnotprop","email":"backnotprop@gmail.com"}],"homepage":"https://github.com/backnotprop/web-highlighter","bugs":{"url":"https://github.com/backnotprop/web-highlighter/issues"},"dist":{"shasum":"f4e541522f3a976aa2ea0d8cf9f52bff1638ecdd","tarball":"https://registry.npmjs.org/@plannotator/web-highlighter/-/web-highlighter-0.8.0.tgz","fileCount":88,"integrity":"sha512-I4z8MjnO2ynDGuDo1570GdD8fU4nNVx2S2bveyZ0WvB+pUllvhedsWRs2Kl1VTW8EiKEIgO18MWnZUVOHxk6hw==","signatures":[{"sig":"MEUCIQDJ71E7Ae/aZCOfMooxoo5A3uyXhA7Njaw6lu8ucmY5/wIgSOF/74m1tX8IG0vw6/E7oNJwquT60ObMIQsjLAUjp9g=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":2462052},"main":"dist/web-highlighter.min.js","husky":{"hooks":{"pre-commit":"lint-staged && npm run test"}},"types":"dist/index.d.ts","module":"src/index.ts","browser":"dist/web-highlighter.min.js","exports":{".":{"types":"./dist/index.d.ts","import":"./src/index.ts","require":"./dist/web-highlighter.min.js"}},"gitHead":"1a27c1f45264598f258cf9468c2ce4dd7514f260","scripts":{"lint":"eslint \"src/**/*.ts\" --fix","test":"mocha -r ts-node/register -r tsconfig-paths/register test/**.spec.ts","build":"run-s build:code build:types","serve":"http-server -p 8081 ./dist","start":"node script/dev.js","watch":"webpack --config ./config/webpack.config.prod.js --watch","static":"run-p watch serve","coverage":"nyc -r lcov -e .ts -x \"test/**/*.ts\" npm run test","build:code":"target=dist node script/build.js","build:types":"tscpaths -p tsconfig.json -s ./src -o ./dist","build-example":"target=example node script/build.js","serve-example":"http-server example/static","prepublishOnly":"run-s lint build test"},"_npmUser":{"name":"backnotprop","email":"backnotprop@gmail.com"},"repository":{"url":"git+https://github.com/backnotprop/web-highlighter.git","type":"git"},"_npmVersion":"10.9.0","description":"A no-runtime dependency lib for text highlighting & persistence on any website. Fork with selection fixes.","directories":{},"lint-staged":{"src/**/*.ts":["prettier --write","eslint --fix"]},"_nodeVersion":"22.12.0","_hasShrinkwrap":false,"devDependencies":{"nyc":"^15.0.1","chai":"^4.2.0","chalk":"^2.4.2","husky":"^4.3.8","jsdom":"^16.2.2","mocha":"^7.1.2","sinon":"^9.0.2","eslint":"^7.18.0","ts-node":"^8.10.1","webpack":"^4.25.1","fs-extra":"^7.0.1","prettier":"^2.2.1","showdown":"^1.9.0","tscpaths":"0.0.9","coveralls":"^3.1.0","ts-loader":"^5.3.0","better-opn":"^1.0.0","css-loader":"^1.0.1","typescript":"^4.1.3","@types/chai":"^4.2.11","@types/node":"^14.18.63","http-server":"^0.11.1","lint-staged":"^10.5.3","npm-run-all":"^4.1.5","webpack-cli":"^3.1.2","@types/jsdom":"^16.2.3","@types/mocha":"^7.0.2","@types/sinon":"^9.0.1","jsdom-global":"^3.0.2","style-loader":"^0.23.1","webpack-merge":"^4.1.4","tsconfig-paths":"^3.9.0","webpack-dev-server":">=3.1.11","@types/jsdom-global":"^3.0.2","html-webpack-plugin":"^3.2.0","clean-webpack-plugin":"^1.0.0","eslint-plugin-import":"^2.22.1","eslint-config-prettier":"^7.1.0","eslint-plugin-prettier":"^3.3.1","@typescript-eslint/parser":"^4.13.0","tsconfig-paths-webpack-plugin":"^3.5.1","@typescript-eslint/eslint-plugin":"^4.13.0","text-replace-html-webpack-plugin":"^1.0.3"},"_npmOperationalInternal":{"tmp":"tmp/web-highlighter_0.8.0_1768679706572_0.5151701367915698","host":"s3://npm-registry-packages-npm-production"}},"0.8.1":{"name":"@plannotator/web-highlighter","version":"0.8.1","description":"A no-runtime dependency lib for text highlighting & persistence on any website. Fork with selection fixes.","main":"dist/web-highlighter.min.js","module":"dist/web-highlighter.min.js","types":"dist/index.d.ts","browser":"dist/web-highlighter.min.js","scripts":{"lint":"eslint \"src/**/*.ts\" --fix","test":"mocha -r ts-node/register -r tsconfig-paths/register test/**.spec.ts","coverage":"nyc -r lcov -e .ts -x \"test/**/*.ts\" npm run test","serve-example":"http-server example/static","serve":"http-server -p 8081 ./dist","watch":"webpack --config ./config/webpack.config.prod.js --watch","build-example":"target=example node script/build.js","static":"run-p watch serve","start":"node script/dev.js","build:types":"tscpaths -p tsconfig.json -s ./src -o ./dist","build:code":"target=dist node script/build.js","build":"run-s build:code build:types","prepublishOnly":"run-s lint build test"},"husky":{"hooks":{"pre-commit":"lint-staged && npm run test"}},"lint-staged":{"src/**/*.ts":["prettier --write","eslint --fix"]},"homepage":"https://github.com/backnotprop/web-highlighter","repository":{"type":"git","url":"git+https://github.com/backnotprop/web-highlighter.git"},"keywords":["text","highlight","web","persistence","lightweight","selection","range"],"author":{"name":"alienzhou","email":"alienzhou16@163.com"},"license":"MIT","devDependencies":{"@types/chai":"^4.2.11","@types/jsdom":"^16.2.3","@types/jsdom-global":"^3.0.2","@types/mocha":"^7.0.2","@types/node":"^14.18.63","@types/sinon":"^9.0.1","@typescript-eslint/eslint-plugin":"^4.13.0","@typescript-eslint/parser":"^4.13.0","better-opn":"^1.0.0","chai":"^4.2.0","chalk":"^2.4.2","clean-webpack-plugin":"^1.0.0","coveralls":"^3.1.0","css-loader":"^1.0.1","eslint":"^7.18.0","eslint-config-prettier":"^7.1.0","eslint-plugin-import":"^2.22.1","eslint-plugin-prettier":"^3.3.1","fs-extra":"^7.0.1","html-webpack-plugin":"^3.2.0","http-server":"^0.11.1","husky":"^4.3.8","jsdom":"^16.2.2","jsdom-global":"^3.0.2","lint-staged":"^10.5.3","mocha":"^7.1.2","npm-run-all":"^4.1.5","nyc":"^15.0.1","prettier":"^2.2.1","showdown":"^1.9.0","sinon":"^9.0.2","style-loader":"^0.23.1","text-replace-html-webpack-plugin":"^1.0.3","ts-loader":"^5.3.0","ts-node":"^8.10.1","tsconfig-paths":"^3.9.0","tsconfig-paths-webpack-plugin":"^3.5.1","tscpaths":"0.0.9","typescript":"^4.1.3","webpack":"^4.25.1","webpack-cli":"^3.1.2","webpack-dev-server":">=3.1.11","webpack-merge":"^4.1.4"},"_id":"@plannotator/web-highlighter@0.8.1","gitHead":"6f91706dc9d4c0bc15c91bc72f56cfdf7e7d5747","bugs":{"url":"https://github.com/backnotprop/web-highlighter/issues"},"_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-FlteNOwRj9iNSY/AhFMtqOnVS4FvsACvTw6IiOM1y8iDyhiU/WeZOgjURENvIY+wuUaiS9DDFmg0PrHMyuMR1Q==","shasum":"4bfbb2d49e3da7160110c456f3b776f51b09227a","tarball":"https://registry.npmjs.org/@plannotator/web-highlighter/-/web-highlighter-0.8.1.tgz","fileCount":88,"unpackedSize":2461911,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCTKc7JxQ27eT0qKrWOSn6cd1XkUzLVj3mWbG4QD9OtGQIgK1yXDDqo2kN3JvXEx8Vf6i6pFXP/zP83fj7ro2n6kD8="}]},"_npmUser":{"name":"backnotprop","email":"backnotprop@gmail.com"},"directories":{},"maintainers":[{"name":"backnotprop","email":"backnotprop@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/web-highlighter_0.8.1_1768680460377_0.4959967033834731"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-17T19:55:06.512Z","modified":"2026-01-17T20:07:40.789Z","0.8.0":"2026-01-17T19:55:06.803Z","0.8.1":"2026-01-17T20:07:40.647Z"},"bugs":{"url":"https://github.com/backnotprop/web-highlighter/issues"},"author":{"name":"alienzhou","email":"alienzhou16@163.com"},"license":"MIT","homepage":"https://github.com/backnotprop/web-highlighter","keywords":["text","highlight","web","persistence","lightweight","selection","range"],"repository":{"type":"git","url":"git+https://github.com/backnotprop/web-highlighter.git"},"description":"A no-runtime dependency lib for text highlighting & persistence on any website. Fork with selection fixes.","maintainers":[{"name":"backnotprop","email":"backnotprop@gmail.com"}],"readme":"
\n

Web Highlighter  🖍️

\n

\n ✨ 一个可以在任何网页上做高亮笔记前端库，支持高亮文本的持久化存储与还原 ✨🖍️\n

\n \n

\n \n \"Build\n \n \n \"NPM\n \n \n Coverage Status\n \n \n \"Gzip\n \n \n \"Codebeat\"\n \n \n \"MIT\n \n

\n
\n\n---\n\n[English](https://github.com/alienzhou/web-highlighter/blob/master/README.md) | 简体中文\n\n## 1. 背景\n\n灵感来源：当有天我访问某个网页时，突然希望能够像在PDF上一样，对网页文本添加高亮笔记，并支持永久保存这些高亮笔记区域。\n\n如果你曾经访问过 [medium.com](http://medium.com) 这个网站，你一定见到或用过它的高亮在线笔记功能：用户选择一个文本片段然后点击“高亮”按钮，接着，这段文本就被涂上了背景颜色。此外，这些高亮区域还被存储了下来，当你下次访问时会自动恢复。就像下面这个简单的示例一样。\n\n![](./docs/img/sample.gif)\n\n对在线阅读器来说，这是一个非常有用的功能。如果你是开发者，也许你会希望在你的网页上支持该功能以吸引更多的读者；如果你是一名用户（像我一样），你可能会想要一个支持该功能的浏览器插件。\n\n因此，「web-highlighter」仓库的目标就是帮助你在任意的网页上快速地实现高亮笔记功能（例如博客网页、文档阅读器、在线图书等）。它包含了文本高亮笔记与高亮持久化下场景的核心能力，并且支持通过它简单易用的 API 来实现你自己的产品需求。「web-highlighter」已经被用在了我们网站的生产环境中。\n\n\n## 2. 安装\n\n```bash\nnpm i web-highlighter\n```\n\n## 3. 使用方式\n\n两行代码，即可开启文本选中时的自动高亮功能。\n\n```JavaScript\nimport Highlighter from 'web-highlighter';\n(new Highlighter()).run();\n```\n\n四行代码，实现高亮区域持久化。\n\n```JavaScript\nimport Highlighter from 'web-highlighter';\n\n// 1. 实例化\nconst highlighter = new Highlighter();\n\n// 2. 从后端获取高亮信息，还原至网页\ngetRemoteData().then(s => highlighter.fromStore(s.startMeta, s.endMeta, s.id, s.text));\n\n// 3. 监听高亮笔记创建事件，并将信息存至后端\nhighlighter.on(Highlighter.event.CREATE, ({sources}) => save(sources));\n\n// 4. 开启自动划词高亮\nhighlighter.run();\n```\n\n## 4. 示例\n\n一个更复杂的使用示例。\n\n```JavaScript\nimport Highlighter from 'web-highlighter';\n\n// 不高亮 pre&code 元素\nconst highlighter = new Highlighter({\n exceptSelectors: ['pre', 'code']\n});\n\n// 添加一些交互监听\nhighlighter\n .on('selection:hover', ({id}) => {\n // 通过添加 class，实现类似 hover 效果\n highlighter.addClass('highlight-wrap-hover', id);\n })\n .on('selection:hover-out', ({id}) => {\n // 鼠标离开时清除悬停样式\n highlighter.removeClass('highlight-wrap-hover', id);\n })\n .on('selection:create', ({sources}) => {\n sources = sources.map(hs => ({hs}));\n // 存储\n store.save(sources);\n });\n\n// 获取数据存储，将高亮区域还原展示在网页上\nstore.getAll().forEach(\n ({hs}) => highlighter.fromStore(hs.startMeta, hs.endMeta, hs.text, hs.id)\n);\n\nhighlighter.run()\n```\n\n此外，该仓库还自带了一个 DEMO 示例（在`example`文件夹中）。启动该 DEMO 只需要 ——\n\n首先安装运行依赖\n\n```bash\nnpm i\n```\n\n然后启动\n\n```bash\nnpm start\n```\n\n最后访问 http://127.0.0.1:8085/ 即可。\n\n---\n\n另一个使用 web-highlighter 开发的实际产品的例子（用于左侧高亮部分）：\n\n![product sample](https://user-images.githubusercontent.com/9822789/64678049-632e8500-d4ab-11e9-99d6-f960bc90d17b.gif)\n\n## 5. 工作原理\n\nweb-highlighter 会通过 [`Selection API`](https://caniuse.com/#search=selection%20api) 来读取被选择的文本范围。然后选区的信息会被转换为一个可序列化的数据结构，以便于能够发送并存储在后端。当用户再次访问你的页面时，这些存储的数据被返回然后在你的页面上进行反序列化。数据结构本身是技术栈无关的。所以你可以用在任意技术栈构建的页面上（例如 React、Vue、Angular 或者 jQuery 等等）。\n\n想要了解更多实现细节，可以阅读[这篇文章](https://www.alienzhou.com/2019/04/21/web-note-highlight-in-js/)。\n\n## 6. 详细使用文档\n\n### 6.1. 配置项\n\n```JavaScript\nconst highlighter = new Highlighter([opts])\n```\n\n创建一个新的 `highlighter` 实例.\n\n`opts` 会合并至默认配置 (如下所示).\n\n```JavaScript\n{\n $root: document.documentElement,\n exceptSelectors: null,\n wrapTag: 'span',\n style: {\n className: 'highlight-mengshou-wrap'\n }\n}\n```\n\n配置说明:\n\n| 参数名 | 类型 | 描述 | 是否必须 | 默认值 |\n|---|---|---|---|---|\n| $root | `Document | HTMLElement` | 高亮区域的根容器元素 | 否 | `document` |\n| exceptSelectors | `Array` | 过滤器，符合的元素将不会被高亮 | 否 | `null` |\n| wrapTag | `string` | 用于包裹高亮文本的 HTML 标签名 | 否 | `span` |\n| verbose | `boolean` | 是否需要输出警告和错误信息 | 否 | `false` |\n| style | `Object` | 用于控制高亮区域的样式 | 否 | 详见下方 |\n\n`style` 属性配置:\n\n| 参数名 | 类型 | 描述 | 是否必须 | 默认值 |\n|---|---|---|---|---|\n| className | `string` | 高亮包裹元素的 className | 否 | `highlight-mengshou-wrap` |\n\n`exceptSelectors` 为 `null` 或 `Array`。 支持 ID 选择器、类选择器和标签选择器。例如，想要忽略标签为 h1 和 classname 为 `.title` 的元素：\n\n```JavaScript\nvar highlighter = new Highlighter({\n exceptSelectors: ['h1', '.title']\n});\n```\n\n### 6.2. 静态方法\n\n#### 6.2.1. `Highlighter.isHighlightSource(source)`\n\n用于判断 `source` 参数是否为一个 highlight source 对象。如果是则返回 `true`, 反之亦然.\n\n#### 6.2.2. `Highlighter.isHighlightWrapNode($node)`\n\n用于判断 `$node` 参数是否为一个高亮包裹元素。如果是则返回 `true`, 反之亦然.\n\n### 6.3. 实例方法\n\n#### 6.3.1. `highlighter.run()`\n\n开启自动划词高亮。当用户选择了一段文本时，「web-highlighter」会自动为其添加高亮效果。\n\n#### 6.3.2. `highlighter.stop()`\n\n关闭自动划词高亮。\n\n#### 6.3.3. `highlighter.dispose()`\n\n当你不再需要使用高亮功能时，需要先使用该方法来移除一些事件监听，回收一些资源。\n\n#### 6.3.4. `highlighter.fromRange(range)`\n\n该方法支持你传一个 [`Range`](https://developer.mozilla.org/en-US/docs/Web/API/Range)，并基于该对象进行高亮笔记操作。你可以通过 `window.getSelection().getRangeAt(0)` 方法来获取一个 range 对象，或者使用 `document.createRange()` 方法来创建一个新的 range 对象。\n\n如下所示：\n\n```JavaScript\nconst selection = window.getSelection();\nif (!selection.isCollapsed) {\n highlighter.fromRange(selection.getRangeAt(0));\n}\n```\n\n#### 6.3.5. `highlighter.fromStore(start, end, text, id)`\n\n大多数情况下，这个 API 用于通过后端的持久化信息还原出文本高亮效果。\n\n其中四个所需的参数来源于 `HighlightSource` 对象。`HighlightSource` 对象是一个特殊的对象，当高亮笔记被添加时会被创建。为了能在后端实现数据持久化，它需要找到一种能表示 dom 节点的数据结构。这个结构在 web-highlighter 内被称为`HighlightSource`。\n\n四个参数的含义如下：\n\n- start `Object`: 开始节点的源信息\n- end `Object`: 结束节点的源信息\n- text `string`: 文本内容\n- id `string`: 高亮的唯一 ID\n\n#### 6.3.6. `highlighter.remove(id)`\n\n清除指定 id 的高亮区域。该 id 默认会由 web-highlighter 在创建高亮区域使生成。你也可以通过添加钩子来应用你自己的 id 生成规则。钩子相关文档可以[看这里](https://github.com/alienzhou/web-highlighter/blob/master/docs/ADVANCE.zh_CN.md)。\n\n#### 6.3.7. `highlighter.removeAll()`\n\n清除根节点下的所有高亮区域。\n\n#### 6.3.8. `highlighter.addClass(classname, id)`\n\n为某个 id 的高亮区域添加 CSS 类名。你可以通过这个 API 来改变某个高亮区域的样式。\n\n#### 6.3.9. `highlighter.removeClass(classname, id)`\n\n移除某个 id 的高亮区域的指定 CSS 类名。类似于 `highlighter.addClass` 的逆操作。\n\n#### 6.3.10. `highlighter.getDoms([id])`\n\n获取高亮区域内的所有包裹节点。一个高亮区域可能会包含多个片段。它会返回所有这些片段的包裹节点（DOM 节点）。\n\n如果 `id` 参数留空，它会返回根节点下的所有高亮区域中的包裹节点。\n\n#### 6.3.11. `highlighter.getIdByDom(node)`\n\n传入一个 DOM 节点，返回该节点对应的高亮区域的唯一 ID。支持传入非包裹元素。如果是非包裹，则会自动找到最近的祖先包裹元素。\n\n#### 6.3.11. `highlighter.getExtraIdByDom(node)`\n\n传入一个 DOM 节点，返回该节点对应的高亮区域的额外 ID。支持传入非包裹元素。如果是非包裹，则会自动找到最近的祖先包裹元素。\n\n#### 6.3.12. `highlighter.setOption(opt)`\n\n可以使用该 API 改变实例的配置项，参数结构和构造函数中的一致，支持传入部分参数。\n\n### 6.4. `Event Listener`\n\nweb-highlighter 使用监听器方式来处理异步事件。\n\n例如下面这样，\n\n```JavaScript\nvar highlighter = new Highlighter();\nhighlighter.on(Highlighter.event.CREATE, function (data, inst, e) {\n // ...\n});\n```\n\n回调函数接受三个参数：\n\n- data `any`: 事件触发时的具体数据\n- inst `Highlighter`: 当前 Highlighter 类的实例\n- e `Event`: 某些事件会有浏览器触发（例如点击）, web-highlighter 会将浏览器原生 event 对象暴露出来\n\n`Highlighter.event` 是内部的 `EventType` 类型. 它包含了如下这些事件：\n\n- `EventType.CLICK`: 点击高亮区域\n- `EventType.HOVER`: 鼠标移至高亮区域，类似 mouse enter\n- `EventType.HOVER_OUT`: 鼠标移出高亮区域，类似 mouse leave\n- `EventType.CREATE`: 高亮区域被创建\n- `EventType.REMOVE`: 高亮区域被清除\n\n对于不同的事件类型，其 `data` 所包含的具体属性如下：\n\n#### 6.4.1. `EventType.CLICK`\n\n|name|description|type|\n|---|---|---|\n|`id`| 高亮区域唯一 ID |string|\n\n#### 6.4.2. `EventType.HOVER`\n\n|name|description|type|\n|---|---|---|\n|`id`| 高亮区域唯一 ID |string|\n\n#### 6.4.3. `EventType.HOVER_OUT`\n\n|name|description|type|\n|---|---|---|\n|`id`| 高亮区域唯一 ID |string|\n\n#### 6.4.4. `EventType.CREATE`\n\n> 不包含参数 `e`\n\n|name|description|type|\n|---|---|---|\n|`source`|`HighlightSource` 对象|Array|\n|`type`|高亮区域创建的来源|string|\n\n`source` 是一个 `HighlightSource` 对象。该对象在高亮区域被创建时，会由 web-highlighter 创建并传给回调函数。为了能够在后端（数据库中）进行高亮数据的持久化，需要使用一个可以被序列化（`JSON.stringify()`）的数据结构来表示浏览器中的 DOM 节点。`HighlightSource` 就是 web-highlighter 提供的来用于持久化的数据对象。\n\n`type` 用来告知开发者高亮区域被创建的原因。目前 `type` 包含两种可能的值：`from-input` 和 `from-store`。`from-input` 表明该高亮区域是通过用户操作（用户划词的选区）创建的；`from-store` 则表示该高亮区域是通过持久化的 `HighlightSource` 中的数据还原出来的。\n\n#### 6.4.5. `EventType.REMOVE`\n\n> 不包含参数 `e`\n\n|name|description|type|\n|---|---|---|\n|`ids`|一组高亮区域唯一 ID|Array|\n\n### 6.5. Hooks（钩子）\n\n钩子可以用来更好地控制整个高亮流程。通过它你几乎可以实现任何自定义的逻辑。详细内容请参考[下面部分](#更多使用方式)。\n\n## 7. 兼容性\n\n> 依赖 [Selection API](https://caniuse.com/#search=selection%20api)。\n\n- IE 11\n- Edge\n- Firefox 52+\n- Chrome 15+\n- Safari 5.1+\n- Opera 15+\n\n_**移动端支持：**_ 如果检测为移动端，则会自动使用相应的事件监听来替代 PC 端事件。\n\n## 8. 更多使用方式\n\n为了便于开发者更好地控制相关的高亮行为，web-highlighter 提供一些内部的钩子。\n\n想了解内部钩子及其使用方式，可以阅读[这篇文档](https://github.com/alienzhou/web-highlighter/blob/master/docs/ADVANCE.zh_CN.md)。\n\n## 9. 许可证\n\n[MIT](./LICENCE)\n","readmeFilename":"README.zh_CN.md"}