web highlighter

Web Highlighter ? Iqu

Um Lib não dependência para destaque e persistência de texto em qualquer site?

---

Inglês | 简体中文

Fundo

É de uma idéia: destaque textos no site e salve as áreas destacadas, assim como o que você faz no PDF.

Se você já visitou o Medium.com, deve saber o recurso de destacar notas: os usuários selecionam um segmento de texto e clique no botão 'Destaque'. Em seguida, o texto será destacado com uma cor de fundo brilhante. Além disso, as áreas destacadas serão salvas e recuperadas quando você o visitar na próxima vez. É como a demonstração simples abaixo.

Este é um recurso útil para os leitores. Se você é um desenvolvedor, pode querer que seu site o forneça e atraia mais visitas. Se você é um usuário (como eu), pode querer um plugin de navegador para fazer isso.

Por esse motivo, o repositório (com um marcador da Web) pretende ajudá-lo a implementar a Nota de destaque em qualquer site rapidamente (por exemplo, blogs, visualizadores de documentos, livros on-line e assim por diante). Ele contém as habilidades centrais para o destaque e persistência da nota. E você pode implementar seu próprio produto por algumas APIs fáceis de usar. Foi usado para nossos sites em produção.

Instalar

npm i web-highlighter

Uso

Apenas duas linhas, destacadas quando os textos são selecionados.

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

Se você precisar de persistência, quatro linhas o fazem.

 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 ( ) ; 

Exemplo

Um exemplo mais complexo

 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 ( )

Além disso, há um exemplo neste repo (na pasta example ). Para brincar com isso, você só precisa - -

Primeiro insira o repositório e corra

npm i

Então inicie o exemplo

 npm start

Finalmente, visite http://127.0.0.1:8085/

---

Outro produto real construído com um marcador da Web (para a área de destaque à esquerda):

Como funciona

Ele lerá o intervalo selecionado pela Selection API . Em seguida, as informações do intervalo serão convertidas em uma estrutura de dados serializável para que possa ser armazenada no back -end. Quando os usuários visitam sua página na próxima vez, esses dados serão retornados e desserializados em sua página. A estrutura de dados é independente da pilha de tecnologia. Assim, você pode usar em quaisquer páginas 'estáticas' feitas com React / Vue / Angular / JQuery e outros.

Para mais detalhes, leia este artigo (em chinês).

APIs

1. Opções

 const highlighter = new Highlighter ( [ opts ] )

Crie uma nova instância highlighter .

opts serão mesclados nas opções padrão (mostradas abaixo).

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

Todas as opções:

nome	tipo	descrição	obrigatório	padrão
$ root	`Documento	Htmlelement`	o contêiner para permitir o destaque	Não
Exce Executselectors	Array<string>	Se um elemento corresponder ao seletor, ele não será destacado	Não	null
envolvendo	string	A tag html usada para envolver textos destacados	Não	span
detalhado	boolean	dose precisa produzir (imprimir) alguma mensagem de aviso e erro	Não	false
estilo	Object	controle de áreas destacadas estilo	Não	detalhes abaixo

Opções de campo style :

nome	tipo	descrição	obrigatório	padrão
ClassName	string	o nome da classe para o elemento de embrulho	Não	highlight-mengshou-wrap

exceptSelectors precisa null ou Array<string> . Ele suporta seletores de identificação, seletores de classe e seletores de tags. Por exemplo, para pular H1 e .title elementos:

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

2. Métodos estáticos

Highlighter.isHighlightSource(source)

Se a source for um objeto de origem de destaque, ele retornará true , vice -verso.

Highlighter.isHighlightWrapNode($node)

Se o $node for um Node Dom Wrapper Dom, ele retornará true , Vice Verse.

3. Métodos de instância

highlighter.run()

Inicie a iluminação automática. Quando o usuário selecionar um segmento de texto, um destaque será adicionado automaticamente ao texto.

highlighter.stop()

Isso vai parar a iluminação automática.

highlighter.dispose()

Quando você não quiser mais o marcador, lembre -se de chamá -lo primeiro. Ele removerá alguns ouvintes e fará alguma limpeza.

highlighter.fromRange(range)

Você pode passar um objeto Range para ele e, em seguida, será destacado. Você pode usar window.getSelection().getRangeAt(0) para obter um objeto de intervalo ou usar document.createRange() para criar um novo intervalo.

Use -o como abaixo:

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

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

Principalmente, você usa esta API para destacar o texto pelas informações persistidas armazenadas no back -end.

