typeahead standalone
v5.4.0
Una biblioteca de autocompletar independiente, rápida y con todas las funciones
? Reflejos ?
Encuentre aquí documentos detallados con demostraciones en vivo para typeahead-standalone.js .
Vista previa de un ejemplo básico:
# you can install typeahead with npm
$ npm install --save typeahead-standalone
# Alternatively you can use Yarn
$ yarn add typeahead-standaloneLuego incluya la biblioteca en su aplicación/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' ) ;En el contexto del 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 > La biblioteca estará disponible como un objeto global en window.typeahead
Typeahead requiere un elemento input al que adjuntarse y una Data source (local/remota) para mostrar sugerencias.
Aquí hay un ejemplo muy básico (consulte la demostración para ver ejemplos avanzados)
<!-- 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: {...}
}
} ) ; Puede pasar las siguientes opciones de configuración a typeahead-standalone :
| Parámetro | Descripción | Por defecto |
|---|---|---|
input | El elemento de entrada DOM debe pasarse con este parámetro y la escritura anticipada se adjuntará a este campo. | - (Requerido) |
source | Esta es la fuente de datos a partir de la cual se calcularán las sugerencias. La fuente puede ser local, captada previamente o recuperada desde un punto final remoto. Detalles | - (Requerido) |
minLength | Especifique la longitud mínima cuando las sugerencias deberían aparecer en la pantalla. | 1 |
limit | Especifique el número máximo de sugerencias que deben mostrarse. | 5 |
highlight | Las letras coincidentes de la consulta se resaltan en la lista de sugerencias. Se agrega una clase tt-highlight para facilitar el estilo. | true |
autoSelect | Si se establece en verdadero, preselecciona la primera sugerencia mostrada | false |
hint | Actualiza el marcador de posición de entrada para que sea igual a la primera sugerencia coincidente. Se agrega una clase tt-hint para facilitar el estilo. | true |
diacritics | Marcar para habilitar/deshabilitar la búsqueda compatible con signos diacríticos de idioma (es decir, buscar convirtiendo caracteres acentuados en sus contrapartes no acentuadas) | undefined |
classNames: Object | El objeto classNames se puede utilizar para establecer clases personalizadas para cada elemento html que se inyecta en el DOM. Detalles | undefined |
templates | Un objeto que contiene plantillas para encabezado, pie de página, sugerencia, grupo y estado no encontrado. Consulte la sección de plantillas para obtener más información. | undefined |
preventSubmit | Si su elemento de entrada se usa dentro de un elemento de formulario, esta bandera permite evitar la acción de envío predeterminada cuando se presiona la tecla ENTER. | false |
onSubmit(event, selectedItem?) | Cuando desee utilizar la escritura anticipada fuera de un elemento de formulario, este controlador se puede utilizar para procesar/enviar el valor de entrada. Se activa al presionar la tecla ENTER. El primer parámetro es el evento del teclado y el segundo parámetro es el elemento seleccionado o no definido si no se seleccionó ningún elemento. | undefined |
display(selectedItem, event?) => string | Esta devolución de llamada se ejecuta cuando el usuario selecciona un elemento de las sugerencias. La sugerencia/elemento actual se pasa como parámetro y debe devolver una cadena que se establece como valor de entrada. El segundo event de parámetro opcional es un evento de mouse/teclado que se puede usar para rastrear la interacción del usuario o para análisis. El valor predeterminado es null . | Devuelve la representación de cadena del elemento seleccionado. |
tokenizer?: (words: string) => string[] | La función tokenizador se utiliza para dividir la consulta de búsqueda y los datos de búsqueda por caracteres determinados. Esta función es útil cuando desea buscar palabras con guiones o palabras con un determinado prefijo/sufijo. | las palabras están divididas por caracteres de espacio (nueva línea, tabulación, espacios) |
listScrollOptions?: ScrollIntoViewOptions | Permite un control preciso sobre el comportamiento de desplazamiento para una lista grande de sugerencias que necesitan desplazamiento. Estas opciones se pasan a la función scrollIntoView() . Referencia MDN | { block: "nearest", inline: "nearest", behaviour: "auto"} |
retainFocus | Este parámetro es útil para controlar el enfoque al presionar la tecla "Tab" cuando la lista de sugerencias está abierta. Si está habilitado, selecciona la opción resaltada y luego devuelve el foco a la entrada de búsqueda. Si está deshabilitado, al presionar "Tab" se seleccionará la opción resaltada y se desviará el foco al siguiente elemento enfocable en su formulario. | true |
hooks | La opción de configuración de ganchos es útil para ejecutar código arbitrario en momentos específicos del ciclo de vida de la escritura anticipada. Detalles | indefinido |
Esta es la fuente de datos a partir de la cual se proporcionarán sugerencias. Este es el formato esperado del objeto fuente.
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 se utiliza cuando desea proporcionar sugerencias de una fuente local como una variable.prefetch se utiliza cuando desea precargar sugerencias desde un punto final remoto por adelantado. Debe proporcionar el parámetro url que apunta al punto final que devolverá sugerencias. Puede proporcionar un parámetro when opcional que defina cuándo debe ocurrir la solicitud de captación previa. El valor predeterminado es onInit lo que significa que las sugerencias se precargarán tan pronto como se inicialice la escritura anticipada. Puede configurarlo en onFocus , lo que hará que las sugerencias se precarguen solo cuando el usuario enfoque el cuadro de entrada de búsqueda. El indicador done es opcional y se puede usar para deshabilitar la solicitud de captación previa mediante programación. Su valor predeterminado es false . Se establece en true automáticamente cuando los datos se obtienen previamente por primera vez (para evitar múltiples solicitudes de red). Al configurar done: true , no se producirá la solicitud de captación previa. Un caso de uso de ejemplo para hacer esto es cuando utiliza localStorage para almacenar sugerencias, pero localStorage ya había almacenado sugerencias previamente, eliminando así la necesidad de buscar datos previamente. La devolución de llamada del process(suggestions) es opcional. Se ejecuta después de que se produce la solicitud de captación previa. Recibe las sugerencias transformadas como parámetro y, como ejemplo, se puede usar para almacenar las sugerencias recibidas en localStorage para usarlas más adelante.remote se utiliza cuando desea interrogar a un punto final remoto para recuperar datos.remote , debe configurar la url y las opciones wildcard . wildcard se reemplazará con la cadena de búsqueda mientras se ejecuta la solicitud.debounce se utiliza para retrasar la ejecución de solicitudes http (en milisegundos). Es opcional y su valor predeterminado es 200 ms.GET .transform() opcional que se llama inmediatamente después de que el punto final de captación previa/remoto devuelva una respuesta. Puede modificar la respuesta antes de que se procese escribiendo anticipadamente.keys es necesaria cuando la fuente de datos es una matriz de objetos. La primera clave se utiliza para identificar qué propiedad del objeto debe usarse como texto para mostrar las sugerencias. Por ejemplo, digamos que la fuente de datos es algo como esto: /* 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" } ,
...
] Ahora, si deseamos utilizar el texto definido en la propiedad color para que aparezca como sugerencias, entonces las claves deben incluir el color como primera clave. (es decir, keys: ["color"] ).
Si desea agregar más propiedades al índice de búsqueda, también puede especificar esas propiedades en la matriz keys . Esto se puede entender mejor con un ejemplo. Tomemos la misma fuente de datos de ejemplo que se muestra arriba. ¿Qué pasaría si quisiera buscar colores por otra propiedad ( colorCode ) y no solo por su color ? Para hacerlo, simplemente configure keys: ["color", "meta.colorCode"] . Si ahora busca " YW ", aparece la sugerencia "Amarillo" como se esperaba.
groupKey: "shade" , las sugerencias se agruparán según la propiedad " shade ". En este ejemplo, los colores Verde y Oliva aparecerán bajo el grupo " Verdoso " ( shade ), mientras que el color Amarillo no tendrá grupo. groupKey también admite el acceso a propiedades anidadas mediante notación de puntos. (ejemplo: groupKey: "category.title" )identity() se utiliza para determinar la unicidad de cada sugerencia. Recibe la sugerencia como parámetro y debe devolver una cadena única para la sugerencia dada. Esta es una propiedad opcional y de forma predeterminada devuelve el valor asociado con la primera clave, es decir, keys[0] . Sin embargo, es posible que el valor predeterminado no funcione siempre. Por ejemplo, considere el siguiente 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" } ,
...
] Supongamos que las claves están configuradas en keys: ["title"] . De forma predeterminada, la función identity() utiliza la primera clave (es decir, el título ) para determinar la unicidad. Entonces, si busca God , solo encontrará 1 sugerencia, ya que hay 3 canciones con exactamente la misma propiedad title . Para mostrar las 3 sugerencias con diferentes artistas, debe configurar la propiedad identity de modo que devuelva una cadena única:
identity ( item ) = > ` ${ item . title } ${ item . artist } ` ; Se recomienda encarecidamente configurar la opción de configuración identity() para devolver una cadena única cuando su fuente de datos sea una matriz de Objetos.
Consulte los ejemplos en vivo para obtener más aclaraciones.
Actualmente sólo hay 1 gancho disponible:
updateHits: async (resultSet, loader) => Promise<resultSet> que se ejecuta justo antes de que los resultados de la búsqueda se muestren al usuario y se puede utilizar para anular las sugerencias devueltas por el índice de búsqueda. (útil para ordenar, filtrar, agregar o eliminar resultados personalizados. Este enlace es una función asíncrona que le permite realizar solicitudes AJAX para obtener nuevos resultados si es necesario) // 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 : ( ) => { ... } ,
}
} ) ; Algunos estilos básicos se proporcionan con escritura anticipada. La interfaz de usuario depende completamente de usted y se puede personalizar hasta el píxel. Puede utilizar las siguientes clases para agregar/anular estilos.
typeahead-standalone .tt-input .tt-hint .tt-list . (Se agrega una clase tt-hide cuando no hay sugerencias disponibles)tt-suggestion y si se selecciona la sugerencia, entonces tiene una clase tt-selected adicionalmente.tt-highlight . Puede agregar sus propios estilos apuntando al selector principal .typeahead-standalone . Por ejemplo, podemos actualizar el color de fondo de cada sugerencia como se ve a continuación:
/* set background color for each suggestion */
. typeahead-standalone . tt-list . tt-suggestion {
background-color : green;
} Para anular el estilo predeterminado, establezca la opción de configuración className y utilícela como selector. Digamos que configuras className: "my-typeahead" y luego, para anular el estilo al pasar el cursor/seleccionar una sugerencia, puedes 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 de v4.0 , JS y CSS se separaron, lo que permite un mayor control sobre el estilo. El CSS completo se puede recuperar desde la CDN o desde abajo y copiarlo directamente en su proyecto, lo que le permite descartar/anular cualquier estilo según sea necesario.
/***** 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 ;
}También puedes usar plantillas para agregar un encabezado, un pie de página y darle más estilo a cada sugerencia.
Se pueden utilizar plantillas para personalizar la representación de la Lista. Su uso es completamente opcional. Actualmente, hay 7 plantillas disponibles:
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 se vio arriba, cada plantilla recibe una devolución de llamada que debe devolver una string que luego se interpreta como HTML. Las plantillas también reciben un resultSet de parámetros que tiene una estructura como la que se muestra a continuación.
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 el estilo, cada plantilla está envuelta en un elemento div con una clase correspondiente. es decir
header => clase tt-headerfooter => clase tt-footersuggestion => clase tt-suggestiongroup => clase tt-grouploader => clase tt-loaderempty => clase tt-emptynotFound => clase tt-notFound La opción de configuración classNames simplemente le permite reemplazar los nombres de clase predeterminados según su elección.
Los nombres de clase predeterminados utilizados en la escritura anticipada son los siguientes:
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' ,
} ;Como ejemplo, si desea utilizar un nombre de clase diferente para el elemento de entrada , puede inicializar la escritura anticipada de esta manera:
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) Restablece la instancia de escritura anticipada al estado en el que se encontraba antes de cualquier interacción del usuario. Elimina todos los elementos del índice de búsqueda excepto aquellos que se agregaron a través de una fuente local. Para eliminar absolutamente todos los elementos, la función acepta un parámetro opcional que debe establecerse en true . Reset() también borra las solicitudes remotas almacenadas en caché.
const instance = typeahead ( { /* options */ } ) ;
// clear search index except items added via Local source
instance . reset ( ) ;
// clears entire search index
instance . reset ( true ) ;Esta API es útil en situaciones en las que necesita invalidar datos después de que haya transcurrido un cierto tiempo.
addToIndex()Agrega elementos al índice de búsqueda. Útil cuando desea recuperar datos usted mismo y luego agregarlos al índice de búsqueda. Es similar a agregar elementos a través de la fuente local.
const instance = typeahead ( { /* options */ } ) ;
instance . reset ( true ) ; // or instance.reset();
instance . addToIndex ( [ 'Blue, Baige , Black' ] ) ; destroy()Destruye la instancia de escritura anticipada, borra el índice de búsqueda, elimina todos los controladores de eventos y limpia el DOM. Se puede utilizar si desea desactivar la escritura anticipada.
const instance = typeahead ( { /* options */ } ) ;
instance . destroy ( ) ;Aquí tienes un pequeño glosario de los posibles códigos de error con los que te puedes encontrar
| Código | Descripción |
|---|---|
| e01 | Falta elemento DOM de entrada |
| e02 | Fuente de sugerencias faltante/incorrecta. Debe proporcionar al menos una de las 3 fuentes posibles: local, captación previa o remota con el formato de fuente esperado (Ref) |
| e03 | llaves faltantes |
| e04 | Error en la solicitud de captación previa |
| e05 | Error en la solicitud remota |
¿Está interesado en contribuir con funciones y correcciones?
Lea más sobre cómo contribuir.
Ver el registro de cambios
MIT © Fortaleza Digital
