# SearchMode (cfg)

> 데이터를 조회하고 화면에 표시하는 방식을 설정합니다.

> - 데이터를 한번에 전체 조회할 수 있으면 → `0`, `1`, `2`를 설정합니다.
> - 데이터가 많아 서버·브라우저 메모리 부족이나 렌더링 부담이 크면 → `3`, `4`, `5`를 설정합니다.

### Type

`number`

### Options

Value | Mode | Description
--- | --- | ---
`0` | FastLoad | 전체 데이터를 조회하고 세로 스크롤 시 보이는 셀의 데이터만 교체하여 표시
`1` | ClientPaging | 전체 데이터를 조회하고 PageLength 만큼 페이징 처리
`2` | LazyLoad (default) | 전체 데이터를 조회하고 스크롤 위치에 따라 PageLength 단위로 표시
`3` | ScrollAppend | 데이터가 많아 서버 응답이 느리거나 브라우저 렌더링 부담이 큰 경우 사용. PageLength 단위로 서버에서 조회 스크롤 하단 도달 시 추가 조회하여 기존 데이터 하단에 표시. 조회한 페이지는 재요청 없음
`4` | ServerPaging | 데이터가 많아 서버 응답이 느리거나 브라우저 렌더링 부담이 큰 경우 사용. PageLength 단위로 서버에서 조회 페이지 번호 클릭 시 해당 페이지 데이터를 조회하여 표시. 조회한 페이지는 재요청 없음
`5` | ServerPaging2 | 데이터가 많아 서버 응답이 느리거나 브라우저 렌더링 부담이 큰 경우 사용. ServerPaging과 동일하나 페이지 이동 시 항상 서버 재요청

### 비교표

구분 | 0 (FastLoad) | 1 (ClientPaging) | 2 (LazyLoad) | 3 (ScrollAppend) | 4 (ServerPaging) | 5 (ServerPaging2)
--- | --- | --- | --- | --- | --- | ---
데이터 로드 | 전체 데이터 조회 | 전체 데이터 조회 | 전체 데이터 조회 | 서버에서 PageLength 단위 조회 | 서버에서 PageLength 단위 조회 | 서버에서 PageLength 단위 조회
조회 함수 | doSearch loadSearchData | doSearch loadSearchData | doSearch loadSearchData | doSearchPaging | doSearchPaging | doSearchPaging
페이지 번호 | X | O (InfoRowConfig) | X | X | O (InfoRowConfig) | O (InfoRowConfig)
페이지 캐싱 | — | — | — | O (재요청 없음) | O (재요청 없음) | X (항상 재요청)
서버 응답에 Total 필수 | X | X | X | O | O | O
Sort | 전체 데이터 | 전체 데이터 | 전체 데이터 | 조회된 데이터에서만 정렬 (서버로 Sort 정보 전송 시 ScrollPagingServerSort 참조) | 서버로 Sort 정보 전송 (조회된 데이터에서만 정렬 시 SortCurrentPage 참조) | 서버로 Sort 정보 전송 (조회된 데이터에서만 정렬 시 SortCurrentPage 참조)
Filter | 전체 데이터 | 전체 데이터 | 전체 데이터 | 조회된 데이터만 (전체는 서버 재조회: onBeforeFilter) | 조회된 데이터만 (전체는 서버 재조회: onBeforeFilter) | 조회된 데이터만 (전체는 서버 재조회: onBeforeFilter)
찾기 (Ctrl+F) | 전체 데이터 | 전체 데이터 | 전체 데이터 | 조회된 데이터만 | 조회된 데이터만 | 조회된 데이터만
Pivot | O | O | O | X | X | X
엑셀 다운로드 | 전체 데이터 | 전체 데이터 | 전체 데이터 | 조회된 데이터만 (서버에서 전체 다운로드: directDown2Excel) | 조회된 데이터만 (서버에서 전체 다운로드: directDown2Excel) | PageLength 만큼 (서버에서 전체 다운로드: directDown2Excel)
Tree | O | X | O | X | X | X
FormulaRow | O | O | O | △ (대안: Foot 또는 showFixedRows) | △ (대안: Foot 또는 showFixedRows) | △ (대안: Foot 또는 showFixedRows)
makeSubTotal | O | X | O | X | X | X
Wrap, Lines, Image 등 가변 행 높이 | AutoRowHeight 필요 | O | O | AutoRowHeight 필요 | O | O

### 모드 선택 가이드