Esses quatro valores são do objeto HighlightSource . O objeto HighlightSource é um objeto especial criado pelo marcador da Web quando a área destacada criada. Para persistência no back -end (banco de dados), é necessário encontrar uma estrutura de dados para representar um nó DOM. Essa estrutura é chamada HighlightSource no bem-sucedido da Web.

Quatro significados dos atributos:

• Iniciar Object : meta informações sobre o elemento inicial
• Object final: meta informações sobre o elemento final
• string de texto: conteúdo de texto
• string ID: ID exclusivo

highlighter.remove(id)

Remova (limpe) uma área destacada por seu ID exclusivo. O ID será gerado por um marcador da Web por padrão. Você também pode adicionar um gancho para sua própria regra. Ganchos doces aqui.

highlighter.removeAll()

Remova todas as áreas destacadas pertencentes à raiz.

highlighter.addClass(className, id)

Adicione um nome de classe para áreas destacadas (elementos de embrulho) por ID exclusivo. Você pode alterar o estilo de uma área destacada usando esta API.

highlighter.removeClass(className, id)

Remova o nome da classe por ID exclusivo. É operação inversa de highlighter.addClass .

highlighter.getDoms([id])

Obtenha todos os nós de embrulho em uma área destacada. Uma área destacada pode conter muitos segmentos. Ele retornará todos os nós DOM que envolvem esses segmentos.

Se o id não for passado, ele retornará todos os nós de embrulho das áreas.

highlighter.getIdByDom(node)

Se você tiver um nó DOM, ele pode retornar o ID de destaque exclusivo para você. Ao passar por um elemento que não é de wrapper, ele encontrará o nó do wrapper mais próximo.

highlighter.getExtraIdByDom(node)

Se você tiver um nó DOM, ele pode retornar o ID de destaque extra exclusivo para você. Ao passar por um elemento que não é de wrapper, ele encontrará o nó do wrapper mais próximo.

highlighter.setOption(opt)

Você pode usar esta API para alterar as opções do marcador. A estrutura dos parâmetros é a mesma que a do construtor. Você pode passar opções parciais.

4. ouvinte de eventos

A Web-Alterlighter usa os ouvintes para lidar com os eventos.

por exemplo

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

A função de retorno de chamada receberá três parâmetros:

• Dados any : dados do evento
• Highlighter Inst: Instância atual do marcador
• E Event : Algum evento é acionado pelo navegador (como cliques), o bem-sucedido da Web o expõe

Highlighter.event é o tipo EventType . Contém

• EventType.CLICK : Clique na área destacada
• EventType.HOVER : Mouse entra na área destacada
• EventType.HOVER_OUT : Mouse deixa a área destacada
• EventType.CREATE : Uma área destacada é criada
• EventType.REMOVE : Uma área destacada é removida

Evento diferente tem data diferentes. Atributos abaixo:

EventType.CLICK

nome	descrição	tipo
id	o ID de destaque	corda

EventType.HOVER

nome	descrição	tipo
id	o ID de destaque	corda

EventType.HOVER_OUT

nome	descrição	tipo
id	o ID de destaque	corda

EventType.CREATE

nenhum parâmetro e

nome	descrição	tipo
source	Objeto HighlightSource	Variedade
type	o motivo da criação	corda

source é um objeto HighlightSource . É um objeto criado por um marcador da Web quando a área destacada criada. Para persistência no back -end (banco de dados), é necessário usar uma estrutura de dados que possa ser serializada ( JSON.stringify() ) para representar um nó DOM nos navegadores. HighlightSource é a estrutura de dados projetada para isso.

type explica por que uma área destacada é criada. Agora, type possui dois valores possíveis: from-input e from-store . from-input mostra que uma área destacada é criada devido à seleção do usuário. from-store significa isso de um armazenamento.

EventType.REMOVE

nenhum parâmetro e

nome	descrição	tipo
ids	Uma lista do ID de destaque	Variedade

5. Ganchos

Os ganchos permitem controlar o fluxo de destaque poderosamente. Você quase pode personalizar qualquer lógica por ganchos. Veja mais na parte 'avançada'.

Compatibilidade

Depende da API de seleção.

• Ou seja, 11
• Borda
• Firefox 52+
• Chrome 15+
• Safari 5.1+
• Opera 15+

Suportes móveis: detecte automaticamente se os dispositivos móveis e usam eventos de toque quando em dispositivos móveis.

Avançar

Ele fornece alguns ganchos para você, para que o comportamento de destaque possa ser controlado melhor por si.

Para saber mais sobre os ganchos, leia este documento.

Licença

Mit