@mobtrue/dom-utils NPM

dom-utils

dom-utils é uma biblioteca utilitária em JavaScript para manipulação do DOM, projetada para simplificar a interação com elementos HTML de maneira eficiente. Esta ferramenta está em desenvolvimento e pode conter erros. Por isso, ainda não é recomendada para uso em projetos de grande escala. É ideal para portfólios ou pequenos projetos pessoais. Convidamos desenvolvedores a contribuir para o desenvolvimento da biblioteca.

Instalação

Para instalar a biblioteca, utilize o npm:

npm install @mobtrue/dom-utils

Importação

Para utilizar a biblioteca em seu projeto, importe o módulo da seguinte forma:

import domUtils from "@mobtrue/dom-utils";

Configuração do `package.json`

Para que o Node.js reconheça seu arquivo como um módulo ES (ES Module), adicione a seguinte linha ao seu package.json:

{
  "type": "module"
}

Verificação de Importação

Para garantir que todas as funções necessárias estão disponíveis, utilize a função de validação de importação:

domUtils.$validateImport();

Para executar o seu arquivo, utilize o seguinte comando:

node 'Your_file.js'

Funcionalidades Principais

Seleção de Elementos:
- $query: Seleciona um único elemento.
- $queryAll: Seleciona todos os elementos que correspondem a um seletor.
- $getParent, $getChildren, $getSiblings: Métodos para navegar na hierarquia do DOM.
Manipulação de Elementos:
- $setHTML, $setText: Para definir o conteúdo HTML ou texto de um elemento.
- $hide, $show, $toggleVisibility: Para controlar a visibilidade dos elementos.
- $setAttribute, $getComputedStyle: Para manipular atributos e estilos computados.
Manipulação de Classes:
- $addClass, $removeClass, $toggleClass: Para adicionar, remover ou alternar classes CSS.
- $getClasses, $setClasses: Para obter ou definir classes de um elemento.
Manipulação de Estilos:
- $setStyle, $setOpacity, $setBackgroundColor: Para aplicar estilos CSS a elementos.
Manipulação de Eventos:
- $onClick, $onHover, $onInput: Métodos para adicionar ouvintes de eventos a elementos.
Animações:
- $fadeIn, $fadeOut, $zoomIn, $zoomOut: Métodos para animações básicas de entrada e saída.
Criar e Remover Elementos:
- $createElement, $removeElement, $clone, $appendChild, $insertBefore, $insertAfter: Para manipulação de elementos no DOM.
Drag & Drop:
- $makeDraggable, $makeDroppable, $getDragData, $setDragData: Para implementar funcionalidades de arrastar e soltar.

Funcionalidades Detalhadas

A seguir, estão listadas as funções disponíveis na biblioteca, apresentando uma breve descrição em português e inglês, juntamente com exemplos de uso.

Seleção de Elementos

$query(selector)
• Seleciona uma tag, classe, ID ou qualquer outro elemento no DOM usando o método querySelector.
• Selects a tag, class, id, or any other element in the DOM using the querySelector method.

const element = domUtils.$query('#content');

$queryAll(selector)
• Seleciona todos os elementos que correspondem ao seletor no DOM.
• Selects all elements that match the selector in the DOM.

const elements = domUtils.$queryAll('.item');

$getParent(selector)
• Retorna o elemento pai do elemento selecionado.
• Returns the parent element of the selected element.

const parent = domUtils.$getParent('#childElement');

$getChildren(selector)
• Retorna todos os filhos do elemento selecionado.
• Returns all children of the selected element.

const children = domUtils.$getChildren('#parentElement');

$getSiblings(selector)
• Retorna todos os irmãos do elemento selecionado.
• Returns all siblings of the selected element.

const siblings = domUtils.$getSiblings('#specificElement');

$getFirstChild(selector)
• Retorna o primeiro filho do elemento selecionado.
• Returns the first child of the selected element.

