Uma biblioteca JavaScript para adicionar funcionalidade de menções em campos de texto editáveis
npm install @billbarsch/mentionjsbash
npm install @billbarsch/mentionjs
`
Uso Básico
`javascript
import MentionJS from '@billbarsch/mentionjs';
const editor = document.getElementById('editor');
const mention = new MentionJS({
inputElement: editor,
data: {
// Exemplo com API
usuarios: {
label: 'Usuários',
data: 'https://jsonplaceholder.typicode.com/users?username_like=',
prefix: 'Usuario: ',
// Obrigatório: função para exibição do item
display: item => ${item.username} (${item.email}),
// Obrigatório: função para processar resposta da API
parseResponse: (data) => data.map(user => ({
tipo: 'usuario',
id: user.id,
username: user.username,
email: user.email
})),
// Opcional: estilos personalizados
styles: {
background: '#e3f2fd',
color: '#1565c0',
border: '#90caf9'
}
},
// Exemplo com dados estáticos
vendas: {
label: 'Vendas',
prefix: 'Venda: ',
// Obrigatório: função para exibição do item
display: item => ${item.label} - R$ ${item.valor},
data: [
{ id: 1, label: 'Venda 1', valor: 1000 },
{ id: 2, label: 'Venda 2', valor: 2000 }
],
// Obrigatório: função para processar os dados
parseResponse: (data) => data.map(venda => ({
...venda,
tipo: 'venda'
})),
// Opcional: estilos personalizados
styles: {
background: '#e8f5e9',
color: '#2e7d32',
border: '#a5d6a7'
}
}
}
});
`
🎯 Exemplos
O projeto inclui exemplos em HTML e React:
$3
Exemplo completo com dados estáticos e dinâmicos:
`bash
Abra diretamente no navegador
open examples/html/url.html
`
$3
`jsx
import React, { useEffect, useRef } from 'react';
import MentionJS from '@billbarsch/mentionjs';
function App() {
const editorRef = useRef(null);
const outputHtmlRef = useRef(null);
const outputJsonRef = useRef(null);
const outputTextRef = useRef(null);
const outputDisplayRef = useRef(null);
const mentionRef = useRef(null);
useEffect(() => {
if (editorRef.current) {
mentionRef.current = new MentionJS({
inputElement: editorRef.current,
data: {
usuarios: {
label: 'Usuários',
data: 'https://jsonplaceholder.typicode.com/users?username_like=',
prefix: 'Usuário: ',
display: item => ${item.username} (${item.email}),
parseResponse: (data) => data.map(user => ({
tipo: 'usuario',
id: user.id,
username: user.username,
email: user.email
})),
styles: {
background: '#e3f2fd',
color: '#1565c0',
border: '#90caf9'
}
},
produtos: {
label: 'Produtos',
data: 'https://dummyjson.com/products/search?q=',
prefix: 'Produto: ',
display: item => ${item.title} - ${item.description},
parseResponse: (data) => {
if (!data || !data.products) return [];
return data.products.map(product => ({
tipo: 'produto',
id: product.id,
title: product.title,
description: product.description
}));
},
styles: {
background: '#fff9c4',
color: '#f57f17',
border: '#ffd54f'
}
},
vendas: {
label: 'Vendas',
prefix: 'Venda: ',
display: item => ${item.label} - R$ ${item.valor} (${item.data}),
data: [
{
tipo: 'venda',
id: 1,
label: 'Venda 1',
valor: 1000,
data: '2024-03-20'
},
{
tipo: 'venda',
id: 2,
label: 'Venda 2',
valor: 2000,
data: '2024-03-21'
}
],
styles: {
background: '#fff9c4',
color: '#f57f17',
border: '#ffd54f'
}
}
},
styles: {
usuarios: {
background: '#e3f2fd',
color: '#1565c0',
border: '#90caf9'
},
produtos: {
background: '#fff9c4',
color: '#f57f17',
border: '#ffd54f'
},
vendas: {
background: '#fff9c4',
color: '#f57f17',
border: '#ffd54f'
}
}
});
const updateOutputs = () => {
if (outputHtmlRef.current) {
outputHtmlRef.current.textContent = mentionRef.current.getHtml();
}
if (outputJsonRef.current) {
outputJsonRef.current.textContent = JSON.stringify(mentionRef.current.getJson(), null, 2);
}
if (outputTextRef.current) {
outputTextRef.current.textContent = mentionRef.current.getText();
}
if (outputDisplayRef.current) {
outputDisplayRef.current.textContent = mentionRef.current.getDisplayText();
}
};
editorRef.current.addEventListener('input', updateOutputs);
return () => {
if (editorRef.current) {
editorRef.current.removeEventListener('input', updateOutputs);
}
if (mentionRef.current) {
mentionRef.current.destroy();
}
};
}
}, []);
return (
MentionJS - Exemplo React
Digite @ e escolha o tipo de menção (usuários, produtos ou vendas)
Conteúdo HTML:
Conteúdo JSON:
Conteúdo Texto:
Conteúdo Display:
);
}
export default App;
`
Para usar o exemplo React:
`bash
Entre na pasta do exemplo React
cd examples/react
Instale as dependências
npm install
Inicie o servidor de desenvolvimento
npm start
`
API
$3
- inputElement: Elemento HTML onde as menções serão habilitadas
- data: Objeto com configuração dos tipos de menção. Cada tipo deve ser um objeto com:
- label: Nome amigável do tipo que será exibido no menu de seleção (opcional, usa o tipo se não fornecido)
- data: URL para busca ou array de dados estáticos
- display: (Obrigatório) Função que define como o item será exibido no menu de seleção
- prefix: Prefixo opcional que será adicionado antes do texto do display (ex: "Usuario: ", "Produto: ", "Venda: ")
- parseResponse: (Obrigatório) Função de transformação dos dados
- styles: (Opcional) Objeto com estilos personalizados para o tipo:
- background: Cor de fundo
- color: Cor do texto
- border: Cor da borda
$3
Cada tipo de menção deve ser configurado como um objeto com as seguintes propriedades:
1. Configuração com dados estáticos:
`javascript
vendas: {
label: 'Vendas', // opcional
prefix: 'Venda: ', // opcional
display: item => ${item.label} - R$ ${item.valor}, // obrigatório
data: [
{ id: 1, label: 'Venda 1', valor: 1000 },
{ id: 2, label: 'Venda 2', valor: 2000 }
],
parseResponse: (data) => data.map(venda => ({ // obrigatório
...venda,
tipo: 'venda'
})),
styles: { // opcional
background: '#e8f5e9',
color: '#2e7d32',
border: '#a5d6a7'
}
}
`
2. Configuração com API:
`javascript
usuarios: {
label: 'Usuários', // opcional
prefix: 'Usuario: ', // opcional
data: 'https://api.exemplo.com/usuarios?q=',
display: item => ${item.nome} (${item.email}), // obrigatório
parseResponse: (data) => data.map(user => ({ // obrigatório
tipo: 'usuario',
id: user.id,
nome: user.nome,
email: user.email
})),
styles: { // opcional
background: '#e3f2fd',
color: '#1565c0',
border: '#90caf9'
}
}
`
A função parseResponse pode retornar objetos com qualquer estrutura, desde que:
- Tenha um id único
- Contenha todos os campos necessários para a função display
A função display define como o item será exibido no menu de seleção e pode usar qualquer campo retornado pelo parseResponse.
$3
- getText(): Retorna o texto puro com as menções em formato JSON
- getHtml(): Retorna o HTML do conteúdo com as menções formatadas
- getJson(): Retorna um array com todas as menções e seus dados
- getDisplayText(): Retorna o texto puro com as menções formatadas usando a função display original
Por exemplo:
`javascript
// Se o texto no editor for: "Olá Usuário: Bret (Sincere@april.biz), como vai?"
mention.getText()
// Retorna: 'Olá {"tipo":"usuario","id":"1","username":"Bret","email":"Sincere@april.biz"}, como vai?'
mention.getDisplayText()
// Retorna: 'Olá Bret (Sincere@april.biz), como vai?'
`
Desenvolvimento
1. Clone o repositório
`bash
git clone https://github.com/billbarsch/mentionjs.git
`
2. Instale as dependências
`bash
npm install
`
3. Execute o exemplo React
`bash
cd examples/react
npm install
npm start
`
🤝 Contribuindo
1. Faça um fork do projeto
2. Crie sua feature branch (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature`)