HTML 마크업을 사용하여 프로그래밍 검색 엔진 구성요소 (검색창 및 검색 결과 페이지)를 웹페이지 및 기타 웹 애플리케이션에 삽입할 수 있습니다. 이러한 프로그래밍 검색 엔진 요소는 프로그래밍 검색 서버에 저장된 설정과 사용자가 지정한 맞춤설정을 기반으로 렌더링되는 구성요소로 구성됩니다.
모든 JavaScript는 비동기적으로 로드되므로 브라우저가 프로그래밍 검색 엔진 JavaScript를 가져오는 동안 웹페이지가 계속 로드될 수 있습니다.
소개
이 문서에서는 프로그래밍 검색 엔진 요소를 웹페이지에 추가하는 기본 모델과 요소의 구성 가능한 구성요소 및 유연한 JavaScript API에 대한 설명을 제공합니다.
범위
이 문서에서는 프로그래밍 검색 엔진 컨트롤 API에 특정한 함수와 속성을 사용하는 방법을 설명합니다.
브라우저 호환성
프로그래밍 검색 엔진에서 지원하는 브라우저 목록은 여기에서 확인할 수 있습니다.
잠재고객
이 문서는 페이지에 Google 프로그래밍 검색 기능을 추가하려는 개발자를 대상으로 합니다.
프로그래밍 검색 요소
HTML 마크업을 사용하여 프로그래밍 검색 요소를 페이지에 추가할 수 있습니다. 각 요소는 검색창, 검색 결과 블록 또는 둘 다와 같은 하나 이상의 구성요소로 구성됩니다. 검색창은 다음 방법 중 하나로 사용자 입력을 허용합니다.
- 텍스트 입력 필드에 입력된 검색어
- URL에 삽입된 쿼리 문자열
- 프로그래매틱 실행
또한 검색 결과 블록은 다음과 같은 방식으로 입력을 허용합니다.
- URL에 삽입된 쿼리 문자열
- 프로그래매틱 실행
다음과 같은 유형의 프로그래밍 검색 요소를 사용할 수 있습니다.
| 요소 유형 | 구성요소 | 설명 |
|---|---|---|
| 표준 | <div class="gcse-search"> |
검색창과 검색 결과가 동일한 <div>에 표시됩니다. |
| 2열 | <div class="gcse-searchbox"> 및 <div class="gcse-searchresults"> |
한쪽에 검색 결과가 있고 다른 쪽에 검색창이 있는 2열 레이아웃 웹페이지의 2열 모드에 여러 요소를 삽입하려는 경우 gname 속성을 사용하여 검색창을 검색 결과 블록과 페어링할 수 있습니다. |
| 검색창 전용 | <div class="gcse-searchbox-only"> |
독립형 검색창 |
| searchresults-only | <div class="gcse-searchresults-only"> |
독립형 검색 결과 블록입니다. |
웹페이지에 유효한 검색 요소를 원하는 만큼 추가할 수 있습니다. 2열 모드의 경우 필수 구성요소 (검색창 및 검색 결과 블록)가 모두 있어야 합니다.
다음은 간단한 검색 요소의 예입니다.
<!-- Put the following javascript before the closing </head> tag and replace 123456 with your own Programmable Search Engine ID. --> <script async src="https://cse.google.com/cse.js?cx=123456"></script> <!-- Place this tag where you want both of the search box and the search results to render --> <div class="gcse-search"></div>
프로그래밍 검색 요소를 사용하여 다양한 레이아웃 옵션 구성
프로그래밍 검색엔진 제어판의 디자인 페이지에서 다음과 같은 레이아웃 옵션을 사용할 수 있습니다. 다음은 프로그래밍 방식 검색 요소를 사용하여 레이아웃 옵션을 구성하는 방법에 관한 일반적인 가이드라인입니다. 이러한 옵션의 데모를 보려면 링크를 클릭하세요.
| 옵션 | 구성요소 |
|---|---|
| 전체 너비 | <div class="gcse-search"> |
| Compact | <div class="gcse-search"> |
| 2열 | <div class="gcse-searchbox">, <div class="gcse-searchresults"> |
| 두 페이지 | <div class="gcse-searchbox-only">(첫 번째 페이지), <div class="gcse-searchresults-only">(두 번째 페이지) |
| 결과만 | <div class="gcse-searchresults-only"> |
| Google 호스팅 | <div class="gcse-searchbox-only"> |
프로그래밍 검색 요소 맞춤설정
색상, 글꼴 또는 링크 스타일을 맞춤설정하려면 프로그래밍 검색 엔진의 디자인 페이지로 이동하세요.
선택적 속성을 사용하여 프로그래밍 검색 엔진 제어판에서 만든 구성을 덮어쓸 수 있습니다. 이렇게 하면 페이지별 검색 환경을 만들 수 있습니다.
예를 들어 다음 코드는 새 창에서 결과 페이지(http://www.example.com?search=lady+gaga)를 여는 검색창을 만듭니다. queryParameterName 속성 값은 사용자 쿼리 문자열과 함께 결과 URL을 만드는 데 사용됩니다.
queryParameterName 속성에는 data-이 접두사로 붙습니다.
이 접두사는 모든 속성에 필요합니다.
<div class="gcse-searchbox-only" data-resultsUrl="http://www.example.com" data-newWindow="true" data-queryParameterName="search">
프로그래밍 검색엔진 제어판을 사용하여 자동 완성 또는 세부검색과 같은 기능을 사용 설정한 경우 속성을 사용하여 이러한 기능을 맞춤설정할 수 있습니다. 이러한 속성을 사용하여 지정한 맞춤설정은 제어판에서 설정한 내용을 재정의합니다. 다음 예시에서는 다음과 같은 기능이 있는 2열 검색 요소를 만듭니다.
- 기록 관리가 사용 설정됨
- 표시되는 자동 완성의 최대 개수가 5로 설정되어 있습니다.
- 세부사항은 링크로 표시됩니다.
<div class="gcse-searchbox" data-enableHistory="true" data-autoCompleteMaxCompletions="5"> <div class="gcse-searchresults" data-refinementStyle="link">
지원되는 속성
| 속성 | 유형 | 설명 | 구성요소 |
|---|---|---|---|
| 일반 | |||
gname |
문자열 | (선택사항) 검색 요소 객체의 이름입니다. 이름은 이름으로 연결된 구성요소를 검색하거나 searchbox 구성요소를 searchresults 구성요소와 페어링하는 데 사용됩니다. 제공되지 않으면 프로그래밍 검색 엔진이 웹페이지의 구성요소 순서에 따라 gname를 자동으로 생성합니다. 예를 들어 첫 번째 이름 없는 searchbox-only에는 gname 'searchbox-only0'이 있고 두 번째에는 gname 'seachbox-only1'이 있습니다.
2열 레이아웃의 구성요소에 대해 자동으로 생성되는 gname는 two-column입니다. 다음 예에서는 gname storesearch를 사용하여 searchbox 구성요소를 searchresults 구성요소와 연결합니다.
<div class="gcse-searchbox" data-gname="storesearch"></div> <div class="gcse-searchresults" data-gname="storesearch"></div> 객체를 가져올 때 두 개 이상의 구성요소에 동일한 |
모두 |
autoSearchOnLoad |
불리언 | 로드되는 페이지의 URL에 삽입된 쿼리로 검색을 실행할지 여부를 지정합니다. 자동 검색을 실행하려면 URL에 쿼리 문자열이 있어야 합니다. 기본값: true |
모두 |
enableHistory |
불리언 | true인 경우 브라우저 뒤로 및 앞으로 버튼의 기록 관리를 사용 설정합니다. 데모 보기 |
검색창 검색창 전용 |
queryParameterName |
문자열 | 쿼리 매개변수 이름입니다(예: q(기본값) 또는 query). 이 값은 URL에 삽입됩니다 (예: http://www.example.com?q=lady+gaga). 쿼리 매개변수 이름만 지정하면 로드 시 자동 검색이 트리거되지 않습니다. 자동 검색을 실행하려면 URL에 쿼리 문자열이 있어야 합니다. |
모두 |
resultsUrl |
URL | 결과 페이지의 URL입니다. (기본값은 Google 호스팅 페이지입니다.) | 검색창 전용 |
newWindow |
불리언 | 결과 페이지가 새 창에서 열리는지 여부를 지정합니다.
기본값: false |
검색창 전용 |
ivt |
불리언 |
이 매개변수를 사용하면 사용자 동의가 이루어진 트래픽과 이루어지지 않은 트래픽 모두에 무효 트래픽 전용 쿠키 및 로컬 스토리지를 사용하는 광고만 허용한다는 의미의 불리언을 제공할 수 있습니다.
기본값: 사용 예시는 |
searchresults searchresults-only |
mobileLayout |
문자열 |
휴대기기에 모바일 레이아웃 스타일을 사용해야 하는지 여부를 지정합니다.
기본값: 사용 예시는 |
모두 |
| 자동 완성 | |||
enableAutoComplete |
불리언 | 프로그래밍 검색 엔진 제어판에서 자동 완성이 사용 설정된 경우에만 사용할 수 있습니다.
true은 자동 완성을 사용 설정합니다. |
모두 |
autoCompleteMaxCompletions |
정수 | 표시할 자동 완성의 최대 개수입니다. | 검색창 검색창 전용 |
autoCompleteMaxPromotions |
정수 | 자동 완성에 표시할 최대 프로모션 수입니다. | 검색창 검색창 전용 |
autoCompleteValidLanguages |
문자열 | 자동 완성 기능을 사용 설정해야 하는 언어의 쉼표로 구분된 목록입니다. 지원되는 언어 | 검색창 검색창 전용 |
| 세부 조정 | |||
defaultToRefinement |
문자열 | 프로그래밍 검색 엔진 제어판에서 세부검색이 생성된 경우에만 사용할 수 있습니다. 표시할 기본 세부검색 라벨을 지정합니다.참고: 이 속성은 Google 호스팅 레이아웃에는 지원되지 않습니다. | 모두 |
refinementStyle |
문자열 | 허용되는 값은 tab (기본값) 및 link입니다.
link은 이미지 검색이 사용 중지된 경우 또는 이미지 검색이 사용 설정되었지만 웹 검색이 사용 중지된 경우에만 지원됩니다. |
searchresults searchresults-only |
| 이미지 검색 | |||
enableImageSearch |
불리언 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
|
searchresults searchresults-only |
defaultToImageSearch |
불리언 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
|
모두 |
imageSearchLayout |
문자열 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
이미지 검색 결과 페이지의 레이아웃을 지정합니다. 허용되는 값은 |
searchresults searchresults-only |
imageSearchResultSetSize |
정수, 문자열 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
이미지 검색의 검색 결과 세트의 최대 크기를 지정합니다.
예를 들면 |
모두 |
image_as_filetype |
문자열 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
결과를 지정된 확장자의 파일로 제한합니다. 지원되는 확장자는 | 모두 |
image_as_oq |
문자열 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
논리적 OR을 사용하여 검색 결과를 필터링합니다. 'term1' 또는 'term2'가 포함된 검색 결과를 원하는 경우의 사용 예: | 모두 |
image_as_rights |
문자열 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
라이선스에 따라 필터링합니다. 지원되는 값은 일반적인 조합을 참고하세요. | 모두 |
image_as_sitesearch |
문자열 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
결과를 특정 사이트의 페이지로 제한합니다. 사용 예시는 | 모두 |
image_colortype |
문자열 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
흑백 (단색), 그레이 스케일 또는 컬러 이미지로 검색을 제한합니다. 지원되는 값은 | 모두 |
image_cr |
문자열 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
특정 국가에서 생성된 문서로 검색 결과를 제한합니다. | 모두 |
image_dominantcolor |
문자열 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
특정 지배적인 색상의 이미지로 검색을 제한합니다.
지원되는 값은 | 모두 |
image_filter |
문자열 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
검색 결과의 자동 필터링 지원되는 값: 0/1 사용 예시는 | 모두 |
image_gl |
문자열 | 프로그래밍 검색 엔진 제어판에서 이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다. 원산지가 매개변수 값과 일치하는 검색 결과를 부스팅합니다. | 모두 |
image_size |
문자열 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
지정된 크기의 이미지를 반환합니다. 크기는 | 모두 |
image_sort_by |
문자열 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
날짜 또는 기타 구조화된 콘텐츠를 사용하여 결과를 정렬합니다. 관련성을 기준으로 정렬하려면 빈 문자열 (image_sort_by="")을 사용하세요. 사용 예시는 | 모두 |
image_type |
문자열 | 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용할 수 있습니다.
검색을 특정 유형의 이미지로 제한합니다.
지원되는 값은 | 모두 |
| 웹 검색 | |||
disableWebSearch |
불리언 | true인 경우 웹 검색을 사용 중지합니다. 일반적으로 프로그래밍 검색 엔진 제어판에서
이미지 검색을 사용 설정한 경우에만 사용됩니다. |
searchresults searchresults-only |
webSearchQueryAddition |
문자열 | 논리적 OR을 사용하여 검색어에 추가된 단어입니다.
사용 예시는 |
모두 |
webSearchResultSetSize |
정수, 문자열 | 결과 집합의 최대 크기입니다. 이미지 검색과 웹 검색 모두에 적용됩니다. 기본값은 레이아웃과 프로그래밍 검색 엔진이 전체 웹을 검색하도록 구성되어 있는지 아니면 지정된 사이트만 검색하도록 구성되어 있는지에 따라 달라집니다. 허용되는 값은 다음과 같습니다.
|
모두 |
webSearchSafesearch |
문자열 |
웹 검색 결과에 SafeSearch가 사용 설정되어 있는지 지정합니다. 허용되는 값은 off 및 active입니다.
|
모두 |
as_filetype |
문자열 | 결과를 지정된 확장자의 파일로 제한합니다. Google에서 색인을 생성할 수 있는 파일 형식 목록은 Search Console 고객센터에서 확인할 수 있습니다. | 모두 |
as_oq |
문자열 | 논리적 OR을 사용하여 검색 결과를 필터링합니다.
'term1' 또는 'term2'가 포함된 검색 결과를 원하는 경우의 사용 예: |
모두 |
as_rights |
문자열 | 라이선스에 따라 필터링합니다.
지원되는 값은 일반적인 조합은 https://wiki.creativecommons.org/wiki/CC_Search_integration을 참고하세요. | 모두 |
as_sitesearch |
문자열 | 결과를 특정 사이트의 페이지로 제한합니다.
사용 예시는 |
모두 |
cr |
문자열 | 특정 국가에서 생성된 문서로 검색 결과를 제한합니다.
사용 예시는 |
모두 |
filter |
문자열 | 검색 결과의 자동 필터링
지원되는 값: 0/1 사용 예시는 |
모두 |
gl |
문자열 | 원산지가 매개변수 값과 일치하는 검색 결과를 부스팅합니다.
이 설정은 언어 값 설정과 함께만 작동합니다. 사용 예시는 |
모두 |
lr |
문자열 | 특정 언어로 작성된 문서로 검색 결과를 제한합니다.
사용 예시는 |
모두 |
sort_by |
문자열 | 날짜 또는 기타 구조화된 콘텐츠를 사용하여 결과를 정렬합니다. 속성 값은 프로그래밍 검색 엔진의 결과 정렬 설정에 제공된 옵션 중 하나여야 합니다.
관련성으로 정렬하려면 빈 문자열 (sort_by="")을 사용합니다. 사용 예시는 |
모두 |
| 검색 결과 | |||
enableOrderBy |
불리언 | 관련성, 날짜 또는 라벨별로 결과를 정렬할 수 있습니다. | 모두 |
linkTarget |
문자열 | 링크 대상을 설정합니다. 기본값: _blank |
searchresults searchresults-only |
noResultsString |
문자열 | 검색어와 일치하는 검색 결과가 없을 때 표시할 기본 텍스트를 지정합니다. 기본 결과 문자열은 지원되는 모든 언어로 현지화된 문자열을 표시할 수 있지만 맞춤 문자열은 그렇지 않습니다. | searchresults searchresults-only |
resultSetSize |
정수, 문자열 | 결과 집합의 최대 크기입니다. 예를 들면 large, small, filtered_cse, 10입니다. 기본값은 레이아웃과 엔진이 전체 웹을 검색하도록 구성되었는지 아니면 지정된 사이트만 검색하도록 구성되었는지에 따라 달라집니다. |
모두 |
safeSearch |
문자열 | 웹 검색과 이미지 검색 모두에
세이프서치가 사용 설정되어 있는지 지정합니다. 허용되는 값은 off 및 active입니다. |
모두 |
콜백
콜백은 검색 요소 초기화 및 검색 프로세스의 세부적인 제어를 지원합니다.
전역 __gcse 객체를 통해 Search Element JavaScript에 등록됩니다. 콜백 등록에서는 지원되는 모든 콜백의 등록을 보여줍니다.
window.__gcse = {
parsetags: 'explicit', // Defaults to 'onload'
initializationCallback: myInitializationCallback,
searchCallbacks: {
image: {
starting: myImageSearchStartingCallback,
ready: myImageResultsReadyCallback,
rendered: myImageResultsRenderedCallback,
},
web: {
starting: myWebSearchStartingCallback,
ready: myWebResultsReadyCallback,
rendered: myWebResultsRenderedCallback,
},
},
};
초기화 콜백
초기화 콜백은 검색 요소 JavaScript가 DOM에 검색 요소를 렌더링하기 전에 호출됩니다. __gcse에서 parsetags이 explicit로 설정되면 검색 요소 JavaScript는 검색 요소 렌더링을 초기화 콜백에 맡깁니다 (콜백 등록에 표시됨).
이는 렌더링할 요소를 선택하거나 요소가 필요할 때까지 렌더링을 지연하는 데 사용될 수 있습니다. 또한 요소의 속성을 재정의할 수 있습니다. 예를 들어 제어판 또는 HTML 속성을 통해 구성된 검색창을 기본적으로 웹 검색으로 설정된 검색창에서 이미지 검색창으로 전환하거나 프로그래밍 검색 엔진 양식을 통해 제출된 쿼리가 검색 결과 전용 요소에서 실행되도록 지정할 수 있습니다.
데모 보기
초기화 콜백의 역할은 __gcse의 parsetags 속성 값에 의해 제어됩니다.
- 값이
onload이면 검색 요소 JavaScript가 페이지의 모든 검색 요소를 자동으로 렌더링합니다. 초기화 콜백은 계속 호출되지만 검색 요소를 렌더링하지는 않습니다. - 값이
explicit이면 검색 요소 JavaScript가 검색 요소를 렌더링하지 않습니다. 콜백은render()함수를 사용하여 선택적으로 렌더링하거나go()함수를 사용하여 모든 검색 요소를 렌더링할 수 있습니다.
다음 코드는 explicit parsetag와 초기화 콜백을 사용하여 div에 검색 결과와 함께 검색창을 렌더링하는 방법을 보여줍니다.
검색 요소 코드를 원하는 위치에 ID 값이 있는 <div>를 포함해야 합니다.
<div id="test"></div><div> 뒤에 이 JavaScript를 추가합니다. <div>를 식별하는 데 사용한 id인 test를 참조합니다.const myInitCallback = function() {
if (document.readyState == 'complete') {
// Document is ready when Search Element is initialized.
// Render an element with both search box and search results in div with id 'test'.
google.search.cse.element.render(
{
div: "test",
tag: 'search'
});
} else {
// Document is not ready yet, when Search Element is initialized.
google.setOnLoadCallback(function() {
// Render an element with both search box and search results in div with id 'test'.
google.search.cse.element.render(
{
div: "test",
tag: 'search'
});
}, true);
}
};
// Insert it before the Search Element code snippet so the global properties like parsetags and callback
// are available when cse.js runs.
window.__gcse = {
parsetags: 'explicit',
initializationCallback: myInitCallback
};
검색 요소를 로드하기 시작하려면 이 HTML을 포함하세요. src 절의 cx 값을 자체 cx로 바꿉니다.
<script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>검색 콜백
검색 요소 JavaScript는 검색 제어 흐름에서 작동하는 6개의 콜백을 지원합니다. 검색 콜백은 웹 검색 콜백과 일치하는 이미지 검색 콜백의 두 가지로 제공됩니다.
- 검색 시작
- 이미지 검색
- 웹 검색
- 결과 준비됨
- 이미지 검색
- 웹 검색
- 렌더링된 결과
- 이미지 검색
- 웹 검색
초기화 콜백과 마찬가지로 검색 콜백은 __gcse 객체의 항목을 사용하여 구성됩니다. 이는 검색 요소 JavaScript가 시작될 때 발생합니다. 시작 후 __gcse 수정사항은 무시됩니다.
이러한 각 콜백에는 검색 요소의 gName이 인수로 전달됩니다.
gname은 페이지에 검색이 두 개 이상 포함된 경우에 유용합니다. data-gname 속성을 사용하여 검색 요소에 gname 값을 부여합니다.
<div class="gcse-searchbox" data-gname="storesearch"></div>
HTML에서 gname을 식별하지 않으면 검색 요소 JavaScript는 HTML이 수정될 때까지 일관되게 유지되는 값을 생성합니다.
이미지/웹 검색 시작 콜백
검색 시작 콜백은 검색 요소 JavaScript가 서버에서 검색 결과를 요청하기 직전에 호출됩니다. 사용 사례의 예로는 현지 시간을 사용하여 쿼리 변경사항을 제어하는 것이 있습니다.
searchStartingCallback(gname, query)
gname- 검색 요소의 식별 문자열
query 사용자가 입력한 - 값 (검색 요소 JavaScript에 의해 수정될 수 있음)
콜백은 이 검색의 쿼리로 사용해야 하는 값을 반환합니다. 빈 문자열을 반환하면 반환 값이 무시되고 호출자가 수정되지 않은 쿼리를 사용합니다.
또는 콜백 함수를 __gcse 객체에 넣거나 JavaScript로 객체에 콜백을 동적으로 추가할 수 있습니다.
window.__gcse['searchCallbacks']['web']['starting'] = function(gname, query) {...};검색 시작 콜백 예시
검색 시작 콜백 예시의 검색 시작 콜백 예시는 시간에 따라 morning 또는 afternoon를 쿼리에 추가합니다.
const myWebSearchStartingCallback = (gname, query) => {
const hour = new Date().getHours();
return query + (hour < 12 ? ' morning' : ' afternoon');
};
window.myImageSearchStartingCallbackName = myWebSearchStartingCallback;
window.__gcse:에 이 콜백을 설치합니다.
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
image: {
starting: 'myImageSearchStartingCallbackName',
},
web: {
starting: myWebSearchStartingCallback,
},
};
<script
async src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>이미지/웹 검색 결과 준비 콜백
이러한 콜백은 검색 요소 JavaScript가 프로모션과 결과를 렌더링하기 직전에 호출됩니다. 사용 사례의 예로는 프로모션을 렌더링하고 일반 맞춤설정으로 지정할 수 없는 스타일을 생성하는 콜백이 있습니다.
resultsReadyCallback(gname, query, promos, results, div)
gname- 검색 요소의 식별 문자열
query- 이 결과를 생성한 쿼리
promos- 사용자 쿼리와 일치하는 프로모션에 해당하는 프로모션 객체의 배열입니다. 프로모션 객체 정의를 참고하세요.
results- 결과 객체의 배열입니다. 결과 객체 정의를 참고하세요.
div- 검색 요소가 일반적으로 프로모션과 검색 결과를 배치하는 DOM에 위치한 HTML div 일반적으로 검색 요소 JavaScript는 이 div 채우기를 처리하지만 이 콜백은 결과의 자동 렌더링을 중지하고 이
div를 사용하여 결과를 직접 렌더링할 수 있습니다.
이 콜백이 true 값을 반환하면 검색 요소 JavaScript가 페이지 바닥글 작업으로 건너뜁니다.
결과 준비 콜백 예시
결과 준비 콜백 예의 resultsReady 콜백 예는 프로모션 및 결과의 기본 표시를 매우 간단한 대체로 재정의합니다.
const myResultsReadyCallback = function(name, q, promos, results, resultsDiv) {
const makePromoElt = (promo) => {
const anchor = document.createElement('a');
anchor.href = promo['url'];
anchor.target = '_blank';
anchor.classList.add('gs-title');
const span = document.createElement('span');
span.innerHTML = 'Promo: ' + promo['title'];
anchor.appendChild(span);
return anchor;
};
const makeResultParts = (result) => {
const anchor = document.createElement('a');
anchor.href = result['url'];
anchor.target = '_blank';
anchor.classList.add('gs_title');
anchor.appendChild(document.createTextNode(result['visibleUrl']));
const span = document.createElement('span');
span.innerHTML = ' ' + result['title'];
return [anchor, span];
};
const table = document.createElement('table');
if (promos) {
for (const promo of promos) {
const row = table.insertRow(-1);
const cell = row.insertCell(-1);
cell.appendChild(makePromoElt(promo));
}
resultsDiv.appendChild(table);
resultsDiv.appendChild(document.createElement('br'));
}
if (results) {
const table = document.createElement('table');
for (const result of results) {
const row = table.insertRow(-1);
const cell = row.insertCell(-1);
const [anchor, span] = makeResultParts(result);
cell.appendChild(anchor);
const cell2 = row.insertCell(-1);
cell2.appendChild(span);
}
resultsDiv.appendChild(table);
}
return true;
};
window.__gcse:에 이 콜백을 설치합니다.
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
web: {
ready: myResultsReadyCallback,
},
}; <script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
검색 시작 콜백과 마찬가지로 위는 콜백을 __gcse 객체에 넣는 여러 방법 중 하나입니다.
이미지/웹 검색 결과 렌더링 콜백
이러한 콜백은 검색 요소 JavaScript가 페이지 바닥글을 렌더링하기 직전에 호출됩니다. 사용 사례의 예로는 검색 요소에 표시되지 않는 결과 콘텐츠(예: 저장 체크박스 또는 자동으로 렌더링되지 않는 정보)를 추가하는 콜백이나 자세한 정보 버튼을 추가하는 콜백이 있습니다.
결과 렌더링 콜백에 결과 준비 콜백의 promos 및 results 매개변수에 있던 정보가 필요한 경우 다음과 같이 콜백 간에 정보를 전달할 수 있습니다.
callback(gname, query, promoElts, resultElts);
gname- 검색 요소의 식별 문자열
query- 검색 문자열입니다.
promoElts
프로모션이 포함된 DOM 요소의 배열입니다.
resultElts- 결과가 포함된 DOM 요소의 배열입니다.
반환 값은 없습니다.
결과 렌더링 콜백의 예
결과 렌더링 콜백 예시의 resultsRendered 콜백은 각 프로모션과 결과에 더미 Keep 체크박스를 추가합니다.
myWebResultsRenderedCallback = function(name, q, promos, results) {
for (const div of promos.concat(results)) {
const innerDiv = document.createElement('div');
innerDiv.appendChild(document.createTextNode('Keep: '));
const checkBox = document.createElement('input');
checkBox.type = 'checkbox';
checkBox.name = 'save';
innerDiv.appendChild(checkBox);
div.insertAdjacentElement('afterbegin', innerDiv);
}
};
window.__gcse:에 이 콜백을 설치합니다.
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
web: {
rendered: 'myWebResultsRenderedCallback',
},
}; <script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>
결과 렌더링 콜백에 결과 준비 콜백에 전달된 정보가 필요한 경우 콜백 간에 해당 데이터를 전달할 수 있습니다. 다음 예는 결과 준비 콜백의 richSnippet에서 결과 렌더링 콜백으로 평가 값을 전달하는 여러 방법 중 하나를 보여줍니다.
const makeTwoPartCallback = () => {
let saveForRenderCallback;
const readyCallback = (name, q, promos, results, resultsDiv) =>
{
saveForRenderCallback = [];
for (const result of results) {
const {
richSnippet: {
answer = []
} = {},
} = result;
const firstAnswer = answer[0];
if (firstAnswer) {
const upVotes = firstAnswer['upvotecount'];
if (upVotes) {
saveForRenderCallback.push(
{upvotes: parseInt(upVotes, 10)}
);
continue;
}
}
saveForRenderCallback.push({});
}
};
const renderedCallback = (name, q, promos, results) => {
for (let i = 0; i < results.length; ++i) {
const div = results[i];
const votes = saveForRenderCallback[i]['upvotes'];
if (votes) {
const innerDiv = document.createElement('div');
innerDiv.innerHTML = '<b>Upvotes: ' + votes + '</b>';
div.insertAdjacentElement('afterbegin', innerDiv);
}
}
};
return {readyCallback, renderedCallback};
};__gcse를 설정하는 동안 다음과 같은 코드를 사용하여 이 콜백을 설치합니다.
const {
readyCallback: webResultsReadyCallback,
renderedCallback: webResultsRenderedCallback,
} = makeTwoPartCallback();
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
web: {
ready: webResultsReadyCallback,
rendered: webResultsRenderedCallback,
},
}; <script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:kdroeu4mwju"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>결과 렌더링 콜백 예: 새 탭/창에서 특정 파일 유형 열기
다음 콜백 예시에서는 검색 결과 링크가 렌더링된 후 현재 창 대신 새 탭/페이지에서 특정 파일 (예: PDF, Excel 또는 Word)을 열도록 수정할 수 있습니다. 이렇게 하면 사용자가 동일한 창에서 파일을 열고 결과 페이지에서 벗어나지 않으려는 경우 탐색 환경이 개선됩니다.
이 콜백 예시에서는 검색 결과에서 PDF 링크를 식별하고 PDF 링크가 새 탭에서 열리도록 PDF 링크에 target="_blank" 속성을 설정합니다. 페이지가 업데이트되면 MutationObserver를 사용하여 새 결과를 동적으로 처리합니다. 참고: handleSearchResults의 .pdf를 요구사항에 따라 다른 파일 형식으로 바꿀 수 있습니다.
이 콜백 예시는 Google 호스팅 및 오버레이 레이아웃에서 작동하지 않습니다.
function handleSearchResults() {
const links = document.querySelectorAll('.gsc-results .gs-title');
links.forEach(link => {
const url = link.href;
if (url?.toLowerCase().endsWith('.pdf')) {
link.setAttribute('target', '_blank');
}
});
}
const myWebResultsRenderedCallback = () => {
// Call handleSearchResults when results are rendered
handleSearchResults();
// Set up a MutationObserver to handle subsequent updates to the results
const observer = new MutationObserver(handleSearchResults);
const searchResultsContainer = document.querySelector('.gsc-results');
if (searchResultsContainer) {
observer.observe(searchResultsContainer, {
childList: true,
subtree: true
});
} else {
console.log('No Results.');
}
};
window.__gcse:에 이 콜백을 설치합니다.
window.__gcse || (window.__gcse = {});
window.__gcse.searchCallbacks = {
web: {
rendered: myWebResultsRenderedCallback,
},
}; <script async
src="https://cse.google.com/cse.js?cx=000888210889775888983:y9tkcjel090"></script>
<div class="gcse-searchbox"></div>
<div class="gcse-searchresults"></div>콜백 예시 더보기
추가 콜백 예는 추가 콜백 예 문서에서 확인할 수 있습니다.
프로모션 및 결과 속성
JSDoc 표기법을 사용하면 promotion 및 result 객체의 속성은 다음과 같습니다. 여기에는 있을 수 있는 모든 속성이 나열됩니다. 많은 속성의 존재 여부는 프로모션 또는 검색 결과의 세부정보에 따라 달라집니다.
{
content: string,
image: {
height: number,
url: string,
width: number,
},
title: string,
url: string,
visibleUrl: string,
}{
content: string,
contentNoFormatting: string,
contextUrl: string, // For image search results only
fileFormat: string,
image: { // For image search reseults only
height: number,
url: string,
width: number,
},
perResultLabels: !Array<{
anchor: string,
label: string,
labelWithOp: string,
}>,
richSnippet: !Array<!Object>, // For web search results only
thumbnailImage: {
height: number,
url: string,
width: number,
},
title: string,
titleNoFormatting: string,
url: string,
visibleUrl: string,
}results의 richSnippet에는 객체 배열의 느슨한 유형이 있습니다. 이 배열의 항목 값은 각 검색 결과의 웹페이지에서 발견된 구조화된 데이터에 의해 제어됩니다. 예를 들어 리뷰 웹사이트는 이 배열 항목을 richSnippet에 추가하는 구조화된 데이터를 포함할 수 있습니다.
'review': {
'ratingstars': '3.0',
'ratingcount': '1024',
},Programmable Search Element Control API (V2)
google.search.cse.element 객체는 다음 정적 함수를 게시합니다.
| 함수 | 설명 | ||||||
|---|---|---|---|---|---|---|---|
.render(componentConfig, opt_componentConfig) |
검색 요소를 렌더링합니다.
매개변수
|
||||||
.go(opt_container) |
지정된 컨테이너의 모든 검색 요소 태그/클래스를 렌더링합니다.
매개변수
|
||||||
.getElement(gname) |
gname로 요소 객체를 가져옵니다. 찾을 수 없는 경우 null을 반환합니다.
반환된
다음 코드는 검색 요소 'element1'에서 'news'라는 쿼리를 실행합니다. var element = google.search.cse.element.getElement('element1'); element.execute('news'); |
||||||
.getAllElements() |
gname를 키로 사용하여 성공적으로 생성된 모든 요소 객체의 맵을 반환합니다. |