const firstChild = domUtils.$getFirstChild('#parentElement');

$getLastChild(selector)
• Retorna o último filho do elemento selecionado.
• Returns the last child of the selected element.

const lastChild = domUtils.$getLastChild('#parentElement');

$getNthChild(selector, n)
• Retorna o n-ésimo filho do elemento selecionado.
• Returns the n-th child of the selected element.

const nthChild = domUtils.$getNthChild('#parentElement', 2);

$getNextSibling(selector)
• Retorna o próximo irmão do elemento selecionado.
• Returns the next sibling of the selected element.

const nextSibling = domUtils.$getNextSibling('#specificElement');

$getPreviousSibling(selector)
• Retorna o irmão anterior do elemento selecionado.
• Returns the previous sibling of the selected element.

const previousSibling = domUtils.$getPreviousSibling('#specificElement');

Manipulação de Elementos

$setHTML(selector, html)
• Define o conteúdo HTML de um elemento no DOM.
• Sets the HTML content of an element in the DOM.

domUtils.$setHTML('#element', '<p>Conteúdo HTML</p>');

$setText(selector, text)
• Define o texto de um elemento no DOM.
• Sets the text of an element in the DOM.

domUtils.$setText('#meuElemento', 'Texto Atualizado');

$hide(selector)
• Esconde um elemento no DOM.
• Hides an element in the DOM.

domUtils.$hide('#meuElemento');

$show(selector, displayType = "block")
• Exibe um elemento no DOM.
• Shows an element in the DOM.

domUtils.$show('#meuElemento', 'inline');

$toggleVisibility(selector)
• Alterna a visibilidade de um elemento no DOM.
• Toggles the visibility of an element in the DOM.

domUtils.$toggleVisibility('#meuElemento');

$setAttribute(selector, attribute, value)
• Define um atributo de um elemento no DOM.
• Sets an attribute of an element in the DOM.

domUtils.$setAttribute('#meuElemento', 'data-custom', 'valor');

$getComputedStyle(selector)
• Retorna os estilos computados de um elemento no DOM.
• Returns the computed styles of an element in the DOM.

const styles = domUtils.$getComputedStyle('#meuElemento');

Manipulação de Classes

$addClass(selector, className)
• Adiciona uma classe a um elemento no DOM.
• Adds a class to an element in the DOM.

domUtils.$addClass('#meuElemento', 'novaClasse');

$removeClass(selector, className)
• Remove uma classe de um elemento no DOM.
• Removes a class from an element in the DOM.

domUtils.$removeClass('#meuElemento', 'classeExistente');

$toggleClass(selector, className)
• Alterna uma classe em um elemento no DOM.
• Toggles a class on an element in the DOM.

domUtils.$toggleClass('#meuElemento', 'classeAlternativa');

$replaceClass(selector, oldClass, newClass)
• Substitui uma classe por outra em um elemento no DOM.
• Replaces a class with another on an element in the DOM.

domUtils.$replaceClass('#meuElemento', 'classeAntiga', 'classeNova');

$hasClass(selector, className)
• Verifica se um elemento possui uma classe específica.
• Checks if an element has a specific class.

const hasClass = domUtils.$hasClass('#meuElemento', 'classeVerificada');

$getClasses(selector)
• Retorna todas as classes de um elemento no DOM.
• Returns all classes of an element in the DOM.

const classes = domUtils.$getClasses('#meuElemento');

$setClasses(selector, classNames)
• Define as classes de um elemento no DOM.
• Sets the classes of an element in the DOM.

domUtils.$setClasses('#meuElemento', ['classe1', 'classe2']);

Manipulação de Estilos

$setStyle(selector, styles)
• Aplica estilos CSS a um elemento no DOM.
• Applies CSS styles to an element in the DOM.

domUtils.$setStyle('#meuElemento', { color: 'blue', backgroundColor: 'yellow' });