먼저 데이터를 한 번에 전체 조회할 수 있는지로 크게 나눕니다.

- 전체 데이터를 한 번에 받아도 무리 없으면 → `0` / `1` / `2` (조회: doSearch / loadSearchData)
  - `0` FastLoad — 세로 스크롤이 부드럽고 렌더링 성능에 가장 유리. 단, 행 높이가 모두 같아야 하며 가변이면 AutoRowHeight가 필요합니다.
  - `1` ClientPaging — 페이지 번호로 나눠 보여줄 때. (`Tree`, `makeSubTotal` 미지원)
  - `2` LazyLoad (기본) — 일반적인 경우. `Tree`, `makeSubTotal`, 가변 행 높이까지 폭넓게 지원합니다.
- 데이터가 많아 한 번에 받기 부담되면(서버 응답 지연, 메모리, 렌더링 부담) → `3` / `4` / `5` (조회: doSearchPaging, 서버 응답에 `Total` 필요)
  - `3` ScrollAppend — 스크롤을 내리면 다음 페이지를 이어 붙이는 방식.
  - `4` ServerPaging — 페이지 번호로 이동(조회한 페이지는 캐싱).
  - `5` ServerPaging2 — 페이지 이동 시 항상 서버를 재조회(최신 데이터 반영이 중요할 때).

> 정확한 데이터 건수 기준선은 컬럼 수, 셀 내용, 서버 환경에 따라 달라지므로 단정하기 어렵습니다. 전체를 한 번에 받았을 때 부담이 없으면 `0`~`2`, 그렇지 않으면 `3`~`5`를 기준으로 삼고, 필요한 기능은 위 비교표에서 확인하세요. 예를 들어 `Pivot`, `Tree`, `makeSubTotal`, `(Col) FormulaRow`는 서버 페이징(`3`/`4`/`5`)에서 제약이 있습니다.

### SearchMode: 0 (FastLoad)

가상 스크롤 기반으로, 사용자가 세로 스크롤 시 보이는 영역의 데이터만 즉시 갱신합니다.
스크롤과 동시에 화면의 끊김 없이 행의 데이터를 바로 확인할 수 있습니다.

> 각 행의 높이는 모두 동일해야 하며, (Appendix)기능에 제약사항이 있습니다.
> 데이터행의 높이가 일정하지 않다면 (Cfg)AutoRowHeight를 설정하시기 바랍니다.

    options.Cfg = { SearchMode: 0 };

    // AJAX 통신으로 조회
    sheet.doSearch({ url: "/api/data.jsp", method: "POST" });

    // 또는 데이터 직접 바인딩
    sheet.loadSearchData({ data: jsonData });

### SearchMode: 1 (ClientPaging)

전체 데이터를 조회하고 (Cfg)PageLength 설정값만큼 페이징 처리 후 페이지 번호를 통해 보여주는 기능입니다.

- (Method)updateClientPaging 함수를 이용해서 동적으로 페이지의 개수를 변경하고 재계산할 수 있습니다.
- InfoRowConfig를 사용해 페이지 번호를 표시해야 페이지를 클릭하여 이동할 수 있습니다.

> 주의 : `(Method) makeSubTotal` 지원하지 않습니다.

    // 기본 페이지 번호
    options.Cfg = {
        SearchMode: 1,
        PageLength: 50,
        InfoRowConfig: { Layout: ["Paging", "Count"] }
    };

    // 숫자형 페이지 번호 + 페이지 크기 선택
    options.Cfg = {
        SearchMode: 1,
        PageLength: 50,
        InfoRowConfig: {
            Layout: ["Paging2", "Count"],
            ViewCount: 1,
            ViewFormat: "10|20|50|100"
        }
    };

    // AJAX 통신으로 조회
    sheet.doSearch({ url: "/api/data.jsp", method: "POST" });

    // 또는 데이터 직접 바인딩
    sheet.loadSearchData({ data: jsonData });

### SearchMode: 2 (LazyLoad) — default

가상 스크롤 기반으로, 전체 데이터를 조회하고 (Cfg)PageLength 설정값 단위로 스크롤 위치에 따라 데이터를 화면에 표시하는 기능입니다.

    options.Cfg = { SearchMode: 2, PageLength: 50 };

    // AJAX 통신으로 조회
    sheet.doSearch({ url: "/api/data.jsp", method: "POST" });

    // 또는 데이터 직접 바인딩
    sheet.loadSearchData({ data: jsonData });

