web highlighter

Web Highlighter ？q

任何网站上的无依赖性lib用于突出显示和持久性？

---

英语| 简体中文

背景

它来自一个想法：突出显示网站上的文本，并像您在PDF中所做的那样保存突出显示的领域。

如果您曾经访问过Medive.com，则必须知道突出显示注释的功能：用户选择文本段，然后单击“突出显示”按钮。然后，文本将以闪亮的背景颜色突出显示。此外，下次访问时，突出显示的区域将被保存和恢复。就像一个简单的演示bellow。

这对于读者来说是一个有用的功能。如果您是开发人员，则可能希望您的网站支持它并吸引更多访问。如果您是用户（像我一样），则可能需要一个浏览器 - 插曲来执行此操作。

因此，仓库（网络高速公路）旨在帮助您快速在任何网站上实施突出显示（例如，博客，文档查看者，在线书籍等）。它包含注释突出显示和持久性的核心能力。您可以通过一些易于使用的API实施自己的产品。它已用于我们的生产网站。

安装

npm i web-highlighter

用法

选择文本时，只有两行突出显示。

 import Highlighter from 'web-highlighter' ;
( new Highlighter ( ) ) . run ( ) ;

如果您需要持久性，则四行就可以了。

 import Highlighter from 'web-highlighter' ;

// 1. initialize
const highlighter = new Highlighter ( ) ;

// 2. retrieve data from backend, then highlight it on the page
getRemoteData ( ) . then ( s => highlighter . fromStore ( s . startMeta , s . endMeta , s . id , s . text ) ) ;

// 3. listen for highlight creating, then save to backend
highlighter . on ( Highlighter . event . CREATE , ( { sources } ) => save ( sources ) ) ;

// 4. auto highlight
highlighter . run ( ) ; 

例子

一个更复杂的例子

 import Highlighter from 'web-highlighter' ;

// won't highlight pre&code elements
const highlighter = new Highlighter ( {
    exceptSelectors : [ 'pre' , 'code' ]
} ) ;

// add some listeners to handle interaction, such as hover
highlighter
    . on ( 'selection:hover' , ( { id } ) => {
        // display different bg color when hover
        highlighter . addClass ( 'highlight-wrap-hover' , id ) ;
    } )
    . on ( 'selection:hover-out' , ( { id } ) => {
        // remove the hover effect when leaving
        highlighter . removeClass ( 'highlight-wrap-hover' , id ) ;
    } )
    . on ( 'selection:create' , ( { sources } ) => {
        sources = sources . map ( hs => ( { hs } ) ) ;
        // save to backend
        store . save ( sources ) ;
    } ) ;

// retrieve data from store, and display highlights on the website
store . getAll ( ) . forEach (
    // hs is the same data saved by 'store.save(sources)'
    ( { hs } ) => highlighter . fromStore ( hs . startMeta , hs . endMeta , hs . text , hs . id )
) ;

// auto-highlight selections
highlighter . run ( )

此外，此存储库中还有一个示例（在example文件夹中）。要玩它，您只需要 -

首先输入存储库并运行

npm i

然后开始示例

 npm start

最后访问http://127.0.0.1:8085/

---

另一个由Web-Highllighter构建的真实产品（对于左侧的突出显示区域）：

它如何工作

它将通过Selection API读取所选范围。然后，该范围的信息将转换为可序列化的数据结构，以便将其存储在后端中。当用户下次访问您的页面时，这些数据将在您的页面中返回并进行启用。数据结构是独立的技术堆栈。因此，您可以在用React / Vue / Vue / Angular / Jquery等制成的任何“静态”页面上使用。

有关更多详细信息，请阅读本文（中文）。

蜜蜂

1。选项

 const highlighter = new Highlighter ( [ opts ] )

创建一个新的highlighter实例。

opts将合并到默认选项中（显示Bellow）。

 {
    $root : document . documentElement ,
    exceptSelectors : null ,
    wrapTag : 'span' ,
    style : {
        className : 'highlight-mengshou-wrap'
    }
}

所有选项：

姓名	类型	描述	必需的	默认
$ root	`文件	htmlelement`	容器启用突出显示	不
除外	Array<string>	如果元素与选择器匹配，则不会突出显示	不	null
包裹	string	HTML标签用于包装突出显示的文本	不	span
冗长	boolean	剂量需要输出（打印）一些警告和错误消息	不	false
风格	Object	控制突出的区域样式	不	下面的详细信息

style字段选项：

姓名	类型	描述	必需的	默认
className	string	包装元素的类名称	不	highlight-mengshou-wrap

exceptSelectors需要null或Array<string> 。它支持ID选择器，类选择器和标签选择器。例如，跳过H1和.title元素：

 var highlighter = new Highlighter ( {
    exceptSelectors : [ 'h1' , '.title' ]
} ) ;

2。静态方法

Highlighter.isHighlightSource(source)

如果source是一个高光源对象，它将返回true vice经文。