$setOpacity(selector, value)
• Define a opacidade de um elemento no DOM.
• Sets the opacity of an element in the DOM.

domUtils.$setOpacity('#meuElemento', 0.5);

$setBorder(selector, config)
• Define a borda de um elemento no DOM.
• Sets the border of an element in the DOM.

domUtils.$setBorder('#meuElemento', '1px solid black');

$setGradient(selector, colors, direction = "to right")
• Define um gradiente de fundo em um elemento no DOM.
• Sets a background gradient on an element in the DOM.

domUtils.$setGradient('#meuElemento', ['red', 'blue'], 'to bottom');

$setBackgroundColor(selector, color)
• Define a cor de fundo de um elemento no DOM.
• Sets the background color of an element in the DOM.

domUtils.$setBackgroundColor('#meuElemento', 'green');

$setColor(selector, color)
• Define a cor do texto de um elemento no DOM.
• Sets the text color of an element in the DOM.

domUtils.$setColor('#meuElemento', 'red');

$setWidth(selector, width)
• Define a largura de um elemento no DOM.
• Sets the width of an element in the DOM.

domUtils.$setWidth('#meuElemento', '100px');

$setHeight(selector, height)
• Define a altura de um elemento no DOM.
• Sets the height of an element in the DOM.

domUtils.$setHeight('#meuElemento', '200px');

Manipulação de Eventos

$onClick(selector, callback)
• Adiciona um ouvinte de evento de clique a um elemento.
• Adds a click event listener to an element.

domUtils.$onClick('#meuElemento', () => {
    alert('Elemento clicado!');
});

$onHover(selector, callback)
• Adiciona um ouvinte de evento de mouse sobre a um elemento.
• Adds a mouseover event listener to an element.

domUtils.$onHover('#meuElemento', () => {
    console.log('Mouse sobre o elemento!');
});

$onKeyPress(key, callback)
• Adiciona um ouvinte de evento de tecla pressionada ao documento.
• Adds a keydown event listener to the document.

domUtils.$onKeyPress('Enter', (event) => {
    console.log('Tecla Enter pressionada!');
});

$onResize(callback)
• Adiciona um ouvinte de evento de redimensionamento à janela.
• Adds a resize event listener to the window.

domUtils.$onResize(() => {
    console.log('Janela redimensionada!');
});

$onFocus(selector, callback)
• Adiciona um ouvinte de evento de foco a um elemento.
• Adds a focus event listener to an element.

domUtils.$onFocus('#meuElemento', () => {
    console.log('Elemento focado!');
});

$onBlur(selector, callback)
• Adiciona um ouvinte de evento de perda de foco a um elemento.
• Adds a blur event listener to an element.

domUtils.$onBlur('#meuElemento', () => {
    console.log('Elemento perdeu o foco!');
});

$onInput(selector, callback)
• Adiciona um ouvinte de evento de entrada a um elemento.
• Adds an input event listener to an element.

domUtils.$onInput('#meuElemento', (event) => {
    console.log('Entrada alterada: ', event.target.value);
});

$onChange(selector, callback)
• Adiciona um ouvinte de evento de alteração a um elemento.
• Adds a change event listener to an element.

domUtils.$onChange('#meuElemento', () => {
    console.log('Valor alterado!');
});

Animações

$fadeIn(selector, duration)
• Faz um elemento aparecer gradualmente.
• Fades an element in gradually.

domUtils.$fadeIn('#meuElemento', 500);

$fadeOut(selector, duration)
• Faz um elemento desaparecer gradualmente.
• Fades an element out gradually.

domUtils.$fadeOut('#meuElemento', 500);

$zoomIn(selector, scale = 1.2, duration = 500)
• Aumenta o tamanho de um elemento gradualmente.
• Gradually increases the size of an element.

domUtils.$zoomIn('#meuElemento', 1.5, 500);

