refresh date: 2026-09-25 robots: noindex
설명
chrome.documentScan API를 사용하여 연결된 문서 스캐너에서 이미지를 검색하고 가져옵니다.
권한
documentScan가용성
Document Scan API
Document Scan API는 앱과 확장 프로그램이 연결된 문서 스캐너에서 종이 문서의 콘텐츠를 볼 수 있도록 설계되었습니다.
유형
CancelScanResponse
속성
-
작업
문자열
cancelScan()에 전달된 것과 동일한 작업 핸들을 제공합니다. -
백엔드의 스캔 취소 결과입니다. 결과가
OperationResult.SUCCESS또는OperationResult.CANCELLED이면 스캔이 취소되고 스캐너가 새 스캔을 시작할 준비가 된 것입니다. 결과가OperationResult.DEVICE_BUSY이면 스캐너가 아직 요청된 취소를 처리 중인 것입니다. 호출자는 잠시 기다린 후 요청을 다시 시도해야 합니다. 다른 결과 값은 다시 시도해서는 안 되는 영구적인 오류를 나타냅니다.
CloseScannerResponse
속성
-
스캐너를 닫은 결과입니다. 이 값이
SUCCESS가 아니더라도 핸들은 유효하지 않으며 추가 작업에 사용해서는 안 됩니다. -
scannerHandle
문자열
closeScanner에 전달된 것과 동일한 스캐너 핸들입니다.
Configurability
옵션을 변경하는 방법
열거형
"NOT_CONFIGURABLE"
옵션이 읽기 전용입니다.
'SOFTWARE_CONFIGURABLE'
소프트웨어에서 옵션을 설정할 수 있습니다.
'HARDWARE_CONFIGURABLE'
사용자가 스캐너의 버튼을 전환하거나 눌러 옵션을 설정할 수 있습니다.
ConnectionType
스캐너가 컴퓨터에 연결되는 방식을 나타냅니다.
열거형
"UNSPECIFIED"
'USB'
"NETWORK"
열거형
"INT_RANGE"
OptionType.INT 값 범위에 대한 제약조건입니다. OptionConstraint의 min, max, quant 속성은 long이고 list 속성은 설정되지 않습니다.
"FIXED_RANGE"
OptionType.FIXED 값 범위에 대한 제약조건입니다. OptionConstraint의 min, max, quant 속성은 double이고 list 속성은 설정되지 않습니다.
"INT_LIST"
특정 OptionType.INT 값 목록에 대한 제약 조건입니다. OptionConstraint.list 속성에는 long 값이 포함되고 다른 속성은 설정되지 않습니다.
"FIXED_LIST"
특정 OptionType.FIXED 값 목록에 대한 제약 조건입니다. OptionConstraint.list 속성에는 double 값이 포함되고 다른 속성은 설정되지 않습니다.
"STRING_LIST"
특정 OptionType.STRING 값 목록에 대한 제약조건입니다. OptionConstraint.list 속성에는 DOMString 값이 포함되고 다른 속성은 설정되지 않습니다.
DeviceFilter
속성
-
로컬
불리언 선택사항
컴퓨터에 직접 연결된 스캐너만 반환합니다.
-
보안
불리언 선택사항
USB 또는 TLS와 같은 보안 전송을 사용하는 스캐너만 반환합니다.
GetOptionGroupsResponse
속성
-
그룹
OptionGroup[] 선택사항
result이SUCCESS인 경우 스캐너 드라이버에서 제공하는 순서대로 옵션 그룹 목록을 제공합니다. -
옵션 그룹을 가져온 결과입니다. 이 값이
SUCCESS이면groups속성이 채워집니다. -
scannerHandle
문자열
getOptionGroups에 전달된 것과 동일한 스캐너 핸들입니다.
GetScannerListResponse
속성
-
열거 결과입니다. 오류가 표시되더라도 부분 결과가 반환될 수 있습니다.
-
스캐너
제공된
DeviceFilter와 일치하는 스캐너 목록입니다(비어 있을 수 있음).
OpenScannerResponse
속성
-
옵션
객체 선택사항
result가SUCCESS인 경우 키가 기기별 옵션이고 값이ScannerOption의 인스턴스인 키-값 맵을 제공합니다. -
스캐너를 연 결과입니다. 이 값이
SUCCESS이면scannerHandle및options속성이 채워집니다. -
scannerHandle
문자열 선택사항
result가SUCCESS인 경우 추가 작업에 사용할 수 있는 스캐너의 핸들입니다. -
scannerId
문자열
openScanner()에 전달된 스캐너 ID입니다.
OperationResult
각 작업의 결과를 나타내는 enum입니다.
열거형
'UNKNOWN'
알 수 없거나 일반적인 오류가 발생했습니다.
'SUCCESS'
작업이 성공했습니다.
'UNSUPPORTED'
작업이 지원되지 않습니다.
'CANCELLED'
작업이 취소되었습니다.
'DEVICE_BUSY'
기기가 사용 중입니다.
'INVALID'
데이터 또는 메서드에 전달된 인수가 유효하지 않습니다.
'WRONG_TYPE'
제공된 값이 기본 옵션에 잘못된 데이터 유형입니다.
'EOF'
더 이상 사용할 수 있는 데이터가 없습니다.
'ADF_JAMMED'
문서 공급기가 걸렸습니다.
"ADF_EMPTY"
문서 공급기가 비어 있습니다.
'COVER_OPEN'
평판 커버가 열려 있습니다.
'IO_ERROR'
기기와 통신하는 중에 오류가 발생했습니다.
"ACCESS_DENIED"
기기에 인증이 필요합니다.
'NO_MEMORY'
Chromebook에 작업을 완료하는 데 사용할 수 있는 메모리가 부족합니다.
'UNREACHABLE'
기기에 연결할 수 없습니다.
'MISSING'
기기 연결이 끊어졌습니다.
'INTERNAL_ERROR'
호출 애플리케이션이 아닌 다른 곳에서 오류가 발생했습니다.
OptionConstraint
속성
-
list
string[] | number[] 선택사항
-
최대
number 선택사항
-
분
number 선택사항
-
quant
number 선택사항
OptionGroup
속성
-
멤버
문자열[]
드라이버 제공 순서의 옵션 이름 배열입니다.
-
제목
문자열
인쇄 가능한 제목(예: 'Geometry options')을 제공합니다.
OptionSetting
속성
-
이름
문자열
설정할 옵션의 이름을 나타냅니다.
-
유형
옵션의 데이터 유형을 나타냅니다. 요청된 데이터 유형은 기본 옵션의 실제 데이터 유형과 일치해야 합니다.
-
값
string | number | boolean | number[] 선택사항
설정할 값을 나타냅니다.
autoSettable가 사용 설정된 옵션의 자동 설정을 요청하려면 설정하지 않은 상태로 둡니다.value에 제공된 데이터 유형은type와 일치해야 합니다.
OptionType
옵션의 데이터 유형입니다.
열거형
"UNKNOWN"
옵션의 데이터 유형을 알 수 없습니다. value 속성이 설정 해제됩니다.
'BOOL'
value 속성은 truefalse 중 하나입니다.
"INT"
부호 있는 32비트 정수입니다. value 속성은 옵션이 값을 두 개 이상 사용하는지에 따라 long 또는 long[]입니다.
'FIXED'
-32768~32767.9999 범위의 double이며 해상도는 1/65535입니다. value 속성은 옵션이 값을 두 개 이상 사용하는지에 따라 double 또는 double[] 입니다. 정확하게 표현할 수 없는 double 값은 사용 가능한 범위와 정밀도로 반올림됩니다.
"STRING"
NUL ('\0')을 제외한 모든 바이트의 시퀀스입니다. value 속성은 DOMString입니다.
"BUTTON"
이 유형의 옵션에는 값이 없습니다. 대신 이 유형의 옵션을 설정하면 스캐너 드라이버에서 옵션별 부작용이 발생합니다. 예를 들어 버튼 유형 옵션은 스캐너 드라이버에서 기본값을 선택하거나 자동 문서 공급기에 다음 용지로 넘어가도록 지시하는 수단을 제공하는 데 사용할 수 있습니다.
"GROUP"
그룹화 옵션입니다. 값 없음. 호환성을 위해 포함되어 있지만 일반적으로 ScannerOption 값으로 반환되지 않습니다. getOptionGroups()를 사용하여 회원 옵션이 있는 그룹 목록을 검색합니다.
열거형
"UNITLESS"
값이 단위가 없는 숫자입니다. 예를 들어 기준점이 될 수 있습니다.
"PIXEL"
값은 픽셀 수입니다(예: 스캔 크기).
'BIT'
값은 비트 수입니다(예: 색상 심도).
'MM'
값이 밀리미터 단위로 측정됩니다(예: 스캔 크기).
'DPI'
값은 인치당 도트 수(예: 해상도)로 측정됩니다.
'PERCENT'
값이 백분율입니다(예: 밝기).
'MICROSECOND'
값이 마이크로초 단위로 측정됩니다(예: 노출 시간).
ReadScanDataResponse
속성
-
데이터
ArrayBuffer 선택사항
result이SUCCESS이면 스캔된 이미지 데이터의 다음 청크가 포함됩니다.result가EOF인 경우 스캔된 이미지 데이터의 마지막 청크를 포함합니다. -
estimatedCompletion
number 선택사항
result가SUCCESS인 경우 지금까지 전송된 총 스캔 데이터의 추정치입니다(0~100). -
작업
문자열
readScanData()에 전달된 작업 핸들을 제공합니다. -
데이터 읽기 결과입니다. 값이
SUCCESS이면data에 읽을 준비가 된 이미지 데이터의 다음 청크(길이가 0일 수 있음)가 포함됩니다. 값이EOF이면data에 이미지 데이터의 마지막 청크가 포함됩니다.
ScannerInfo
속성
-
connectionType
스캐너가 컴퓨터에 연결되는 방식을 나타냅니다.
-
deviceUuid
문자열
동일한 실제 기기를 가리키는 다른
ScannerInfo항목과 일치하는지 확인합니다. -
imageFormats
문자열[]
반환된 스캔에 요청할 수 있는 MIME 유형의 배열입니다.
-
제조업체
문자열
스캐너 제조업체입니다.
-
모델
문자열
스캐너 모델(사용 가능한 경우) 또는 일반적인 설명입니다.
-
이름
문자열
UI에 표시할 스캐너의 인간이 읽을 수 있는 이름입니다.
-
protocolType
문자열
스캐너에 액세스하는 데 사용되는 프로토콜 또는 드라이버에 대해 인간이 읽을 수 있는 설명입니다(예: Mopria, WSD, epsonds). 이는 주로 기기가 여러 프로토콜을 지원하는 경우 사용자가 프로토콜을 선택할 수 있도록 하는 데 유용합니다.
-
scannerId
문자열
특정 스캐너의 ID입니다.
-
보안
부울
true인 경우 스캐너 연결의 전송을 TLS 또는 USB와 같은 수동 리스너가 가로챌 수 없습니다.
ScannerOption
속성
-
구성 가능성
옵션을 변경할 수 있는지 여부와 변경 방법을 나타냅니다.
-
제약조건
OptionConstraint 선택사항
현재 스캐너 옵션에서
OptionConstraint를 정의합니다. -
설명
문자열
옵션에 대한 자세한 설명입니다.
-
isActive
부울
옵션이 활성 상태이며 설정하거나 가져올 수 있음을 나타냅니다. false이면
value속성이 설정되지 않습니다. -
isAdvanced
부울
UI에서 이 옵션을 기본적으로 표시하지 않아야 함을 나타냅니다.
-
isAutoSettable
부울
스캐너 드라이버에서 자동으로 설정할 수 있습니다.
-
isDetectable
부울
이 옵션이 소프트웨어에서 감지될 수 있음을 나타냅니다.
-
isEmulated
부울
true인 경우 스캐너 드라이버에서 에뮬레이션됩니다.
-
이름
문자열
소문자 ASCII 문자, 숫자, 대시를 사용하는 옵션 이름입니다. 발음 구별 부호는 허용되지 않습니다.
-
제목
문자열
인쇄 가능한 한 줄 제목입니다.
-
유형
이 옵션을 설정하는 데 필요한
value속성에 포함된 데이터 유형입니다. -
단위
이 옵션의 측정 단위입니다.
-
값
string | number | boolean | number[] 선택사항
옵션의 현재 값(관련이 있는 경우) 이 속성의 데이터 유형은
type에 지정된 데이터 유형과 일치해야 합니다.
ScanOptions
속성
-
maxImages
number 선택사항
허용되는 스캔 이미지 수입니다. 기본값은 1입니다.
-
mimeTypes
string[] 선택사항
호출자가 허용하는 MIME 유형입니다.
ScanResults
속성
-
dataUrls
문자열[]
이미지 태그에 'src' 값으로 전달할 수 있는 형식의 데이터 이미지 URL 배열입니다.
-
mimeType
문자열
dataUrls의 MIME 유형입니다.
SetOptionResult
속성
-
이름
문자열
설정된 옵션의 이름을 나타냅니다.
-
옵션 설정 결과를 나타냅니다.
SetOptionsResponse
속성
-
옵션
객체 선택사항
제공된 모든 옵션을 설정하려고 시도한 후 새 구성이 포함된 옵션 이름에서
ScannerOption값으로의 업데이트된 키-값 맵입니다. 이는OpenScannerResponse의options속성과 동일한 구조를 갖습니다.이 속성은 일부 옵션이 설정되지 않은 경우에도 설정되지만, 업데이트된 구성을 가져오지 못하는 경우 (예: 스캔 중에 스캐너 연결이 끊어진 경우)에는 설정되지 않습니다.
-
결과
전달된 각
OptionSetting에 대한 결과 배열입니다. -
scannerHandle
문자열
setOptions()에 전달된 스캐너 핸들을 제공합니다.
StartScanOptions
속성
-
형식
문자열
스캔한 데이터를 반환할 MIME 유형을 지정합니다.
-
maxReadSize
number 선택사항
0이 아닌 값을 지정하면 단일
readScanData응답에서 반환되는 최대 스캔 바이트가 해당 값으로 제한됩니다. 허용되는 최솟값은 32768 (32KB)입니다. 이 속성을 지정하지 않으면 반환되는 청크의 크기가 전체 스캔 이미지의 크기와 같을 수 있습니다.
StartScanResponse
속성
-
작업
문자열 선택사항
result가SUCCESS인 경우 스캔 데이터를 읽거나 작업을 취소하는 데 사용할 수 있는 핸들을 제공합니다. -
스캔 시작 결과입니다. 이 값이
SUCCESS이면job속성이 채워집니다. -
scannerHandle
문자열
startScan()에 전달된 것과 동일한 스캐너 핸들을 제공합니다.
메서드
cancelScan()
chrome.documentScan.cancelScan(
job: string,
callback?: function,
): Promise<CancelScanResponse>
시작된 스캔을 취소하고 CancelScanResponse 객체로 확인되는 프로미스를 반환합니다. 콜백이 사용되면 객체가 대신 전달됩니다.
매개변수
-
작업
문자열
이전에
startScan호출에서 반환된 활성 스캔 작업의 핸들입니다. -
callback
함수 선택사항
callback매개변수는 다음과 같습니다.(response: CancelScanResponse) => void
반환 값
-
Promise<CancelScanResponse>
결과로 확인되는 프로미스를 반환합니다.
프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
closeScanner()
chrome.documentScan.closeScanner(
scannerHandle: string,
callback?: function,
): Promise<CloseScannerResponse>
전달된 핸들로 스캐너를 닫고 CloseScannerResponse 객체로 확인되는 프로미스를 반환합니다. 콜백이 사용되면 객체가 대신 전달됩니다. 응답이 성공하지 못하더라도 제공된 핸들은 유효하지 않게 되며 추가 작업에 사용해서는 안 됩니다.
매개변수
-
scannerHandle
문자열
이전에
openScanner호출에서 반환된 열린 스캐너의 핸들을 지정합니다. -
callback
함수 선택사항
callback매개변수는 다음과 같습니다.(response: CloseScannerResponse) => void
반환 값
-
Promise<CloseScannerResponse>
결과로 확인되는 프로미스를 반환합니다.
프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
getOptionGroups()
chrome.documentScan.getOptionGroups(
scannerHandle: string,
callback?: function,
): Promise<GetOptionGroupsResponse>
openScanner에서 이전에 연 스캐너에서 그룹 이름과 구성원 옵션을 가져옵니다. 이 메서드는 GetOptionGroupsResponse 객체로 확인되는 프로미스를 반환합니다. 콜백이 이 함수에 전달되면 반환된 데이터가 대신 전달됩니다.
매개변수
-
scannerHandle
문자열
openScanner호출에서 반환된 열린 스캐너의 핸들입니다. -
callback
함수 선택사항
callback매개변수는 다음과 같습니다.(response: GetOptionGroupsResponse) => void
반환 값
-
Promise<GetOptionGroupsResponse>
결과로 확인되는 프로미스를 반환합니다.
프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
getScannerList()
chrome.documentScan.getScannerList(
filter: DeviceFilter,
callback?: function,
): Promise<GetScannerListResponse>
사용 가능한 스캐너 목록을 가져오고 GetScannerListResponse 객체로 확인되는 프로미스를 반환합니다. 콜백이 이 함수에 전달되면 반환된 데이터가 대신 전달됩니다.
매개변수
-
filter
반환해야 하는 스캐너 유형을 나타내는
DeviceFilter입니다. -
callback
함수 선택사항
callback매개변수는 다음과 같습니다.(response: GetScannerListResponse) => void
반환 값
-
Promise<GetScannerListResponse>
결과 및 스캐너 목록으로 확인되는 프로미스를 반환합니다.
프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
openScanner()
chrome.documentScan.openScanner(
scannerId: string,
callback?: function,
): Promise<OpenScannerResponse>
독점 액세스를 위해 스캐너를 열고 OpenScannerResponse 객체로 확인되는 프로미스를 반환합니다. 콜백이 이 함수에 전달되면 반환된 데이터가 대신 전달됩니다.
매개변수
-
scannerId
문자열
열려는 스캐너의 ID입니다. 이 값은
getScannerList에 대한 이전 호출에서 반환된 값입니다. -
callback
함수 선택사항
callback매개변수는 다음과 같습니다.(response: OpenScannerResponse) => void
반환 값
-
Promise<OpenScannerResponse>
결과로 확인되는 프로미스를 반환합니다.
프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
readScanData()
chrome.documentScan.readScanData(
job: string,
callback?: function,
): Promise<ReadScanDataResponse>
활성 작업 핸들에서 사용 가능한 이미지 데이터의 다음 청크를 읽고 ReadScanDataResponse 객체로 결정되는 프로미스를 반환합니다. 콜백이 사용되면 객체가 대신 전달됩니다.
**참고:**응답 결과가 길이가 0인 data 멤버를 포함하는 SUCCESS인 것은 유효합니다. 이는 스캐너가 아직 작동 중이지만 추가 데이터가 아직 준비되지 않았음을 의미합니다. 호출자는 잠시 기다린 후 다시 시도해야 합니다.
스캔 작업이 완료되면 응답에 EOF 결과 값이 포함됩니다. 이 응답에는 0이 아닌 최종 data 멤버가 포함될 수 있습니다.
매개변수
-
작업
문자열
이전에
startScan에서 반환된 활성 작업 핸들입니다. -
callback
함수 선택사항
callback매개변수는 다음과 같습니다.(response: ReadScanDataResponse) => void
반환 값
-
Promise<ReadScanDataResponse>
결과로 확인되는 프로미스를 반환합니다.
프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
scan()
chrome.documentScan.scan(
options: ScanOptions,
callback?: function,
): Promise<ScanResults>
문서 스캔을 실행하고 ScanResults 객체로 확인되는 프로미스를 반환합니다. 콜백이 이 함수에 전달되면 반환된 데이터가 대신 전달됩니다.
매개변수
-
옵션
스캔 매개변수를 포함하는 객체입니다.
-
callback
함수 선택사항
callback매개변수는 다음과 같습니다.(result: ScanResults) => void
-
결과
-
반환 값
-
Promise<ScanResults>
Chrome 96 이상스캔 결과로 확인되는 프로미스를 반환합니다.
프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
setOptions()
chrome.documentScan.setOptions(
scannerHandle: string,
options: OptionSetting[],
callback?: function,
): Promise<SetOptionsResponse>
지정된 스캐너에 옵션을 설정하고 전달된 OptionSetting 객체의 순서대로 모든 값을 설정하려는 시도의 결과가 포함된 SetOptionsResponse 객체로 확인되는 프로미스를 반환합니다. 콜백이 사용되면 객체가 대신 전달됩니다.
매개변수
-
scannerHandle
문자열
옵션을 설정할 스캐너의 핸들입니다. 이 값은 이전에
openScanner호출에서 반환된 값이어야 합니다. -
옵션
스캐너에 적용할
OptionSetting객체의 목록입니다. -
callback
함수 선택사항
callback매개변수는 다음과 같습니다.(response: SetOptionsResponse) => void
반환 값
-
Promise<SetOptionsResponse>
결과로 확인되는 프로미스를 반환합니다.
프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
startScan()
chrome.documentScan.startScan(
scannerHandle: string,
options: StartScanOptions,
callback?: function,
): Promise<StartScanResponse>
지정된 스캐너에서 스캔을 시작하고 StartScanResponse로 확인되는 프로미스를 반환합니다. 콜백이 사용되면 객체가 대신 전달됩니다. 호출이 성공하면 응답에 스캔 데이터를 읽거나 스캔을 취소하기 위한 후속 호출에 사용할 수 있는 작업 핸들이 포함됩니다.
매개변수
-
scannerHandle
문자열
열려 있는 스캐너의 핸들입니다. 이 값은 이전에
openScanner호출에서 반환된 값이어야 합니다. -
스캔에 사용할 옵션을 나타내는
StartScanOptions객체입니다.StartScanOptions.format속성은 스캐너의ScannerInfo에 반환된 항목 중 하나와 일치해야 합니다. -
callback
함수 선택사항
callback매개변수는 다음과 같습니다.(response: StartScanResponse) => void
반환 값
-
Promise<StartScanResponse>
결과로 확인되는 프로미스를 반환합니다.
프로미스는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.