typeahead standalone
v5.4.0
快速、功能齊全的獨立自動完成庫
？亮點？
在這裡找到typeahead-standalone.js的詳細文件和即時演示。
基本範例預覽：
# you can install typeahead with npm
$ npm install --save typeahead-standalone
# Alternatively you can use Yarn
$ yarn add typeahead-standalone然後將該庫包含在您的應用程式/頁面中。
作為一個模組，
// 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' ) ;在瀏覽器上下文中，
<!-- 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 >該庫將在window.typeahead中作為全域物件提供
Typeahead 需要一個input元素來附加自身，以及一個Data source （本地/遠端）來顯示建議。
這是一個非常基本的範例（有關進階範例，請參閱演示）
<!-- 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: {...}
}
} ) ; 您可以將以下設定選項傳遞給typeahead-standalone ：
| 範圍 | 描述 | 預設 |
|---|---|---|
input | DOM 輸入元素必須與此參數一起傳遞，並且 typeahead 會將其附加到此欄位。 | - （必需的） |
source | 這是計算建議的資料來源。來源可以是本地的、預先取的或從遠端端點檢索的。細節 | - （必需的） |
minLength | 指定螢幕上應顯示建議的最小長度。 | 1 |
limit | 指定應顯示的最大建議數。 | 5 |
highlight | 查詢中符合的字母會在建議清單中反白。增加了一個tt-highlight類，方便造型 | true |
autoSelect | 如果設定為 true，則預先選擇第一個顯示的建議 | false |
hint | 將輸入佔位符更新為等於第一個符合的建議。新增了tt-hint類別以方便樣式設定 | true |
diacritics | 啟用/停用語言變音符號支援搜尋的標誌（即透過將重音字元轉換為非重音字元進行搜尋） | undefined |
classNames: Object | classNames 物件可用於為 DOM 中註入的每個 html 元素設定自訂類別。細節 | undefined |
templates | 包含頁首、頁尾、建議、群組和未找到狀態範本的物件。請參閱範本部分以取得說明 | undefined |
preventSubmit | 如果您的輸入元素在表單元素內使用，則此標誌允許阻止按下 ENTER 鍵時的預設提交操作。 | false |
onSubmit(event, selectedItem?) | 當您想要在表單元素之外使用 typeahead 時，可以使用此處理程序來處理/提交輸入值。按 ENTER 鍵時觸發。第一個參數是鍵盤事件，第二個參數是所選項目，如果未選擇任何項目，則未定義 | undefined |
display(selectedItem, event?) => string | 當使用者從建議中選擇一個項目時，將執行此回調。目前建議/項目作為參數傳遞，它必須傳回一個設定為輸入值的字串。第二個可選參數event是滑鼠/鍵盤事件，可用於追蹤使用者互動或進行分析。它預設為null 。 | 傳回所選項目目的字串表示形式 |
tokenizer?: (words: string) => string[] | 分詞器函數用於按給定字元分割搜尋查詢和搜尋資料。當您希望搜尋連字符或具有特定前綴/後綴的單字時，此功能非常有用 | 單字以空格字元分割（換行符號、製表符、空格） |
listScrollOptions?: ScrollIntoViewOptions | 允許對需要滾動的大量建議的滾動行為進行精細控制。這些選項被傳遞給scrollIntoView()函數。 MDN 參考 | { block: "nearest", inline: "nearest", behaviour: "auto"} |
retainFocus | 此參數可用於控制建議清單開啟時按下「Tab」鍵的焦點。如果啟用，它將選擇突出顯示的選項，然後將焦點返回搜尋輸入。如果停用，按「Tab」將選擇突出顯示的選項並將焦點移至表單中的下一個可聚焦項目 | true |
hooks | hooks 設定選項對於在 typeahead 生命週期中的特定時刻執行任意程式碼非常有用。細節 | 不明確的 |
這是提供建議的資料來源。這是來源物件的預期格式。
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資料來源。prefetch資料來源。您必須提供指向將傳回建議的端點的url參數。您可以提供一個可選的when參數，定義何時應發生預取請求。它預設為onInit這意味著一旦 typeahead 初始化，建議就會預先載入。您可以將其設定為onFocus這將導致僅當使用者聚焦搜尋輸入框時才預先載入建議。 done標誌是可選的，可用於以程式設計方式停用預取請求。它的預設值為false 。當第一次預取資料時，它會自動設定為true （以防止多個網路請求）。透過設定done: true ，預取請求將不會發生。執行此操作的範例用例是，當您使用localStorage儲存建議，但localStorage之前已經儲存了建議，從而無需再次預取資料。 process(suggestions)回調是可選的。它在預取請求發生後執行。它接收轉換後的建議作為參數，並且作為範例可用於將接收到的建議儲存在localStorage中以供稍後使用。remote資料來源。remote資料來源時，必須設定url和wildcard選項。執行請求時， wildcard將替換為搜尋字串。debounce選項用於延遲 http 請求的執行（以毫秒為單位）。它是可選的，預設為 200ms。GET 。transform()函數，在預取/遠端端點回傳回應後立即被呼叫。您可以在 typeahead 處理回應之前對其進行修改。keys數組。第一個鍵用於標識應將物件的哪個屬性用作顯示建議的文字。例如，假設資料來源是這樣的： /* 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" } ,
...
]現在，如果我們希望使用color屬性中定義的文字作為建議顯示，則鍵必須包含顏色作為第一個鍵。 （即keys: ["color"] ）。
如果您希望為搜尋索引新增更多屬性，您也可以在keys數組中指定這些屬性。透過一個例子可以最好地理解這一點。讓我們採用與上面所示相同的範例資料來源。如果您想透過另一個屬性（ colorCode ）而不只是透過其顏色搜尋顏色怎麼辦？為此，只需設定keys: ["color", "meta.colorCode"] 。如果您現在搜尋“ YW ”，則會按預期彈出建議“黃色”。
groupKey: "shade"時，建議將按屬性「 shade 」進行分組。在此範例中，綠色和橄欖色將出現在「綠色」（ shade ）組下，而黃色將沒有組。 groupKey也支援使用點表示法存取嵌套屬性。 （範例 - groupKey: "category.title" ）identity()函數用來決定每個建議的唯一性。它接收建議作為參數，並且必須傳回給定建議唯一的字串。這是一個可選屬性，預設傳回與第一個鍵（即keys[0]關聯的值。但是，預設值可能並非每次都有效。例如，考慮以下程式碼 - /* 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" } ,
...
]假設鍵設定為keys: ["title"] 。預設情況下， identity()函數使用第一個鍵（即title ）來決定唯一性。因此，如果您搜尋God ，您會發現僅顯示 1 個建議，因為有 3 首歌曲具有完全相同的title屬性。為了顯示不同藝術家的所有 3 個建議，您需要設定identity屬性，使其傳回一個唯一的字串 -
identity ( item ) = > ` ${ item . title } ${ item . artist } ` ;當您的資料來源是物件陣列時，強烈建議設定identity()配置選項以傳回唯一的字串。
查看即時範例以取得進一步說明。
目前只有 1 個可用的鉤子：
updateHits: async (resultSet, loader) => Promise<resultSet>在搜尋結果顯示給使用者之前執行，可用來覆寫搜尋索引傳回的建議。 （對於自訂排序、過濾、新增或刪除結果很有用。這個鉤子是一個非同步函數，可讓您在需要時發出 AJAX 請求來取得新結果） // 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 : ( ) => { ... } ,
}
} ) ; typeahead 提供了一些基本樣式。使用者介面完全由您決定，並且可以根據像素進行自訂。您可以使用以下類別來新增/覆蓋樣式。
typeahead-standalone類別的容器中。tt-input類別。tt-hint類別。tt-list類別的容器中。 （當沒有建議可用時，請新增一個類別tt-hide ）tt-suggestion類，如果該建議被選擇，那麼它還有一個tt-selected類。tt-highlight類別。您可以透過定位父選擇器.typeahead-standalone來新增自己的樣式。例如，我們可以更新每個建議的背景顏色，如下所示 -
/* set background color for each suggestion */
. typeahead-standalone . tt-list . tt-suggestion {
background-color : green;
}若要覆寫預設樣式，請設定配置選項className並將其用作選擇器。假設您設定了className: "my-typeahead" ，然後要覆寫懸停/選擇建議時的樣式，您可以使用：
/* 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;
}從v4.0開始，JS 和 CSS 已經分離，可以更好地控制樣式。整個 CSS 可以從 CDN 或下面檢索，並直接複製到您的專案中，讓您可以根據需要丟棄/覆蓋任何樣式。
/***** 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 ;
}您也可以使用範本新增頁首、頁尾並進一步設定每個建議的樣式。
模板可用於自訂清單的呈現。它們的使用完全是可選的。目前，有 7 個模板可用 -
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 */
}如上所示，每個模板都需要一個回調，該回調必須傳回一個string ，該字串稍後被解釋為 HTML。模板也會接收一個參數resultSet ，其結構如下所示。
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
}為了方便樣式設置，每個模板都包裝在具有相應類別的div元素中。 IE
header => 類別tt-headerfooter => tt-footer類suggestion => 類別tt-suggestiongroup => 類別tt-grouploader => 類別tt-loaderempty => 類別tt-emptynotFound => 類別tt-notFoundclassNames配置選項僅允許您根據您的選擇替換預設的類別名稱。
typeahead 中使用的預設類別名稱如下：
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' ,
} ;例如，如果您想要為輸入元素使用不同的類別名，您可以像這樣初始化 typeahead -
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)將預輸入實例重設為任何使用者互動之前的狀態。它會從搜尋索引中刪除所有項目（透過本機來源新增的項目除外）。若要絕對刪除所有項目，函數接受一個可選參數，該參數應設為true 。 Reset() 也會清除快取的遠端請求。
const instance = typeahead ( { /* options */ } ) ;
// clear search index except items added via Local source
instance . reset ( ) ;
// clears entire search index
instance . reset ( true ) ;當您需要在經過一定時間後使資料失效時，此 API 非常有用。
addToIndex()將項目新增至搜尋索引。當您想要自己獲取資料然後將其新增至搜尋索引時很有用。它類似於透過本地來源添加項目。
const instance = typeahead ( { /* options */ } ) ;
instance . reset ( true ) ; // or instance.reset();
instance . addToIndex ( [ 'Blue, Baige , Black' ] ) ; destroy()銷毀 typeahead 實例，清除搜尋索引，刪除所有事件處理程序並清理 DOM。如果您想停用預輸入，可以使用它。
const instance = typeahead ( { /* options */ } ) ;
instance . destroy ( ) ;以下是可能遇到的錯誤代碼的一個小詞彙表
| 程式碼 | 描述 |
|---|---|
| e01 | 缺少輸入 DOM 元素 |
| e02 | 建議來源缺失/不正確。您必須至少提供 3 種可能的來源之一 - 本地、預取或遠端，並具有預期的來源格式（參考） |
| e03 | 鑰匙遺失 |
| e04 | 預取請求失敗 |
| e05 | 遠端請求失敗 |
有興趣貢獻功能和修復嗎？
閱讀更多關於貢獻的內容。
查看變更日誌
麻省理工學院 © DigitalFortress
