[ASP.NET] AJAX Control Toolkit 에서 제공하는 자동완성 기능 컨트롤 / AutoCompleteExtender

ASP.NET

[ASP.NET] AJAX Control Toolkit 에서 제공하는 자동완성 기능 컨트롤 / AutoCompleteExtender

yerica 2025. 3. 24. 09:22

" 목차 "

AutoCompleteExtender

AutoCompleteExtender란?

ASP.NET AJAX Control Toolkit 에서 제공하는 컨트롤 중 하나로,

사용자가 텍스트를 입력하면, 서버 측 웹 메서드를 호출하여 추천 목록을 받아와 자동완성 리스트를 표시해준다.

그래서 보통 검색창, 주소 입력, 이메일 자동완성 등에서 많이 사용된다.

[How Do I:] Use the ASP.NET AJAX AutoComplete Control

The AutoComplete extender control from the ASP.NET AJAX Control Toolkit provides real-time suggestions to the user as he or she types in a text box on the Web page, where the list of suggestions is obtained by an asynchronous call to a Web service on the s

learn.microsoft.com

AutoCompleteExtender

01. 구성 요소

구성 요소	설명
TextBox	사용자 입력을 받을 기본 컨트롤
AutoCompleteExtender	텍스트 입력에 자동완성 기능을 더해주는 AJAX 컨트롤
ServiceMethod	자동완성 데이터를 제공하는 서버 함수
itemSelected 이벤트	사용자가 선택한 항목을 JavaScript에서 처리

AutoCompleteExtender

02. 기본 사용 예제

ASPX 코드

<asp:ScriptManager ID="ScriptManager1" runat="server" />

<asp:TextBox ID="txtSearch" runat="server" />

<ajaxToolkit:AutoCompleteExtender
    ID="autoCompleteExtender1"
    BehaviorID="autoComplete"
    runat="server"
    TargetControlID="txtSearch"
    ServicePath="경로"
    ServiceMethod="GetSuggestions"
    MinimumPrefixLength="2"
    CompletionInterval="300"
    EnableCaching="true"
    CompletionSetCount="10" />

