빠르고 모든 기능을 갖춘 독립형 자동 완성 라이브러리
? 하이라이트?
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 입력 요소는 이 매개변수와 함께 전달되어야 하며 자동 완성 기능은 이 필드에 연결됩니다. | - (필수의) |
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 | 머리글, 바닥글, 제안, 그룹 및 notFound 상태에 대한 템플릿이 포함된 개체입니다. 자세한 내용은 템플릿 섹션을 참조하세요. | undefined |
preventSubmit | 입력 요소가 양식 요소 내에서 사용되는 경우 이 플래그를 사용하면 ENTER 키를 눌렀을 때 기본 제출 작업을 방지할 수 있습니다. | false |
onSubmit(event, selectedItem?) | 양식 요소 외부에서 자동 완성 기능을 사용하려는 경우 이 핸들러를 사용하여 입력 값을 처리/제출할 수 있습니다. 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
입니다. 이는 자동 입력이 초기화되자마자 제안이 미리 로드된다는 의미입니다. 사용자가 검색 입력 상자에 초점을 맞출 때만 제안이 미리 로드되도록 onFocus
로 설정할 수 있습니다. done
플래그는 선택 사항이며 프로그래밍 방식으로 프리페치 요청을 비활성화하는 데 사용할 수 있습니다. 기본값은 false
입니다. 데이터가 처음으로 프리페치되면 자동으로 true
로 설정됩니다(여러 네트워크 요청을 방지하기 위해). done: true
설정하면 프리페치 요청이 발생하지 않습니다. 이를 수행하는 사용 사례의 예는 제안을 저장하기 위해 localStorage를 사용하지만 이전에 localStorage에 제안이 이미 저장되어 있으므로 데이터를 다시 미리 가져올 필요가 없는 경우입니다. process(suggestions)
콜백은 선택사항입니다. 프리페치 요청이 발생한 후에 실행됩니다. 변환된 제안을 매개변수로 수신하며, 예를 들어 수신된 제안을 나중에 사용할 수 있도록 localStorage 에 저장하는 데 사용할 수 있습니다.remote
데이터 원본은 데이터를 가져오기 위해 원격 끝점을 조사하려는 경우에 사용됩니다.remote
데이터소스 사용시 url
과 wildcard
옵션을 설정해야 합니다. 요청을 실행하는 동안 wildcard
검색 문자열로 대체됩니다.debounce
옵션은 http 요청 실행을 지연하는 데 사용됩니다(밀리초 단위). 선택 사항이며 기본값은 200ms입니다.GET
입니다.transform()
함수를 제공할 수 있습니다. 자동 완성 기능으로 처리되기 전에 응답을 수정할 수 있습니다.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 "를 검색하면 예상대로 "Yellow"라는 제안이 나타납니다.
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
을 검색하면 title
속성이 완전히 동일한 노래가 3개 있으므로 제안 항목이 1개만 표시됩니다. 서로 다른 아티스트의 제안 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 : ( ) => { ... } ,
}
} ) ;
일부 기본 스타일은 자동 완성 기능으로 제공됩니다. UI는 전적으로 사용자에게 달려 있으며 픽셀 단위로 사용자 정의할 수 있습니다. 다음 클래스를 사용하여 스타일을 추가/재정의할 수 있습니다.
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 */
}
위에서 볼 수 있듯이 각 템플릿은 나중에 HTML로 해석되는 string
반환해야 하는 콜백을 사용합니다. 또한 템플릿은 아래와 같은 구조를 갖는 매개변수 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
요소로 래핑됩니다. 즉
header
=> 클래스 tt-header
footer
=> 클래스 tt-footer
suggestion
=> 클래스 tt-suggestion
group
=> 클래스 tt-group
loader
=> 클래스 tt-loader
empty
=> 클래스 tt-empty
notFound
=> 클래스 tt-notFound
classNames
구성 옵션을 사용하면 원하는 대로 기본 클래스 이름을 바꿀 수 있습니다.
자동 완성 내에서 사용되는 기본 클래스 이름은 다음과 같습니다.
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 ( {
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()
자동 완성 인스턴스를 삭제하고, 검색 색인을 지우고, 모든 이벤트 핸들러를 제거하고, DOM을 정리합니다. 자동 완성 기능을 비활성화하려는 경우 사용할 수 있습니다.
const instance = typeahead ( { /* options */ } ) ;
instance . destroy ( ) ;
다음은 발생할 수 있는 오류 코드에 대한 작은 용어집입니다.
암호 | 설명 |
---|---|
e01 | 입력 DOM 요소가 누락되었습니다. |
e02 | 제안 항목이 누락되었거나 잘못되었습니다. 예상되는 소스 형식(Ref)을 사용하여 로컬, 프리페치 또는 원격의 3가지 가능한 소스 중 하나 이상을 제공해야 합니다. |
e03 | 누락된 키 |
e04 | 프리페치 요청이 실패했습니다. |
e05 | 원격 요청 실패 |
기능 및 수정 사항을 제공하는 데 관심이 있으십니까?
기여에 대해 자세히 알아보세요.
변경 로그 보기
MIT © DigitalFortress