### SearchMode: 3 (ScrollAppend)

(Cfg)PageLength에 지정된 개수만큼 한 페이지씩 서버에서 조회하여 화면에 표시하는 기능입니다.

- 조회는 반드시 (Method)doSearchPaging 함수를 통해 수행해야 합니다.
- 세로 스크롤이 하단에 도달하면 다음 페이지 데이터를 서버에서 조회하여 기존 데이터 아래에 추가합니다.
- 서버는 시트로부터 넘어오는 페이지 정보(`ibpage=2,3,4...`)에 따라 페이징 쿼리를 구성하여 각 페이지별 데이터를 리턴해야 합니다.
- 조회 데이터에 Total(전체 record 수) 속성이 포함되어 있어야 합니다.
- Total 값과 누적 데이터 수가 같아지면 더 이상 서버 호출은 발생하지 않습니다.
- 한번 조회한 페이지는 재요청 없이 재사용됩니다.
- `Sort`, `Filter`, `엑셀 다운로드`는 기본적으로 조회된 데이터 안에서만 동작합니다.
  - `Sort` : (Cfg) ScrollPagingServerSort를 설정하면 서버로 정렬 요청을 전송할 수 있습니다.
  - `엑셀 다운로드` : (Method) directDown2Excel을 사용하면 전체 데이터를 다운로드할 수 있습니다. 단, 서버에서 전체 데이터를 처리할 수 있는 메모리가 충분해야 합니다.
  - `Filter` : 전체 데이터에 대한 필터링은 지원하지 않습니다. 단, onBeforeFilter에서 getFilter로 필터 조건을 모아 doSearchPaging로 서버에 전송하면(기본 필터는 `return 1`로 취소) 전체 데이터 기준 필터를 서버에서 구현할 수 있습니다.
- `(Col) FormulaRow`는 사용할 수 없습니다. 전체 합계가 필요한 경우 서버에서 계산하여 Foot 또는 showFixedRows로 Footer에 표시합니다.
- `(Method) makeSubTotal`은 지원하지 않습니다.

> 주의

> - `Type:Lines, Img`나 `Wrap:1` 과 같이 데이터 행의 높이가 일정하지 않은 속성을 사용하려면 (Cfg)AutoRowHeight를 설정해야 합니다.

    options.Cfg = { SearchMode: 3, PageLength: 50 };

    // doSearchPaging으로 최초 조회
    // 이후 페이지 이동, Sort 등은 시트가 자동으로 서버에 요청합니다.
    sheet.doSearchPaging({ url: "/api/data.jsp", method: "POST" });

### SearchMode: 4 (ServerPaging)

(Cfg)PageLength에 지정된 개수만큼 한 페이지씩 서버에서 조회하여 화면에 표시하는 기능입니다.

- 조회는 반드시 (Method)doSearchPaging 함수를 통해 수행해야 합니다.
- InfoRowConfig를 사용해 페이지 번호를 표시해야 페이지를 클릭하여 이동할 수 있습니다.
- 페이지 번호 변경 시 doSearchPaging이 호출한 URL을 다시 요청하여 해당 페이지 데이터를 표시합니다.
- 서버는 시트로부터 넘어오는 페이지 정보(`ibpage=2,3,4...`)에 따라 페이징 쿼리를 구성하여 각 페이지별 데이터를 리턴해야 합니다.
- 조회 데이터에 Total(전체 record 수) 속성이 포함되어 있어야 합니다.
- 한번 조회한 페이지는 서버를 다시 호출하지 않습니다.
- `Sort`는 기본적으로 서버로 정렬 정보를 전송하므로, 서버에서 정렬된 결과를 조회해야 합니다. 조회된 데이터에서만 정렬하려면 SortCurrentPage를 설정하세요.
- `Filter`, `엑셀 다운로드`는 조회된 데이터 안에서만 동작합니다.
  - `엑셀 다운로드` : (Method) directDown2Excel을 사용하면 전체 데이터를 다운로드할 수 있습니다. 단, 서버에서 전체 데이터를 처리할 수 있는 메모리가 충분해야 합니다.
  - `Filter` : 전체 데이터에 대한 필터링은 지원하지 않습니다. 단, onBeforeFilter에서 getFilter로 필터 조건을 모아 doSearchPaging로 서버에 전송하면(기본 필터는 `return 1`로 취소) 전체 데이터 기준 필터를 서버에서 구현할 수 있습니다.
