typeahead standalone
v5.4.0
Uma biblioteca de preenchimento automático independente e rápida com todos os recursos
? Destaques ?
Encontre aqui documentos detalhados com demonstrações ao vivo para typeahead-standalone.js .
Prévia de um exemplo básico:
# you can install typeahead with npm
$ npm install --save typeahead-standalone
# Alternatively you can use Yarn
$ yarn add typeahead-standaloneEm seguida, inclua a biblioteca em seu aplicativo/página.
Como módulo,
// using ES6 modules
import typeahead from 'typeahead-standalone' ; // imports library (js)
import 'typeahead-standalone/dist/basic.css' ; // imports basic styles (css)
// using CommonJS modules
const typeahead = require ( 'typeahead-standalone' ) ;
require ( 'typeahead-standalone/dist/basic.css' ) ;No contexto do navegador,
<!-- Include the basic styles & the library -->
< link rel =" stylesheet " href =" ./node_modules/typeahead-standalone/dist/basic.css " />
< script src =" ./node_modules/typeahead-standalone/dist/typeahead-standalone.umd.js " > </ script >
<!-- Alternatively, you can use a CDN. For example, use jsdelivr to get the latest version -->
< link rel =" stylesheet " href =" https://cdn.jsdelivr.net/npm/typeahead-standalone/dist/basic.css " />
< script src =" https://cdn.jsdelivr.net/npm/typeahead-standalone " > </ script >
<!-- or use unpkg.com to get a specific version -->
< link rel =" stylesheet " href =" https://unpkg.com/[email protected]/dist/basic.css " />
< script src =" https://unpkg.com/[email protected]/dist/typeahead-standalone.umd.js " > </ script > A biblioteca estará disponível como um objeto global em window.typeahead
Typeahead requer um elemento input para se anexar e uma Data source (local/remota) para exibir sugestões.
Aqui está um exemplo muito básico (veja a demonstração para exemplos avançados)
<!-- include the library -->
< script src =" ... " async > </ script >
<!-- Html markup -->
< input type =" search " id =" searchInput " autocomplete =" off " placeholder =" Search... " > // local Data
const colors = [ 'Grey' , 'Brown' , 'Black' , 'Blue' ] ;
// input element to attach to
const inputElement = document . getElementById ( "searchInput" ) ;
typeahead ( {
input : inputElement ,
source : {
local : colors ,
// prefetch: {...}
// remote: {...}
}
} ) ; Você pode passar as seguintes opções de configuração para typeahead-standalone :
| Parâmetro | Descrição | Padrão |
|---|---|---|
input | O elemento de entrada DOM deve ser passado com este parâmetro e o typeahead se anexará a este campo. | - (Obrigatório) |
source | Esta é a fonte de dados a partir da qual as sugestões serão calculadas. A origem pode ser local, pré-buscada ou recuperada de um terminal remoto. Detalhes | - (Obrigatório) |
minLength | Especifique o comprimento mínimo, quando as sugestões deverão aparecer na tela. | 1 |
limit | Especifique o número máximo de sugestões que devem ser exibidas. | 5 |
highlight | As letras correspondentes da consulta são destacadas na lista de sugestões. Um tt-highlight é adicionado para facilitar o estilo | true |
autoSelect | Se definido como verdadeiro, pré-seleciona a primeira sugestão exibida | false |
hint | Atualiza o espaço reservado de entrada para ser igual à primeira sugestão correspondente. Uma classe tt-hint é adicionada para facilitar o estilo | true |
diacritics | Sinalizador para ativar/desativar pesquisa suportada por diacríticos de idioma (ou seja, pesquisa convertendo caracteres acentuados em seus equivalentes não acentuados) | undefined |
classNames: Object | O objeto classNames pode ser usado para definir classes personalizadas para cada elemento html injetado no DOM. Detalhes | undefined |
templates | Um objeto contendo modelos para cabeçalho, rodapé, sugestão, grupo e estado notFound. Consulte a seção de modelos para esclarecimentos | undefined |
preventSubmit | Se o seu elemento input for usado dentro de um elemento de formulário, este sinalizador permite evitar a ação de envio padrão quando a tecla ENTER é pressionada. | false |
onSubmit(event, selectedItem?) | Quando você deseja usar digitação antecipada fora de um elemento de formulário, esse manipulador pode ser usado para processar/enviar o valor de entrada. É acionado ao pressionar a tecla ENTER. O primeiro parâmetro é o evento do teclado e o segundo parâmetro é o item selecionado ou indefinido se nenhum item foi selecionado | undefined |
display(selectedItem, event?) => string | Este retorno de chamada é executado quando o usuário seleciona um item das sugestões. A sugestão/item atual é passada como parâmetro e deve retornar uma string que é definida como valor da entrada. O segundo event de parâmetro opcional é um evento de mouse/teclado que pode ser usado para rastrear a interação do usuário ou para análises. O padrão é null . | Retorna a representação em string do item selecionado |
tokenizer?: (words: string) => string[] | A função tokenizer é usada para dividir a consulta de pesquisa e os dados de pesquisa por um determinado caractere. Esta função é útil quando você deseja pesquisar palavras hifenizadas ou palavras com um determinado prefixo/sufixo | as palavras são divididas por caracteres de espaço (nova linha, tabulação, espaços) |
listScrollOptions?: ScrollIntoViewOptions | Permite um controle preciso sobre o comportamento de rolagem para uma grande lista de sugestões que precisam ser roladas. Essas opções são passadas para a função scrollIntoView() . Referência MDN | { block: "nearest", inline: "nearest", behaviour: "auto"} |
retainFocus | Este parâmetro é útil para controlar o foco ao pressionar a tecla “Tab” quando a lista de sugestões está aberta. Se ativado, seleciona a opção destacada e retorna o foco para a entrada de pesquisa. Se desativado, pressionar "Tab" selecionará a opção destacada e desviará o foco para o próximo item focável em seu formulário | true |
hooks | A opção de configuração hooks é útil para executar código arbitrário em momentos específicos do ciclo de vida do typeahead. Detalhes | indefinido |
Esta é a fonte de dados a partir da qual serão fornecidas sugestões. Este é o formato esperado do objeto de origem.
source: {
local: [],
remote: {
url: 'https://remoteapi.com/%QUERY', // OR "url: (inputQuery: string) => `https://remoteapi.com/${inputQuery}`"
wildcard: '%QUERY',
debounce: 300 // optional, default => 200ms
requestOptions: {} // optional, default => undefined
},
prefetch: {
url: 'https://remoteapi.com/load-suggestions', // OR `url: () => string`
when: 'onFocus', // optional, default => 'onInit'
done: false, // optional, default => false
process: (items) => void, // optional, default => undefined
requestOptions: {} // optional, default => undefined
},
keys: ['...'], // optional (required when source => Object[])
groupKey: '...', // optional, default => undefined
identity: (item) => string, // optional (determines uniqueness of each suggestion)
transform: function (data) {
// modify source data if needed & return it
return data;
}
}
local é usada quando você deseja fornecer sugestões de uma fonte local como uma variável.prefetch é usada quando você deseja pré-carregar sugestões de um terminal remoto com antecedência. Você deve fornecer o parâmetro url que aponta para o endpoint que retornará sugestões. Você pode fornecer um parâmetro opcional when que define quando a solicitação de pré-busca deve ocorrer. O padrão é onInit o que significa que as sugestões serão pré-carregadas assim que o typeahead for inicializado. Você pode configurá-lo para onFocus o que fará com que as sugestões sejam pré-carregadas somente quando o usuário focar a caixa de entrada de pesquisa. O sinalizador done é opcional e pode ser usado para desabilitar a solicitação de pré-busca programaticamente. Seu valor padrão é false . Ele é definido como true automaticamente quando os dados são pré-buscados pela primeira vez (para evitar múltiplas solicitações de rede). Ao definir done: true , a solicitação de pré-busca não ocorrerá. Um exemplo de caso de uso para fazer isso é quando você está usando localStorage para armazenar sugestões, mas o localStorage já tinha sugestões armazenadas anteriormente, eliminando assim a necessidade de pré-busca de dados novamente. O retorno de chamada process(suggestions) é opcional. Ele é executado após ocorrer a solicitação de pré-busca. Ele recebe as sugestões transformadas como parâmetro e como exemplo pode ser usado para armazenar as sugestões recebidas em localStorage para serem utilizadas posteriormente.remote é usada quando você deseja interrogar um terminal remoto para buscar dados.remote , você deve definir o url e as opções wildcard . wildcard será substituído pela string de pesquisa durante a execução da solicitação.debounce é usada para atrasar a execução de solicitações http (em milissegundos). É opcional e o padrão é 200ms.GET .transform() opcional que é chamada imediatamente após o endpoint de pré-busca/remoto retornar uma resposta. Você pode modificar a resposta antes que ela seja processada pela digitação antecipada.keys é necessária quando a fonte de dados é uma matriz de objetos. A primeira chave é utilizada para identificar qual propriedade do objeto deve ser utilizada como texto para exibição das sugestões. Por exemplo, digamos que a fonte de dados seja algo assim: /* Example Data source */
[
{ id : 1 , color : "Yellow" , meta : { colorCode : "YW" } } ,
{ id : 2 , color : "Green" , meta : { colorCode : "GN" } , shade : "Greenish" } ,
{ id : 3 , color : "Olive" , meta : { colorCode : "OV" } , shade : "Greenish" } ,
...
] Agora se quisermos usar o texto definido na propriedade color para aparecer como sugestões, então as chaves devem incluir color como a primeira chave. (ou seja, keys: ["color"] ).
Se desejar adicionar mais propriedades ao índice de pesquisa, você também pode especificar essas propriedades no array keys . Isso pode ser melhor compreendido com um exemplo. Vamos pegar o mesmo exemplo de fonte de dados mostrado acima. E se você quisesse pesquisar cores por outra propriedade ( colorCode ) e não apenas pela sua cor ? Para fazer isso, basta definir keys: ["color", "meta.colorCode"] . Se você pesquisar agora por “ YW ”, a sugestão “Amarelo” aparecerá conforme o esperado.
groupKey: "shade" , as sugestões serão agrupadas pela propriedade " shade ". Neste exemplo, as cores Verde e Oliva aparecerão no grupo “ Esverdeado ” ( shade ) enquanto a cor Amarelo não terá grupo. groupKey também oferece suporte ao acesso a propriedades aninhadas usando notação de ponto. (exemplo - groupKey: "category.title" )identity() é usada para determinar a exclusividade de cada sugestão. Ele recebe a sugestão como parâmetro e deve retornar uma string exclusiva para a sugestão dada. Esta é uma propriedade opcional e seu padrão é retornar o valor associado à primeira chave, ou seja, keys[0] . No entanto, o valor padrão pode não funcionar sempre. Por exemplo, considere o seguinte código - /* Example Data source of Songs */
[
{ title : "God is Good" , artist : "Don Moen" } ,
{ title : "God is Good" , artist : "Paul Wilbur" } ,
{ title : "God is Good" , artist : "Micheal Smith" } ,
{ title : "El Shaddai" , artist : "Amy Grant" } ,
...
] Vamos supor que as chaves estejam definidas como keys: ["title"] . Por padrão, a função identity() usa a primeira chave (ou seja, o título ) para determinar a exclusividade. Portanto, se você pesquisar por God , encontrará apenas 1 sugestão exibida, pois há 3 músicas com exatamente a mesma propriedade title . Para mostrar todas as 3 sugestões com artistas diferentes, você precisa definir a propriedade identity de forma que ela retorne uma string exclusiva -
identity ( item ) = > ` ${ item . title } ${ item . artist } ` ; É altamente recomendado definir a opção de configuração identity() para retornar uma string exclusiva quando sua fonte de dados for uma matriz de objetos.
Confira os exemplos ao vivo para maiores esclarecimentos.
Atualmente há apenas 1 gancho disponível:
updateHits: async (resultSet, loader) => Promise<resultSet> que é executado logo antes dos resultados da pesquisa serem exibidos ao usuário e pode ser usado para substituir as sugestões retornadas pelo índice de pesquisa. (útil para classificação, filtragem, adição ou remoção personalizada de resultados. Este gancho é uma função assíncrona que permite fazer solicitações AJAX para buscar novos resultados, se necessário) // Example usage of "updateHits" hook
typeahead ( {
input : document . querySelector ( ".myInput" ) ,
source : {
local : [ ] ,
// ...
} ,
hooks : {
updateHits : async ( resultSet , loader ) => {
resultSet . hits . push ( { name : "new suggestion" } ) ; // add new suggestion
// resultSet.hits.filter( ... ); // filter the suggestions
// resultSet.hits.sort( ... ); // custom sort the suggestions
// resultSet.count = 5000; // to set the total results found
/*** You can also make an AJAX request to fetch results ***/
// loader(); // display the loader template
// const response = await fetch('https://example.com');
// const text = await response.text();
// resultSet.hits = text && JSON.parse(text);
// loader(false); // hide the loader template
// resultSet.updateSearchIndex = true; // updates search index if necessary. Default `false`
return resultSet ; // you must return the resultSet
} ,
} ,
templates : {
loader : ( ) => { ... } ,
}
} ) ; Alguns estilos básicos são fornecidos com digitação antecipada. A IU depende totalmente de você e é personalizável até o pixel. Você pode usar as seguintes classes para adicionar/substituir estilos.
typeahead-standalone .tt-input .tt-hint .tt-list . (Uma classe tt-hide é adicionada quando nenhuma sugestão está disponível)tt-suggestion e se a sugestão for selecionada, então ela possui uma classe tt-selected adicionalmente.tt-highlight . Você pode adicionar seus próprios estilos direcionando o seletor pai .typeahead-standalone . Por exemplo, podemos atualizar a cor de fundo de cada sugestão conforme visto abaixo -
/* set background color for each suggestion */
. typeahead-standalone . tt-list . tt-suggestion {
background-color : green;
} Para substituir o estilo padrão, defina a opção de configuração className e use-a como seletor. Digamos que você defina className: "my-typeahead" e, para substituir o estilo ao passar o mouse/selecionar uma sugestão, você pode usar:
/* override styles */
. typeahead-standalone . my-typeahead . tt-list . tt-suggestion : hover ,
. typeahead-standalone . my-typeahead . tt-list . tt-suggestion . tt-selected {
color : black;
background-color : white;
} A partir da v4.0 , o JS e o CSS foram separados permitindo maior controle sobre o estilo. Todo o CSS pode ser recuperado do CDN ou abaixo e copiado diretamente para o seu projeto, permitindo descartar/substituir quaisquer estilos conforme necessário.
/***** basic styles *****/
. typeahead-standalone {
position : relative;
text-align : left;
color : # 000 ;
}
. typeahead-standalone . tt-input {
z-index : 1 ;
background : transparent;
position : relative;
}
. typeahead-standalone . tt-hint {
position : absolute;
left : 0 ;
cursor : default;
user-select : none;
background : # fff ;
color : silver;
z-index : 0 ;
}
. typeahead-standalone . tt-list {
background : # fff ;
z-index : 1000 ;
box-sizing : border-box;
overflow : auto;
border : 1 px solid rgba ( 50 , 50 , 50 , 0.6 );
border-radius : 4 px ;
box-shadow : 0 px 10 px 30 px 0 px rgba ( 0 , 0 , 0 , 0.1 );
position : absolute;
max-height : 70 vh ;
}
. typeahead-standalone . tt-list . tt-hide {
display : none;
}
. typeahead-standalone . tt-list div [ class ^= "tt-" ] {
padding : 0 4 px ;
}
. typeahead-standalone . tt-list . tt-suggestion : hover ,
. typeahead-standalone . tt-list . tt-suggestion . tt-selected {
background : # 55acee ;
cursor : pointer;
}
. typeahead-standalone . tt-list . tt-suggestion . tt-highlight {
font-weight : 900 ;
}
. typeahead-standalone . tt-list . tt-group {
background : # eee ;
}Você também pode usar modelos para adicionar um cabeçalho, rodapé e estilizar ainda mais cada sugestão.
Os modelos podem ser usados para personalizar a renderização da Lista. Seu uso é totalmente opcional. Atualmente, existem 7 modelos disponíveis -
templates: {
header : ( resultSet ) => '<h1>List of Countries</h1>' , /* Rendered at the top of the dataset */
footer : ( resultSet ) => '<div>See more</div>' , /* Rendered at the bottom of the dataset */
suggestion : ( item , resultSet ) => { /* Used to render a single suggestion */
return `<div class="custom-suggestion"> ${ item . label } </div>` ;
} ,
group : ( groupName , resultSet ) => { /* Used to render a group */
return `<div class="custom-group"> ${ groupName } </div>` ;
} ,
empty : ( resultSet ) => { /* Rendered when the input query is empty */
return `<div>Search for Colors...</div>` ;
// OR (to display some suggestions by default)
return [ { title : "France" } , { title : "Spain" } ] ;
}
loader : ( ) = > 'Loading...' , /* Rendered while awaiting data from a remote source */
notFound : ( resultSet ) => '<span>Nothing Found</span>' , /* Rendered if no suggestions are available */
} Como visto acima, cada modelo recebe um retorno de chamada que deve retornar uma string que posteriormente será interpretada como HTML. Os templates também recebem um parâmetro resultSet que possui uma estrutura conforme mostrado abaixo.
resultSet = {
query : '...' , // the input query
hits : [ ... ] , // found suggestions
count : 0 , // the total suggestions found in the search index
limit : 5 , // the number of suggestions to show
wrapper : DOMElement , // the container DOM element
} Para facilitar o estilo, cada modelo é encapsulado em um elemento div com uma classe correspondente. ou seja
header => classe tt-headerfooter => classe tt-footersuggestion => aula tt-suggestiongroup => classe tt-grouploader => classe tt-loaderempty => classe tt-emptynotFound => classe tt-notFound A opção de configuração classNames simplesmente permite que você substitua os nomes de classe padrão conforme sua escolha.
Os nomes de classe padrão usados no typeahead são os seguintes:
const classNames = {
wrapper : 'typeahead-standalone' , /* main container element */
input : 'tt-input' ,
hint : 'tt-hint' ,
highlight : 'tt-highlight' ,
list : 'tt-list' , /* container element for suggestions */
hide : 'tt-hide' ,
show : 'tt-show' ,
selected : 'tt-selected' ,
/* classes used within templates */
header : 'tt-header' ,
footer : 'tt-footer' ,
loader : 'tt-loader' ,
suggestion : 'tt-suggestion' ,
group : 'tt-group' ,
empty : 'tt-empty' ,
notFound : 'tt-notFound' ,
} ;Por exemplo, se você quiser usar um nome de classe diferente para o elemento de entrada , poderá inicializar o typeahead assim -
typeahead ( {
input : '...' ,
source : '...' ,
classNames : {
input : 'my-custom-input-class' // this class is used instead of tt-input
}
} ) ;typeahead.reset()typeahead.addToIndex()typeahead.destroy()reset(clearLocalSrc?: boolean) Redefine a instância de digitação antecipada para o estado em que se encontrava antes de qualquer interação do usuário. Remove todos os itens do índice de pesquisa, exceto aqueles que foram adicionados por meio de uma fonte local. Para remover absolutamente todos os itens, a função aceita um parâmetro opcional que deve ser definido como true . Reset() também limpa solicitações remotas armazenadas em cache.
const instance = typeahead ( { /* options */ } ) ;
// clear search index except items added via Local source
instance . reset ( ) ;
// clears entire search index
instance . reset ( true ) ;Esta API é útil em situações em que você precisa invalidar dados após um determinado tempo.
addToIndex()Adiciona itens ao índice de pesquisa. Útil quando você mesmo deseja buscar dados e adicioná-los ao índice de pesquisa. É semelhante a adicionar itens por meio da fonte local.
const instance = typeahead ( { /* options */ } ) ;
instance . reset ( true ) ; // or instance.reset();
instance . addToIndex ( [ 'Blue, Baige , Black' ] ) ; destroy()Destrói a instância de digitação antecipada, limpa o índice de pesquisa, remove todos os manipuladores de eventos e limpa o DOM. Pode ser usado se você deseja desativar a digitação antecipada.
const instance = typeahead ( { /* options */ } ) ;
instance . destroy ( ) ;Aqui está um pequeno glossário dos possíveis códigos de erros que podem ser encontrados
| Código | Descrição |
|---|---|
| e01 | Elemento DOM de entrada ausente |
| e02 | Fonte de sugestões ausente/incorreta. Você deve fornecer pelo menos uma das 3 fontes possíveis - local, pré-busca ou remota com o formato de origem esperado (Ref) |
| e03 | Chaves ausentes |
| e04 | Falha na solicitação de pré-busca |
| e05 | Falha na solicitação remota |
Interessado em contribuir com recursos e correções?
Leia mais sobre como contribuir.
Veja o registro de alterações
MIT © DigitalFortress