Code-behind(C#)

[System.Web.Services.WebMethod]
public static List<string> GetSuggestions(string prefixText, int count)
{
    // 예시: 실제 데이터베이스에서 가져올 수도 있음
    List<string> cities = new List<string> { "Seoul", "San Francisco", "Sydney", "Singapore", "Sapporo" };

    return cities
        .Where(c => c.StartsWith(prefixText, StringComparison.OrdinalIgnoreCase))
        .Take(count)
        .ToList();
}

- 동작 순서

사용자가 텍스트박스에 2글자 이상 입력 후 MinimunPerfixLength
0.3초 동안 입력이 멈추면 CompleteionInterval
서버의 GetSuggestion(prefixText, count) 함수가 호출된다. (또는 ServicePath 경유하여 호출)
결과 리스트를 받아 자동완성 목록을 표시한다.
사용자가 항목을 클릭하면 해당 항목이 텍스트 박스에 자동 입력된다. ( AutoCompleteExtender의 기본 기능)

AutoCompleteExtender

03. 주요 속성 설명

속성명	설명
ID	ASP.NET 서버 컨트롤에서 서버가 인식하는 이름, 백엔드 전용 ID ~~runat = "server" 가 붙은 경우 필수~~
BehaviorID	클라이언트(브라우저)에서 JavaScript로 이 AJAX 컨트롤에 접근할 때 사용하는 이름
TargetControlID	자동완성 기능을 적용할 TextBox의 ID
ServicePath	메서드가 현재 페이지가 아닌 다른 웹 서비스~~(.asmx)~~에 있을 때 사용하는 경로 지정 속성
ServiceMethod	서버에서 자동완성 데이터를 가져오는 메서드 이름
MinimumPrefixLength	몇 글자 이상 입력해야 자동완성 시작되는지 설정
CompletionInterval	사용자가 입력을 멈춘 뒤 자동완성 실행까지의 지연 시간~~(ms)~~
EnableCaching	이전 결과를 클라이언트에 캐시할지 여부
CompletionSetCount	최대 몇 개의 추천 항목을 표시할지 설정

AutoCompleteExtender

04. HTML 렌더링 결과

코드를 작성하면 렌더링시 <body> 태그 안의 최하단에 <ul> 태그로 자동완성 박스가 생성된다.

속성들은 기본으로 다음과 같이 설정되어 있으며, 사용자가 텍스트를 입력하면 visibility 가 hidden에서 visible 로 변환된다.

사용자가 텍스트를 입력한 텍스트와 서버에서 자동완성 데이터가 일치한다면 <ul> 태그 안에 목록이 생성된다.

생성된 목록을 클릭하면 기존 텍스트를 입력하던 텍스트 박스의 value에 해당 목록이 자동으로 입력된다.

자동으로 입력되는 것은 AutoCompleteExtender의 기본 기능

AutoCompleteExtender

05. 좀 더 정밀하게 동작을 제어하고 싶다면?

예를 들어, 목록을 클릭했을 때 결과 내용전체를 텍스트 박스의 value에 넣는 것이 아니라 분류해서 넣고 싶을 수도 있고

혹은 목록을 클릭했을 때 다른 이벤트 함수가 함께 실행되도록 만들고 싶을 수도 있다.

이럴 때, 가장 정확하고 안전한 방법은 itemSelected 이벤트를 직접 연결하는 것이다.

- 선택한 목록을 알람창에 띄우기

<asp:ScriptManager ID="ScriptManager1" runat="server" />

<asp:TextBox ID="txtSearch" runat="server" />

<ajaxToolkit:AutoCompleteExtender
    ID="autoCompleteExtender1"
    BehaviorID="autoComplete"
    runat="server"
    TargetControlID="txtSearch"
    ServicePath="경로"
    ServiceMethod="GetSuggestions"
    MinimumPrefixLength="2"
    CompletionInterval="300"
    EnableCaching="true"
    CompletionSetCount="10" />

<script type="text/javascript">
   function onItemSelected(sender, e) {
      var selectedValue = e.get_value();
      var selectedText = e.get_text();
      alert("선택한 항목: " + selectedText + " (값: " + selectedValue + ")");
   }

   Sys.Application.add_load(function () {
      var autoComplete = $find("autoCompleteExtender1");
      autoComplete.add_itemSelected(onItemSelected);
   });
</script>

Sys.Application.add_load() 는 페이지가 로드될 때 실행할 함수를 불러온다.
$find("autoCompleteExtender1") 로 AutoCompleteExtender를 찾아 add_itemSelected() 라는 자동완성 항목을 사용자가 선택했을 때 실행할 자바스크립트 함수를 연결한다.

위의 예제에선 onItemSelected 함수를 만들어 연결했다.
onItemSelected 함수 안의 매개변수인 sender는 AutoCompleteExtender의 객체를 뜻하며, e는 선택된 항목이다.
e.get_value()는 선택된 항목의 값(value)이고, e.get_text()는 선택된 항목의 표시 텍스트(text)이다.

결과적으로 자동완성 목록을 선택하면 선택한 목록의 값과 텍스트가 알람창에 띄워지는 것이다.

이때, ID보다는 BehaviorID로 AutoCompleteExtender를 찾는 것이 더 좋다.

이유는 ID는 서버 컨트롤이며, 서버의 ID가 클라이언트에서 자동으로 ClientID로 렌더링 되기 때문에 $find(" ")로 찾을 수 있었던 것인데, 컨트롤 구조나 환경에 따라 ID가 바뀔 수 있기 때문이다.

- 선택한 항목의 값을 hidden input에 저장하기

<asp:TextBox ID="txtCity" runat="server" />
<asp:HiddenField ID="hfCityValue" runat="server" />

<ajaxToolkit:AutoCompleteExtender 
    ID="autoCompleteExtender"
    runat="server"
    TargetControlID="txtCity"
    ServiceMethod="GetCities"
    MinimumPrefixLength="2"
    CompletionSetCount="10" />

<script type="text/javascript">
    function saveCityValue(sender, e) {
        document.getElementById('<%= hfCityValue.ClientID %>').value = e.get_value();
    }

    Sys.Application.add_load(function () {
        $find("autoCompleteExtender").add_itemSelected(saveCityValue);
    });
</script>

검색을 입력할 텍스트 박스와 히든 필드를 만들고,
자동검색 목록을 클릭 시, 히든필드의 value에 선택된 목록의 값(value)가 들어가도록 만든 함수이다.

- 목록 선택 이후 검색 버튼 자동으로 눌리는 함수

<asp:TextBox ID="txtSearch" runat="server" />
<button type="submit" id="cmdReSearch" >

<ajaxToolkit:AutoCompleteExtender
    ID="autoCompleteExtender1"
    BehaviorID="autoComplete"
    runat="server"
    TargetControlID="txtSearch"
    ServicePath="경로"
    ServiceMethod="GetSuggestions"
    MinimumPrefixLength="2"
    CompletionInterval="300"
    EnableCaching="true"
    CompletionSetCount="10" />

<script type="text/javascript">
   Sys.Application.add_load(function () {
      var autoComplete = $find("autoComplete"); //BehaviorID로 가져오기
      autoComplete.add_itemSelected(function (sender, args) {
        //검색버튼 클릭
        document.querySelector("#cmdReSearch").click();
      });
   });
</script>

검색 목록이 선택되면 검색 버튼인 #cmdReSearch에 클릭 이벤트 발생.

AutoCompleteExtender

06. CSS 꾸미기

자동완성 목록은 동적으로 생성되기 때문에, 스타일을 주고 싶을 때 렌더링 된 결과를 확인하여 스타일을 적용하여야한다.

<!-- 렌더링 된 결과 -->
<ul id="autoComplete_completionListElem" 
    style="text-align: left; visibility: hidden; cursor: default; 
    list-style: none; padding: 0px; border: 1px solid gray; 
    background-color: white; color: black; display: none; position: absolute;">
    <div>목록</div>
</ul>

<style>
/* 자동완성 목록 스타일 */
#autoComplete_completionListElem {
  font-size: 14px !important;
  box-sizing: border-box;
}

/* 자동완성 항목 스타일 */
#autoComplete_completionListElem div {
  padding: 5px 10px !important;
  cursor: pointer;
  transition: background 0.2s;
  background: white !important; /* white로 설정해 주어야 마우스를 뗐을 때 다시 흰색으로 돌아옴*/
}

/* 마우스 오버 시 배경색 변경 */
#autoComplete_completionListElem div:hover {
  background: #f1faff !important;
}
</style>