cep-search-lib
v1.0.6
Published
Lib para achar endereço por cep
Downloads
23
Maintainers
Readme
Sumário
Instalação e Configuração
Esta biblioteca foi desenvolvida para facilitar a busca de endereços a partir de CEPs brasileiros, utilizando a API pública do ViaCEP. Ela oferece dois recursos principais: um Hook chamado useCep e um componente React chamado CepSearch. Vamos mostrar como instalar e configurar essa biblioteca.
Pré-requisitos
Antes de instalar, verifique se você já possui um projeto React configurado. Se ainda não, siga os passos para criar um projeto básico usando create-react-app:
npx create-react-app meu-projeto
cd meu-projeto
Instalação
Para instalar a biblioteca, basta rodar o seguinte comando:
npm install cep-search-lib
Isso adicionará todos os arquivos e dependências necessárias ao seu projeto.
Feats Implementadas
Atualmente, esta biblioteca possui duas funcionalidades principais, que facilitam a integração com a API ViaCEP:
useCep: Um Hook customizado que permite fazer buscas de endereço a partir de um CEP informado pelo usuário. CepSearch: Um componente que utiliza o useCep para fornecer uma interface completa de busca de endereços, com campo de entrada e botão de ação.
Agora que você instalou a biblioteca, veja abaixo os detalhes de uso para cada funcionalidade implementada.
Dependências
Esta biblioteca utiliza as seguintes versões de dependências para garantir a compatibilidade e o funcionamento correto:
{
"@mui/material": "^6.1.3",
"@mui/system": "^6.1.3",
"next": "^14.2.15",
"react": "^18.3.1",
"react-toastify": "^10.0.5"
}
useCep Hook - Documentação
O useCep
é um Hook customizado desenvolvido para facilitar a busca de endereços no Brasil, utilizando a API pública do ViaCEP. Com ele, é possível obter dados completos de um endereço, como logradouro, bairro, cidade e estado, a partir de um CEP informado. Que roda do lado do cliente
Exemplo de uso
import React from 'react';
import { useCep } from 'cep-search-lib';
const SimpleCepLogger = () => {
const { cep, setCep, fetchEndereco } = useCep();
const handleFetch = () => {
fetchEndereco(); // Aciona a busca do endereço
console.log('CEP atual:', cep);
};
return (
<div>
<input
type="text"
value={cep}
onChange={(e) => setCep(e.target.value)}
placeholder="Digite o CEP"
/>
<button onClick={handleFetch}>Buscar</button>
</div>
);
};
export default SimpleCepLogger;
Retornos
const { cep, setCep, endereco, fetchEndereco } = useCep();
cep
Estado que armazena o valor atual do CEP inserido.
setCep
Função responsável por atualizar o estado do cep.
endereco
Objeto que contém a resposta da API ViaCEP com os dados do endereço.
interface cepResponse {
cep: string;
logradouro: string;
complemento: string;
unidade: string;
bairro: string;
localidade: string;
uf: string;
estado: string;
regiao: string;
ibge: string;
gia: string;
ddd: string;
siafi: string;
erro: boolean;
}
fetchEndereco
Função que aciona a busca do endereço com base no CEP informado.
tratamentos de erros
O Hook lida com diferentes tipos de erros, exibindo mensagens apropriadas através de um toast (opcionalmente). Você pode controlar a exibição dessas mensagens utilizando a flag handleToasts.
Utilizando a flag handleToasts
- handleToasts: true (padrão): Exibe mensagens de erro e sucesso utilizando toasts.
- handleToasts: false (padrão): Não exibe toasts. O controle das mensagens é de sua responsabilidadew.
casos de erros
1. CEP inválido ou formato incorreto
Motivo do erro: O usuário inseriu um CEP que não tem 8 dígitos ou contém caracteres que não são numéricos.
- Mensagem no toast: "Por favor, insira um CEP válido com 8 dígitos numéricos."
Esse erro ocorre porque o CEP deve ter exatamente 8 dígitos numéricos. O código verifica se o valor inserido atende a esses critérios e, caso contrário, a busca nem é realizada.
2. CEP não encontrado
Motivo do erro: O CEP informado é válido, mas não está registrado no ViaCEP.
- Mensagem no toast: "CEP não encontrado. Por favor, insira um CEP válido."
Esse erro ocorre quando a API do ViaCEP retorna a chave erro: true
, indicando que o CEP não foi encontrado na base de dados. Isso pode acontecer quando o CEP é inexistente ou está incorreto.
3. Erro na requisição ou problema na API
Motivo do erro: Houve algum problema com a requisição, como falha de conexão, erro no servidor, ou algum outro problema inesperado.
- Mensagem no toast: "Houve um problema ao buscar o endereço."
CepSearch Component - Documentação
O CepSearch
é um componente React que utiliza o Hook customizado useCep
para permitir que os usuários busquem endereços a partir de um CEP. Ele fornece uma interface simples, onde o usuário pode digitar um CEP e visualizar os dados do endereço correspondente.
Exemplo de Uso
Para utilizar o componente CepSearch
, você deve importá-lo em seu arquivo e incluí-lo na sua árvore de componentes.
import React from 'react';
import { CepSearch } from 'cep-search-lib';
const BuscaEndereco = () => {
return (
<div>
<h1>Buscar Endereço pelo CEP</h1>
<CepSearch
label="Digite o CEP"
buttonLabel="Buscar"
inputVariant="outlined"
buttonVariant="contained"
buttonColor="primary"
/>
</div>
);
};
export default BuscaEndereco;
Estrutura Visual do Componente
Ao renderizar o componente CepSearch
, os seguintes elementos aparecerão na tela em ordem:
TextField (Campo de Entrada):
- Descrição: Um campo de entrada onde o usuário pode digitar o CEP.
O
TextField
é exibido no topo, ocupando toda a largura disponível e com margens para melhor espaçamento.Button (Botão de Busca):
- Descrição: Um botão que aciona a busca pelo endereço quando clicado.
O botão é exibido logo abaixo do campo de entrada, com um estilo destacado que o torna fácil de identificar e acessar.
Box (Container para Resultados):
- Descrição: Um contêiner que é renderizado condicionalmente, contendo as informações do endereço, se disponíveis.
Dentro do
Box
, os seguintes elementos são exibidos, um por um, caso oendereco.logradouro
esteja presente:Typography (Exibição de Rua):
- Texto: "Rua: {endereco.logradouro}"
Typography (Exibição de Unidade):
- Texto: "Unidade: {endereco.unidade}"
Typography (Exibição de Bairro):
- Texto: "Bairro: {endereco.bairro}"
Typography (Exibição de Cidade):
- Texto: "Cidade: {endereco.localidade}"
Typography (Exibição de Estado):
- Texto: "Estado: {endereco.uf}"
Typography (Exibição de Região):
- Texto: "Região: {endereco.regiao}"
Typography (Exibição de DDD):
- Texto: "DDD: {endereco.ddd}"
Propriedades (cepComponentProps
)
O componente CepSearch
aceita várias propriedades que permitem personalizar tanto o comportamento quanto a aparência do componente.
Propriedades disponíveis:
label
(string
)
Texto exibido como rótulo do campo de entrada de CEP.- Default:
"Digite o CEP"
- Default:
buttonLabel
(string
)
Texto exibido no botão de busca.- Default:
"Buscar"
- Default:
inputVariant
("outlined" | "filled" | "standard"
)
Define o estilo visual do campo de entrada.- Default:
"outlined"
- Default:
buttonColor
("primary" | "secondary"
)
Cor do botão de busca.- Default:
"primary"
- Default:
buttonVariant
("outlined" | "contained" | "text"
)
Variante do botão, alterando seu estilo visual.- Default:
"contained"
- Default:
buttonFullWidth
(boolean
)
Define se o botão ocupará toda a largura disponível.- Default:
false
- Default:
containerSx
(SxProps
)
Propriedades de estilo personalizadas para o contêiner do componente.inputSx
(SxProps
)
Propriedades de estilo personalizadas para o campo de entrada.buttonSx
(SxProps
)
Propriedades de estilo personalizadas para o botão de busca.