- `(Col) FormulaRow`는 사용할 수 없습니다. 전체 합계가 필요한 경우 서버에서 계산하여 Foot 또는 showFixedRows로 Footer에 표시합니다.
- `(Method) makeSubTotal`은 지원하지 않습니다.

    // 기본 페이지 번호
    options.Cfg = {
        SearchMode: 4,
        PageLength: 50,
        InfoRowConfig: { Layout: ["Paging", "Count"] }
    };

    // 숫자형 페이지 번호 + 건수 포맷 커스텀
    options.Cfg = {
        SearchMode: 4,
        PageLength: 50,
        InfoRowConfig: {
            Layout: ["Paging2", "Count"],
            ViewCount: 1,
            Format: "[BOTTOMDATAROW / TOTALROWS] 건"
        }
    };

    // doSearchPaging으로 최초 조회
    // 이후 페이지 이동, Sort 등은 시트가 자동으로 서버에 요청합니다.
    sheet.doSearchPaging({ url: "/api/data.jsp", method: "POST" });

### SearchMode: 5 (ServerPaging2)

(Cfg)PageLength에 지정된 개수만큼 한 페이지씩 서버에서 조회하여 화면에 표시하는 기능입니다. `ServerPaging`과 동일하지만, 페이지 이동 시 항상 서버를 호출하여 최신 데이터를 조회합니다.

- 조회는 반드시 (Method)doSearchPaging 함수를 통해 수행해야 합니다.
- InfoRowConfig를 사용해 페이지 번호를 표시해야 페이지를 클릭하여 이동할 수 있습니다.
- 서버는 시트로부터 넘어오는 페이지 정보(`ibpage=2,3,4...`)에 따라 페이징 쿼리를 구성하여 각 페이지별 데이터를 리턴해야 합니다.
- 조회 데이터에 Total(전체 record 수) 속성이 포함되어 있어야 합니다.
- 페이지 이동 시 항상 서버를 재요청합니다. (캐싱 없음)
- `Sort`는 기본적으로 서버로 정렬 정보를 전송하므로, 서버에서 정렬된 결과를 조회해야 합니다. 조회된 데이터에서만 정렬하려면 SortCurrentPage를 설정하세요.
- `Filter`, `엑셀 다운로드`는 조회된 데이터(PageLength) 안에서만 동작합니다.
  - `엑셀 다운로드` : (Method) directDown2Excel을 사용하면 전체 데이터를 다운로드할 수 있습니다. 단, 서버에서 전체 데이터를 처리할 수 있는 메모리가 충분해야 합니다.
  - `Filter` : 전체 데이터에 대한 필터링은 지원하지 않습니다. 단, onBeforeFilter에서 getFilter로 필터 조건을 모아 doSearchPaging로 서버에 전송하면(기본 필터는 `return 1`로 취소) 전체 데이터 기준 필터를 서버에서 구현할 수 있습니다.
- `(Col) FormulaRow`는 사용할 수 없습니다. 전체 합계가 필요한 경우 서버에서 계산하여 Foot 또는 showFixedRows로 Footer에 표시합니다.
- `(Method) makeSubTotal`은 지원하지 않습니다.
- (Method)updatePageLength를 통해 동적으로 페이지 행의 개수를 변경할 수 있습니다.

    // 숫자형 페이지 번호 + 페이지 크기 선택
    options.Cfg = {
        SearchMode: 5,
        PageLength: 50,
        InfoRowConfig: {
            Layout: ["Paging2", "Count"],
            ViewCount: 1,
            ViewFormat: "10|20|50|100"
        }
    };

    // doSearchPaging으로 최초 조회 (항상 서버 재요청)
    // 이후 페이지 이동, Sort 등은 시트가 자동으로 서버에 요청합니다.
    sheet.doSearchPaging({ url: "/api/data.jsp", method: "POST" });

### Read More

- AutoRowHeight cfg
- InfoRowConfig cfg
- PageLength cfg
- SortCurrentPage cfg
- ScrollPagingServerSort cfg
- 조회 응답 규격
- 페이징 응답 규격
- doSearch method
- loadSearchData method
- doSearchPaging method
- updateClientPaging method
- updatePageLength method
- showFixedRows method
- directDown2Excel method

### Since

product | version | desc
--- | --- | ---
core | 8.0.0.0 | 기능 추가
core | 8.1.0.54 | `ServerPaging2` 추가