$zoomOut(selector, scale = 0.8, duration = 500)
• Diminui o tamanho de um elemento gradualmente.
• Gradually decreases the size of an element.

domUtils.$zoomOut('#meuElemento', 0.5, 500);

$moveTo(selector, x, y, duration = 500)
• Move um elemento para uma posição específica.
• Moves an element to a specific position.

domUtils.$moveTo('#meuElemento', 100, 200, 500);

$bounce(selector, intensity = 10, duration = 500)
• Faz um elemento "quicar" na tela.
• Makes an element "bounce" on the screen.

domUtils.$bounce('#meuElemento', 20, 500);

$shake(selector, duration = 500, intensity = 10)
• Faz um elemento "tremer" na tela.
• Makes an element "shake" on the screen.

domUtils.$shake('#meuElemento', 500, 15);

$slideDown(selector, duration = 500)
• Faz um elemento descer na tela.
• Slides an element down on the screen.

domUtils.$slideDown('#meuElemento', 500);

$slideUp(selector, duration = 500)
• Faz um elemento subir na tela.
• Slides an element up on the screen.

domUtils.$slideUp('#meuElemento', 500);

Criar e Remover Elementos

$createElement(tag, {attributes}, [children])
• Cria um novo elemento no DOM com seus atributos e filhos, como classes, IDs, tags, textos, etc.
• Creates a new element in the DOM with its attributes and children, such as classes, IDs, tags, texts, etc.

const newElement = domUtils.$createElement('div', {class: 'newDiv'}, [`
   <h1>A new div</h1>
   <span>Made with the dom-utils library</span>
`]);

$removeElement(selector)
• Remove um elemento do DOM.
• Removes an element from the DOM.

domUtils.$removeElement('#meuElemento');

$clone(selector)
• Clona um elemento do DOM.
• Clones an element from the DOM.

const clonedElement = domUtils.$clone('#meuElemento');

$appendChild(selector, child)
• Adiciona um elemento recém-criado ao DOM.
• Adds a newly created element to the DOM.

const child = domUtils.$createElement('span', {}, ['Novo Filho']);
domUtils.$appendChild('#meuElemento', child);

$insertBefore(selector, newElement)
• Insere um novo elemento antes do elemento selecionado no DOM.
• Inserts a new element before the selected element in the DOM.

const newElement = domUtils.$createElement('div', { class: 'novoDiv' }, ['Novo Elemento']);
domUtils.$insertBefore('#meuElemento', newElement);

$insertAfter(selector, newElement)
• Insere um novo elemento após o elemento selecionado no DOM.
• Inserts a new element after the selected element in the DOM.

const newElement = domUtils.$createElement('div', { class: 'novoDiv' }, ['Novo Elemento']);
domUtils.$insertAfter('#meuElemento', newElement);

Drag & Drop

$makeDraggable(selector)
• Torna um elemento arrastável.
• Makes an element draggable.

domUtils.$makeDraggable('#meuElemento');

$makeDroppable(selector, callback)
• Torna um elemento uma área de soltar.
• Makes an element a drop area.

domUtils.$makeDroppable('#dropArea', () => {
    alert('Elemento solto na área!');
});

$getDragData(event)
• Obtém dados de arrasto de um evento.
• Gets drag data from an event.

const dragData = domUtils.$getDragData(event);

$setDragData(event, data)
• Define dados de arrasto em um evento.
• Sets drag data on an event.

domUtils.$setDragData(event, 'algum dado');

Contribuição

Convidamos desenvolvedores a contribuir para o desenvolvimento da biblioteca. Sinta-se à vontade para abrir problemas ou solicitações de pull no repositório.

Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

Essa documentação fornece uma visão abrangente e profissional do uso da biblioteca dom-utils, abrangendo a instalação, importação, configuração e exemplos de uso das funções principais. Sinta-se à vontade para expandir ou modificar conforme necessário!

dom javascript utils manipulação html

1.1.0

5 months ago

1.0.2