Highlighter.isHighlightWrapNode($node)

如果$node是高光包装器dom节点，则它将返回true ，vice vice vice。

3。实例方法

highlighter.run()

开始自动高光。当用户选择文本段时，将自动添加突出显示。

highlighter.stop()

它将停止自动高光。

highlighter.dispose()

当您不再想要荧光笔时，请记住先打电话给它。它将删除一些听众并进行一些清理。

highlighter.fromRange(range)

您可以将Range对象传递给它，然后将突出显示。您可以使用window.getSelection().getRangeAt(0)获取范围对象或使用document.createRange()创建新范围。

将其用作波纹管：

 const selection = window . getSelection ( ) ;
if ( ! selection . isCollapsed ) {
    highlighter . fromRange ( selection . getRangeAt ( 0 ) ) ;
} 

highlighter.fromStore(start, end, text, id)

通常，您使用此API来强调文本，该文本通过后端存储的持久信息。

这四个值来自HighlightSource对象。 HighlightSource对象是由Web-Highlighter创建的特殊对象。对于后端（数据库）中的持久性，有必要找到代表DOM节点的数据结构。该结构在Web-Highllighter中称为HighlightSource 。

四个属性的含义：

• 启动Object ：有关开始元素的元信息
• 结束Object ：有关结束元素的元信息
• 文本string ：文本内容
• ID string ：唯一ID

highlighter.remove(id)

通过其唯一ID删除（清洁）突出显示区域。默认情况下，ID将由Web-Highllighter生成。您还可以为自己的规则添加钩子。挂钩文档在这里。

highlighter.removeAll()

删除所有属于根部的突出显示区域。

highlighter.addClass(className, id)

通过唯一ID添加一个为突出显示区域（包装元素）的className。您可以使用此API更改突出显示区域的样式。

highlighter.removeClass(className, id)

通过唯一ID删除className。它是highlighter.addClass的逆操作。

highlighter.getDoms([id])

在突出显示的区域中获取所有包裹节点。突出显示的区域可能包含许多细分市场。它将返回所有包装这些段的DOM节点。

如果id未通过，它将返回所有区域的包装节点。

highlighter.getIdByDom(node)

如果您有DOM节点，则可以为您返回唯一的突出显示ID。传递非包装元素时，它将找到最近的祖先包装器节点。

highlighter.getExtraIdByDom(node)

如果您有一个DOM节点，则可以为您返回额外的唯一突出显示ID。传递非包装元素时，它将找到最近的祖先包装器节点。

highlighter.setOption(opt)

您可以使用此API来更改荧光笔的选项。参数的结构与构造函数相同。您可以通过部分选项。

4。活动听众

Web-Highlighter使用听众来处理这些事件。

例如

 var highlighter = new Highlighter ( ) ;
highlighter . on ( Highlighter . event . CREATE , function ( data , inst , e ) {
    // ...
} ) ;

回调功能将接收三个参数：

• 数据any ：事件数据
• Inst Highlighter ：当前荧光笔实例
• E Event ：某些事件是由浏览器触发的（例如单击），Web-Highlighter将公开它

Highlighter.event是EventType类型。它包含：

• EventType.CLICK ：单击突出显示的区域
• EventType.HOVER ：鼠标进入突出显示的区域
• EventType.HOVER_OUT ：鼠标离开突出显示的区域
• EventType.CREATE ：创建了一个突出显示的区域
• EventType.REMOVE ：删除突出显示的区域

不同的事件具有不同的data 。以下属性：

EventType.CLICK

姓名	描述	类型
id	突出显示ID	细绳

EventType.HOVER

姓名	描述	类型
id	突出显示ID	细绳

EventType.HOVER_OUT

姓名	描述	类型
id	突出显示ID	细绳

EventType.CREATE

没有参数e

姓名	描述	类型
source	HighlightSource对象	大批
type	创建的原因	细绳

source是HighlightSource对象。当创建突出显示区域时，它是由Web-Highllighter创建的对象。对于后端（数据库）中的持久性，有必要使用可以序列化的数据结构（ JSON.stringify() ）代表浏览器中的DOM节点。 HighlightSource是为此设计的数据结构。

type说明了为什么会创建突出显示区域。现在type具有两个可能的值： from-input和from-store 。 from-input显示，由于用户的选择而创建了突出显示的区域。 from-store意思是从存储中。

EventType.REMOVE

没有参数e

姓名	描述	类型
ids	高光ID的列表	大批

5。钩

钩子可让您强大地控制突出显示的流程。您几乎可以通过挂钩自定义任何逻辑。在“前进”部分中查看更多。

兼容性

这取决于选择API。

• 即11
• 边缘
• Firefox 52+
• Chrome 15+
• Safari 5.1+
• 歌剧15+

移动支持：在移动设备上自动检测移动设备并使用触摸事件。

进步

它为您提供了一些钩子，以便可以自己控制突出显示行为。

要了解有关钩子的更多信息，请阅读此文档。

执照

麻省理工学院