typeahead standalone
v5.4.0
Pustaka pelengkapan otomatis mandiri berfitur lengkap dan cepat
? Sorotan?
Temukan di sini Dokumen terperinci dengan Demo Langsung untuk typeahead-standalone.js .
Pratinjau contoh dasar:
# you can install typeahead with npm
$ npm install --save typeahead-standalone
# Alternatively you can use Yarn
$ yarn add typeahead-standaloneKemudian sertakan perpustakaan di Aplikasi/Halaman Anda.
Sebagai sebuah modul,
// 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' ) ;Dalam konteks peramban,
<!-- 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 > Perpustakaan akan tersedia sebagai objek global di window.typeahead
Typeahead memerlukan Elemen input untuk dilampirkan, dan Data source (lokal/jarak jauh) untuk menampilkan saran.
Berikut adalah contoh yang sangat mendasar (Lihat demo untuk contoh lanjutan)
<!-- 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: {...}
}
} ) ; Anda dapat meneruskan opsi konfigurasi berikut ke typeahead-standalone :
| Parameter | Keterangan | Bawaan |
|---|---|---|
input | Elemen input DOM harus diteruskan dengan parameter ini dan typeahead akan melampirkan dirinya ke bidang ini. | - (Diperlukan) |
source | Ini adalah sumber Data yang sarannya akan dihitung. Sumbernya bisa bersifat lokal, diambil sebelumnya, atau diambil dari titik akhir jarak jauh. Detail | - (Diperlukan) |
minLength | Tentukan panjang minimum kapan saran akan muncul di layar. | 1 |
limit | Tentukan jumlah maksimum saran yang harus ditampilkan. | 5 |
highlight | Huruf yang cocok dari kueri disorot dalam daftar saran. tt-highlight ditambahkan untuk memfasilitasi penataan | true |
autoSelect | Jika disetel ke true, pilih terlebih dahulu saran yang pertama kali ditampilkan | false |
hint | Memperbarui placeholder masukan agar sama dengan saran pertama yang cocok. tt-hint kelas ditambahkan untuk memfasilitasi penataan | true |
diacritics | Tandai untuk mengaktifkan/menonaktifkan pencarian yang didukung diakritik bahasa (yaitu pencarian dengan mengubah karakter beraksen menjadi karakter non-aksen) | undefined |
classNames: Object | Objek classNames dapat digunakan untuk mengatur kelas khusus untuk setiap elemen html yang dimasukkan ke dalam DOM. Detail | undefined |
templates | Objek yang berisi templat untuk header, footer, saran, grup, dan status notFound. Lihat bagian templat untuk klarifikasi | undefined |
preventSubmit | Jika elemen masukan Anda digunakan di dalam elemen formulir, tanda ini memungkinkan untuk mencegah tindakan pengiriman default saat tombol ENTER ditekan. | false |
onSubmit(event, selectedItem?) | Saat Anda ingin menggunakan typeahead di luar elemen form, handler ini dapat digunakan untuk memproses/mengirimkan nilai input. Terpicu saat menekan tombol ENTER. Parameter pertama adalah keyboard Event dan parameter ke-2 adalah item yang dipilih atau tidak ditentukan jika tidak ada item yang dipilih | undefined |
display(selectedItem, event?) => string | Panggilan balik ini dijalankan ketika pengguna memilih item dari saran. Saran/item saat ini diteruskan sebagai parameter dan harus mengembalikan string yang ditetapkan sebagai nilai input. event parameter opsional ke-2 adalah peristiwa Mouse/Keyboard yang dapat digunakan untuk melacak interaksi pengguna atau untuk analisis. Standarnya adalah null . | Mengembalikan representasi string dari item yang dipilih |
tokenizer?: (words: string) => string[] | Fungsi tokenizer digunakan untuk membagi permintaan pencarian dan data pencarian berdasarkan karakter tertentu. Fungsi ini berguna ketika Anda ingin mencari kata-kata yang diberi tanda penghubung atau kata-kata dengan awalan/akhiran tertentu | kata-kata dipisahkan berdasarkan karakter spasi (baris baru, tab, spasi) |
listScrollOptions?: ScrollIntoViewOptions | Memungkinkan kontrol yang baik atas perilaku gulir untuk daftar besar saran yang perlu digulir. Opsi ini diteruskan ke fungsi scrollIntoView() . Referensi MDN | { block: "nearest", inline: "nearest", behaviour: "auto"} |
retainFocus | Parameter ini berguna untuk mengontrol fokus penekanan tombol "Tab" saat daftar saran terbuka. Jika diaktifkan, ini akan memilih opsi yang disorot & kemudian mengembalikan fokus ke input pencarian. Jika dinonaktifkan, menekan "Tab" akan memilih opsi yang disorot & mengalihkan fokus ke item yang dapat difokuskan berikutnya di formulir Anda | true |
hooks | Opsi konfigurasi hooks berguna untuk mengeksekusi kode arbitrer pada momen tertentu dalam siklus hidup typeahead. Detail | belum diartikan |
Ini adalah sumber data dari mana saran akan diberikan. Ini adalah format yang diharapkan dari objek sumber.
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 digunakan ketika Anda ingin memberikan saran dari sumber lokal seperti variabel.prefetch digunakan ketika Anda ingin melakukan pramuat saran dari titik akhir jarak jauh terlebih dahulu. Anda harus memberikan parameter url yang menunjuk ke titik akhir yang akan mengembalikan saran. Anda dapat memberikan parameter when opsional yang menentukan kapan permintaan prefetch harus dilakukan. Defaultnya adalah onInit yang berarti bahwa saran akan dimuat segera setelah typeahead diinisialisasi. Anda dapat mengaturnya ke onFocus yang akan menyebabkan saran dimuat sebelumnya hanya ketika pengguna memfokuskan kotak input pencarian. Tanda done bersifat opsional & dapat digunakan untuk menonaktifkan permintaan pengambilan awal secara terprogram. Nilai defaultnya adalah false . Ini akan disetel ke true secara otomatis saat data diambil terlebih dahulu untuk pertama kalinya (untuk mencegah beberapa permintaan jaringan). Dengan pengaturan done: true , permintaan prefetch tidak akan terjadi. Contoh kasus penggunaan untuk melakukan hal ini adalah ketika Anda menggunakan localStorage untuk menyimpan saran tetapi localStorage telah menyimpan saran sebelumnya sehingga menghilangkan kebutuhan untuk mengambil data terlebih dahulu lagi. Panggilan balik process(suggestions) bersifat opsional. Itu dieksekusi setelah permintaan prefetch terjadi. Ia menerima saran yang diubah sebagai parameter & sebagai contoh dapat digunakan untuk menyimpan saran yang diterima di Penyimpanan lokal untuk digunakan nanti.remote digunakan saat Anda ingin menginterogasi titik akhir jarak jauh untuk mengambil data.remote , Anda harus mengatur url dan opsi wildcard . wildcard akan diganti dengan string pencarian saat menjalankan permintaan.debounce digunakan untuk menunda eksekusi permintaan http (dalam milidetik). Ini opsional & defaultnya adalah 200ms.GET .transform() opsional yang dipanggil segera setelah titik akhir prefetch/jarak jauh mengembalikan respons. Anda dapat mengubah respons sebelum diproses dengan mengetik terlebih dahulu.keys diperlukan ketika sumber data adalah array objek. Kunci pertama digunakan untuk mengidentifikasi properti objek mana yang harus digunakan sebagai teks untuk menampilkan saran. Misalnya, sumber datanya seperti ini: /* 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" } ,
...
] Sekarang jika kita ingin menggunakan teks yang ditentukan dalam properti color untuk muncul sebagai saran, maka kuncinya harus menyertakan warna sebagai kunci pertama. (yaitu keys: ["color"] ).
Jika Anda ingin menambahkan lebih banyak properti ke indeks pencarian, Anda dapat menentukan properti tersebut juga di array keys . Hal ini paling baik dipahami dengan sebuah contoh. Mari kita ambil contoh sumber data yang sama seperti yang ditunjukkan di atas. Bagaimana jika Anda ingin mencari warna berdasarkan properti lain ( colorCode ) dan bukan hanya berdasarkan color ? Untuk melakukannya, cukup atur keys: ["color", "meta.colorCode"] . Jika sekarang Anda mencari " YW ", saran "Kuning" muncul seperti yang diharapkan.
groupKey: "shade" , saran akan dikelompokkan berdasarkan properti " shade ". Dalam contoh ini, warna Hijau dan Zaitun akan muncul di bawah grup " Kehijauan " ( shade ) sedangkan warna Kuning tidak memiliki grup. groupKey juga mendukung akses properti bersarang menggunakan notasi titik. (contoh - groupKey: "category.title" )identity() digunakan untuk menentukan keunikan setiap saran. Ia menerima saran sebagai parameter dan harus mengembalikan string unik untuk saran yang diberikan. Ini adalah properti opsional dan secara default mengembalikan nilai yang terkait dengan kunci pertama yaitu keys[0] . Namun, nilai default mungkin tidak selalu berfungsi. Misalnya, pertimbangkan kode berikut - /* 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" } ,
...
] Mari kita asumsikan kunci disetel ke keys: ["title"] . Secara default fungsi identity() menggunakan kunci pertama (yaitu title ) untuk menentukan keunikan. Jadi jika Anda mencari God , Anda hanya akan menemukan 1 saran yang ditampilkan karena ada 3 lagu dengan properti title yang sama persis . Untuk menampilkan ketiga saran dengan artis berbeda, Anda perlu menyetel properti identity sedemikian rupa sehingga mengembalikan string unik -
identity ( item ) = > ` ${ item . title } ${ item . artist } ` ; Sangat disarankan untuk mengatur opsi konfigurasi identity() untuk mengembalikan string unik ketika sumber data Anda adalah array Objek.
Lihat Contoh Langsung untuk klarifikasi lebih lanjut.
Saat ini hanya tersedia 1 pengait:
updateHits: async (resultSet, loader) => Promise<resultSet> yang dijalankan tepat sebelum hasil pencarian ditampilkan kepada pengguna & dapat digunakan untuk mengesampingkan saran yang dikembalikan oleh indeks pencarian. (berguna untuk pengurutan khusus, pemfilteran, penambahan atau penghapusan hasil. Kait ini adalah fungsi asinkron yang memungkinkan Anda membuat permintaan AJAX untuk mengambil hasil baru jika diperlukan) // 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 : ( ) => { ... } ,
}
} ) ; Beberapa gaya dasar disediakan dengan typeahead. UI sepenuhnya terserah Anda dan dapat disesuaikan hingga pikselnya. Anda dapat menggunakan kelas berikut untuk menambahkan/mengganti gaya.
typeahead-standalone .tt-input .tt-hint .tt-list . ( tt-hide kelas ditambahkan ketika tidak ada saran yang tersedia)tt-suggestion dan jika saran tersebut dipilih, maka saran tersebut memiliki kelas tambahan tt-selected .tt-highlight . Anda dapat menambahkan gaya Anda sendiri dengan menargetkan pemilih induk .typeahead-standalone . Misalnya, kami dapat memperbarui warna latar belakang setiap saran seperti yang terlihat di bawah -
/* set background color for each suggestion */
. typeahead-standalone . tt-list . tt-suggestion {
background-color : green;
} Untuk mengganti gaya default, setel opsi konfigurasi className dan gunakan sebagai pemilih. Katakanlah Anda menyetel className: "my-typeahead" , lalu untuk mengganti gaya saat mengarahkan/memilih saran, Anda dapat menggunakan:
/* 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;
} Dimulai dengan v4.0 , JS dan CSS telah dipisahkan sehingga memungkinkan kontrol yang lebih besar terhadap gaya. Seluruh css dapat diambil baik dari CDN atau dari bawah dan disalin langsung ke proyek Anda sehingga memungkinkan Anda membuang/mengganti gaya apa pun jika diperlukan.
/***** 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 ;
}Anda juga dapat menggunakan templat untuk menambahkan header, footer, dan gaya lebih lanjut pada setiap saran.
Templat dapat digunakan untuk menyesuaikan rendering Daftar. Penggunaannya sepenuhnya opsional. Saat ini, ada 7 template yang tersedia -
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 */
} Seperti yang terlihat di atas, setiap template mengambil panggilan balik yang harus mengembalikan string yang kemudian diinterpretasikan sebagai HTML. Templat juga menerima parameter resultSet yang memiliki struktur seperti yang ditunjukkan di bawah ini.
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
} Untuk memfasilitasi penataan gaya, setiap templat dibungkus dalam elemen div dengan kelas yang sesuai. yaitu
header => kelas tt-headerfooter => kelas tt-footersuggestion => tt-suggestiongroup => kelas tt-grouploader => kelas tt-loaderempty => kelas tt-emptynotFound => kelas tt-notFound Opsi konfigurasi classNames memungkinkan Anda mengganti nama kelas default sesuai pilihan Anda.
Nama kelas default yang digunakan dalam typeahead adalah sebagai berikut:
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' ,
} ;Sebagai contoh, jika Anda ingin menggunakan nama kelas yang berbeda untuk elemen masukan , Anda dapat menginisialisasi typeahead seperti ini -
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) Menyetel ulang instance typeahead ke keadaan sebelum interaksi pengguna apa pun. Ini menghapus semua item dari indeks pencarian kecuali yang ditambahkan melalui sumber lokal. Untuk benar-benar menghapus semua item, fungsi menerima parameter opsional yang harus disetel ke true . Reset() juga menghapus permintaan jarak jauh yang di-cache.
const instance = typeahead ( { /* options */ } ) ;
// clear search index except items added via Local source
instance . reset ( ) ;
// clears entire search index
instance . reset ( true ) ;API ini berguna dalam situasi di mana Anda perlu membuat data tidak valid setelah waktu tertentu berlalu.
addToIndex()Menambahkan item ke indeks pencarian. Berguna ketika Anda ingin mengambil data sendiri dan kemudian menambahkannya ke indeks pencarian. Hal ini mirip dengan menambahkan item melalui sumber Lokal.
const instance = typeahead ( { /* options */ } ) ;
instance . reset ( true ) ; // or instance.reset();
instance . addToIndex ( [ 'Blue, Baige , Black' ] ) ; destroy()Hancurkan instance typeahead, hapus indeks pencarian, hapus semua event handler dan bersihkan DOM. Dapat digunakan jika Anda ingin menonaktifkan typeahead.
const instance = typeahead ( { /* options */ } ) ;
instance . destroy ( ) ;Berikut adalah glosarium kecil tentang kemungkinan kode kesalahan yang mungkin ditemui
| Kode | Keterangan |
|---|---|
| e01 | Elemen DOM masukan tidak ada |
| e02 | Sumber saran tidak ada/salah. Anda harus menyediakan setidaknya satu dari 3 sumber yang mungkin - lokal, prefetch, atau jarak jauh dengan format sumber yang diharapkan (Ref) |
| e03 | Kunci Hilang |
| e04 | Permintaan pengambilan awal gagal |
| e05 | Permintaan jarak jauh gagal |
Tertarik untuk menyumbangkan fitur dan perbaikan?
Baca lebih lanjut tentang berkontribusi.
Lihat Changelog
MIT © Benteng Digital
