chrome.documentScan

설명

chrome.documentScan API를 사용하여 연결된 문서 스캐너에서 이미지를 검색하고 가져옵니다.

권한

documentScan

가용성

Chrome 44 이상 ChromeOS만 해당

문서 스캔 API

문서 스캔 API는 앱과 확장 프로그램이 연결된 문서 스캐너에서 종이 문서의 콘텐츠를 볼 수 있도록 설계되었습니다.

유형

CancelScanResponse

Chrome 125 이상

속성

  • 작업

    문자열

    cancelScan()에 전달된 것과 동일한 작업 핸들을 제공합니다.

  • 백엔드의 스캔 취소 결과입니다. 결과가 OperationResult.SUCCESS 또는 OperationResult.CANCELLED이면 스캔이 취소되었으며 스캐너가 새 스캔을 시작할 준비가 된 것입니다. 결과가 OperationResult.DEVICE_BUSY이면 스캐너가 요청된 취소를 아직 처리 중인 것입니다. 호출자는 잠시 기다린 후 요청을 다시 시도해야 합니다. 다른 결과 값은 다시 시도해서는 안 되는 영구적인 오류를 나타냅니다.

CloseScannerResponse

Chrome 125 이상

속성

  • 스캐너를 닫은 결과입니다. 이 값이 SUCCESS이 아니더라도 핸들은 유효하지 않으므로 추가 작업에 사용하면 안 됩니다.

  • scannerHandle

    문자열

    closeScanner에 전달된 것과 동일한 스캐너 핸들입니다.

Configurability

Chrome 125 이상

옵션을 변경할 수 있는 방법입니다.

열거형

'NOT_CONFIGURABLE'
옵션이 읽기 전용입니다.

'SOFTWARE_CONFIGURABLE'
소프트웨어에서 옵션을 설정할 수 있습니다.

'HARDWARE_CONFIGURABLE'
이 옵션은 사용자가 스캐너의 버튼을 전환하거나 눌러 설정할 수 있습니다.

ConnectionType

Chrome 125 이상

스캐너가 컴퓨터에 연결된 방식을 나타냅니다.

열거형

"UNSPECIFIED"

"USB"

'NETWORK'

ConstraintType

Chrome 125 이상

OptionConstraint로 표현되는 제약 조건의 데이터 유형입니다.

열거형

'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

Chrome 125 이상

속성

  • 로컬

    불리언 선택사항

    컴퓨터에 직접 연결된 스캐너만 반환합니다.

  • 보안

    불리언 선택사항

    USB 또는 TLS와 같은 보안 전송을 사용하는 스캐너만 반환합니다.

GetOptionGroupsResponse

Chrome 125 이상

속성

  • 그룹

    OptionGroup[] 선택사항

    result이 SUCCESS인 경우 스캐너 드라이버에서 제공한 순서대로 옵션 그룹 목록을 제공합니다.

  • 옵션 그룹을 가져온 결과입니다. 이 값이 SUCCESS이면 groups 속성이 채워집니다.

  • scannerHandle

    문자열

    getOptionGroups에 전달된 것과 동일한 스캐너 핸들입니다.

GetScannerListResponse

Chrome 125 이상

속성

  • 열거 결과입니다. 오류를 나타내더라도 부분 결과가 반환될 수 있습니다.

  • 스캐너

    ScannerInfo[]

    제공된 DeviceFilter와 일치하는 스캐너의 목록(비어 있을 수 있음)

OpenScannerResponse

Chrome 125 이상

속성

  • 옵션

    객체 선택사항

    result이 SUCCESS인 경우 키가 기기별 옵션이고 값이 ScannerOption 인스턴스인 키-값 매핑을 제공합니다.

  • 스캐너를 연 결과입니다. 이 값이 SUCCESS이면 scannerHandle 및 options 속성이 채워집니다.

  • scannerHandle

    문자열 선택사항

    result이 SUCCESS인 경우 추가 작업에 사용할 수 있는 스캐너 핸들입니다.

  • scannerId

    문자열

    openScanner()에 전달된 스캐너 ID입니다.

OperationResult

Chrome 125 이상

각 작업의 결과를 나타내는 enum입니다.

열거형

'UNKNOWN'
알 수 없거나 일반적인 오류가 발생했습니다.

"SUCCESS"
작업이 성공했습니다.

'지원되지 않음'
작업이 지원되지 않습니다.

'CANCELLED'
작업이 취소되었습니다.

'DEVICE_BUSY'
기기가 사용 중입니다.

'INVALID'
데이터 또는 메서드에 전달된 인수가 유효하지 않습니다.

'WRONG_TYPE'
제공된 값이 기본 옵션의 데이터 유형과 다릅니다.

'EOF'
더 이상 사용할 수 있는 데이터가 없습니다.

'ADF_JAMMED'
문서 급지대에 용지가 걸렸습니다.

'ADF_EMPTY'
문서 급지대가 비어 있습니다.

'COVER_OPEN'
평판 스캐너 덮개가 열려 있습니다.

'IO_ERROR'
기기와 통신하는 중에 오류가 발생했습니다.

'ACCESS_DENIED'
기기에 인증이 필요합니다.

'NO_MEMORY'
작업을 완료할 수 있는 메모리가 Chromebook에 충분하지 않습니다.

'연결할 수 없음'
기기에 연결할 수 없습니다.

'MISSING'
기기가 연결 해제되었습니다.

'INTERNAL_ERROR'
호출 애플리케이션 이외의 위치에서 오류가 발생했습니다.

OptionConstraint

Chrome 125 이상

속성

  • list

    string[] | number[] 선택사항

  • 최대

    번호 선택사항

  • 분

    번호 선택사항

  • quant

    번호 선택사항

OptionGroup

Chrome 125 이상

속성

  • 멤버

    문자열[]

    드라이버 제공 순서의 옵션 이름 배열입니다.

  • 제목

    문자열

    인쇄 가능한 제목을 제공합니다(예: '기하학 옵션').

OptionSetting

Chrome 125 이상

속성

  • 이름

    문자열

    설정할 옵션의 이름을 나타냅니다.

  • 유형

    OptionType

    옵션의 데이터 유형을 나타냅니다. 요청된 데이터 유형은 기본 옵션의 실제 데이터 유형과 일치해야 합니다.

  • 값

    string | number | boolean | number[] 선택사항

    설정할 값을 나타냅니다. autoSettable가 사용 설정된 옵션의 자동 설정을 요청하려면 설정되지 않은 상태로 둡니다. value에 제공된 데이터 유형은 type과 일치해야 합니다.

OptionType

Chrome 125 이상

옵션의 데이터 유형입니다.

열거형

'UNKNOWN'
옵션의 데이터 유형을 알 수 없습니다. value 속성이 설정 해제됩니다.

'BOOL'
value 속성은 truefalse 중 하나입니다.

'INT'
부호 있는 32비트 정수입니다. value 속성은 옵션이 두 개 이상의 값을 사용하는지에 따라 long 또는 long[]이 됩니다.

'FIXED'
범위가 -32768~32767.9999이고 해상도가 1/65535인 double입니다. value 속성은 옵션이 두 개 이상의 값을 사용하는지에 따라 double 또는 double[] 이 됩니다. 정확하게 표현할 수 없는 double 값은 사용 가능한 범위와 정밀도로 반올림됩니다.

'STRING'
NUL ('\0')을 제외한 모든 바이트의 시퀀스입니다. value 속성은 DOMString입니다.

'BUTTON'
이 유형의 옵션에는 값이 없습니다. 대신 이 유형의 옵션을 설정하면 스캐너 드라이버에서 옵션별 부작용이 발생합니다. 예를 들어 스캐너 드라이버는 버튼 유형 옵션을 사용하여 기본값을 선택하거나 자동 문서 공급기에 다음 용지로 이동하도록 지시할 수 있습니다.

'GROUP'
그룹화 옵션입니다. 값 없음. 이는 호환성을 위해 포함되지만 일반적으로 ScannerOption 값으로 반환되지 않습니다. getOptionGroups()를 사용하여 그룹 목록과 멤버 옵션을 가져옵니다.

OptionUnit

Chrome 125 이상

ScannerOption.unit의 데이터 유형을 나타냅니다.

열거형

'UNITLESS'
값이 단위가 없는 숫자입니다. 예를 들어 기준일 수 있습니다.

'PIXEL'
값은 픽셀 수입니다(예: 스캔 측정기준).

'BIT'
값은 비트 수입니다(예: 색상 심도).

'MM'
값은 밀리미터 단위로 측정됩니다(예: 스캔 크기).

'DPI'
값은 인치당 도트 수(예: 해상도)로 측정됩니다.

'PERCENT'
값이 백분율입니다(예: 밝기).

'MICROSECOND'
값이 마이크로초 단위로 측정됩니다(예: 노출 시간).

ReadScanDataResponse

Chrome 125 이상

속성

  • 데이터

    ArrayBuffer 선택사항

    result이 SUCCESS인 경우 스캔된 이미지 데이터의 다음 청크가 포함됩니다. result이 EOF인 경우 스캔된 이미지 데이터의 마지막 청크가 포함됩니다.

  • estimatedCompletion

    번호 선택사항

    result이 SUCCESS인 경우 지금까지 전송된 총 스캔 데이터의 양을 추정한 값입니다(범위: 0~100).

  • 작업

    문자열

    readScanData()에 전달된 작업 핸들을 제공합니다.

  • 데이터 읽기의 결과입니다. 값이 SUCCESS이면 data에는 읽을 준비가 된 이미지 데이터의 다음 청크 (길이가 0일 수 있음)가 포함됩니다. 값이 EOF이면 data에 이미지 데이터의 마지막 청크가 포함됩니다.

ScannerInfo

Chrome 125 이상

속성

  • connectionType

    ConnectionType

    스캐너가 컴퓨터에 연결된 방식을 나타냅니다.

  • deviceUuid

    문자열

    동일한 실제 기기를 가리키는 다른 ScannerInfo 항목과 일치하는 데 사용됩니다.

  • imageFormats

    문자열[]

    반환된 검사에 요청할 수 있는 MIME 유형의 배열입니다.

  • 제조업체

    문자열

    스캐너 제조업체입니다.

  • 모델

    문자열

    사용 가능한 경우 스캐너 모델 또는 일반 설명입니다.

  • 이름

    문자열

    UI에 표시할 스캐너의 사람이 읽을 수 있는 이름입니다.

  • protocolType

    문자열

    스캐너에 액세스하는 데 사용되는 프로토콜 또는 드라이버에 대해 사람이 읽을 수 있는 설명입니다(예: Mopria, WSD, epsonds). 이는 기기가 여러 프로토콜을 지원하는 경우 사용자가 프로토콜을 선택할 수 있도록 하는 데 주로 유용합니다.

  • scannerId

    문자열

    특정 스캐너의 ID입니다.

  • 보안

    부울

    true인 경우 스캐너 연결의 전송은 TLS나 USB와 같은 수동 리스너에 의해 가로채질 수 없습니다.

ScannerOption

Chrome 125 이상

속성

  • 구성 가능성

    구성 가능성

    옵션을 변경할 수 있는지 여부와 방법을 나타냅니다.

  • 제약조건

    OptionConstraint 선택사항

    현재 스캐너 옵션에서 OptionConstraint을 정의합니다.

  • 설명

    문자열

    옵션에 대한 자세한 설명입니다.

  • isActive

    부울

    옵션이 활성 상태이며 설정하거나 가져올 수 있음을 나타냅니다. false인 경우 value 속성이 설정되지 않습니다.

  • isAdvanced

    부울

    UI에서 이 옵션을 기본적으로 표시하지 않아야 함을 나타냅니다.

  • isAutoSettable

    부울

    스캐너 드라이버에 의해 자동으로 설정될 수 있습니다.

  • isDetectable

    부울

    이 옵션은 소프트웨어에서 감지할 수 있음을 나타냅니다.

  • isEmulated

    부울

    true인 경우 스캐너 드라이버에 의해 에뮬레이션됩니다.

  • 이름

    문자열

    소문자 ASCII 문자, 숫자, 대시를 사용하는 옵션 이름입니다. 발음 구별 기호는 허용되지 않습니다.

  • 제목

    문자열

    인쇄 가능한 한 줄 제목입니다.

  • 유형

    OptionType

    이 옵션을 설정하는 데 필요한 value 속성에 포함된 데이터 유형입니다.

  • 단위

    OptionUnit

    이 옵션의 측정 단위입니다.

  • 값

    string | number | boolean | number[] 선택사항

    관련된 경우 옵션의 현재 값입니다. 이 속성의 데이터 유형은 type에 지정된 데이터 유형과 일치해야 합니다.

ScanOptions

속성

  • maxImages

    번호 선택사항

    허용되는 스캔 이미지 수입니다. 기본값은 1입니다.

  • mimeTypes

    string[] 선택사항

    호출자가 허용하는 MIME 유형입니다.

ScanResults

속성

  • dataUrls

    문자열[]

    이미지 태그에 'src' 값으로 전달할 수 있는 형식의 데이터 이미지 URL 배열입니다.

  • mimeType

    문자열

    dataUrls의 MIME 유형입니다.

SetOptionResult

Chrome 125 이상

속성

  • 이름

    문자열

    설정된 옵션의 이름을 나타냅니다.

  • 옵션 설정 결과를 나타냅니다.

SetOptionsResponse

Chrome 125 이상

속성

  • 옵션

    객체 선택사항

    제공된 모든 옵션을 설정하려고 시도한 후의 새 구성을 포함하는 옵션 이름에서 ScannerOption 값으로의 업데이트된 키-값 매핑입니다. OpenScannerResponse의 options 속성과 구조가 같습니다.

    이 속성은 일부 옵션이 설정되지 않은 경우에도 설정되지만 업데이트된 구성을 가져오지 못하면 설정되지 않습니다 (예: 스캔 중에 스캐너가 연결 해제된 경우).

  • 결과

    SetOptionResult[]

    결과의 배열로, 전달된 각 OptionSetting에 하나씩 있습니다.

  • scannerHandle

    문자열

    setOptions()에 전달된 스캐너 핸들을 제공합니다.

StartScanOptions

Chrome 125 이상

속성

  • 형식

    문자열

    스캔된 데이터를 반환할 MIME 유형을 지정합니다.

  • maxReadSize

    번호 선택사항

    0이 아닌 값이 지정되면 단일 readScanData 응답에서 반환되는 최대 스캔 바이트가 해당 값으로 제한됩니다. 허용되는 최소값은 32768 (32KB)입니다. 이 속성을 지정하지 않으면 반환된 청크의 크기가 스캔된 전체 이미지만큼 클 수 있습니다.

StartScanResponse

Chrome 125 이상

속성

  • 작업

    문자열 선택사항

    result이 SUCCESS인 경우 스캔 데이터를 읽거나 작업을 취소하는 데 사용할 수 있는 핸들을 제공합니다.

  • 스캔 시작 결과입니다. 이 값이 SUCCESS이면 job 속성이 채워집니다.

  • scannerHandle

    문자열

    startScan()에 전달된 것과 동일한 스캐너 핸들을 제공합니다.

메서드

cancelScan()

Promise Chrome 125 이상 
chrome.documentScan.cancelScan(
  job: string,
  callback?: function,
): Promise<CancelScanResponse>

시작된 스캔을 취소하고 CancelScanResponse 객체로 확인되는 Promise를 반환합니다. 콜백이 사용되면 객체가 대신 콜백에 전달됩니다.

매개변수

  • 작업

    문자열

    startScan 호출에서 이전에 반환된 활성 검색 작업의 핸들입니다.

  • callback

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (response: CancelScanResponse) => void

반환 값

  • Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

closeScanner()

Promise Chrome 125 이상 
chrome.documentScan.closeScanner(
  scannerHandle: string,
  callback?: function,
): Promise<CloseScannerResponse>

전달된 핸들로 스캐너를 닫고 CloseScannerResponse 객체로 확인되는 Promise를 반환합니다. 콜백이 사용되면 객체가 대신 콜백에 전달됩니다. 응답이 성공이 아니더라도 제공된 핸들은 무효화되므로 추가 작업에 사용해서는 안 됩니다.

매개변수

  • scannerHandle

    문자열

    openScanner 호출에서 이전에 반환된 열린 스캐너의 핸들을 지정합니다.

  • callback

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (response: CloseScannerResponse) => void

반환 값

  • Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getOptionGroups()

Promise Chrome 125 이상 
chrome.documentScan.getOptionGroups(
  scannerHandle: string,
  callback?: function,
): Promise<GetOptionGroupsResponse>

이전에 openScanner에 의해 열린 스캐너에서 그룹 이름과 멤버 옵션을 가져옵니다. 이 메서드는 GetOptionGroupsResponse 객체로 확인되는 Promise를 반환합니다. 콜백이 이 함수에 전달되면 반환된 데이터가 대신 콜백에 전달됩니다.

매개변수

반환 값

  • Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getScannerList()

Promise Chrome 125 이상 
chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
): Promise<GetScannerListResponse>

사용 가능한 스캐너 목록을 가져오고 GetScannerListResponse 객체로 확인되는 Promise를 반환합니다. 콜백이 이 함수에 전달되면 반환된 데이터가 대신 콜백에 전달됩니다.

매개변수

반환 값

  • Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

openScanner()

Promise Chrome 125 이상 
chrome.documentScan.openScanner(
  scannerId: string,
  callback?: function,
): Promise<OpenScannerResponse>

독점 액세스를 위해 스캐너를 열고 OpenScannerResponse 객체로 확인되는 Promise를 반환합니다. 콜백이 이 함수에 전달되면 반환된 데이터가 대신 콜백에 전달됩니다.

매개변수

  • scannerId

    문자열

    열 스캐너의 ID입니다. 이 값은 getScannerList에 대한 이전 호출에서 반환된 값 중 하나입니다.

  • callback

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (response: OpenScannerResponse) => void

반환 값

  • Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

readScanData()

Promise Chrome 125 이상 
chrome.documentScan.readScanData(
  job: string,
  callback?: function,
): Promise<ReadScanDataResponse>

활성 작업 핸들에서 사용 가능한 다음 이미지 데이터 청크를 읽고 ReadScanDataResponse 객체로 확인되는 Promise를 반환합니다. 콜백이 사용되면 객체가 대신 콜백에 전달됩니다.

**참고:**응답 결과가 길이가 0인 data 멤버가 있는 SUCCESS인 것은 유효합니다. 이는 스캐너가 계속 작동하지만 아직 추가 데이터가 준비되지 않았음을 의미합니다. 발신자는 잠시 기다렸다가 다시 시도해야 합니다.

스캔 작업이 완료되면 응답에 EOF 결과 값이 포함됩니다. 이 응답에는 최종 0이 아닌 data 멤버가 포함될 수 있습니다.

매개변수

반환 값

  • Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

scan()

Promise 
chrome.documentScan.scan(
  options: ScanOptions,
  callback?: function,
): Promise<ScanResults>

문서 스캔을 실행하고 ScanResults 객체로 확인되는 Promise를 반환합니다. 콜백이 이 함수에 전달되면 반환된 데이터가 대신 콜백에 전달됩니다.

매개변수

  • 옵션

    ScanOptions

    스캔 매개변수를 포함하는 객체입니다.

  • callback

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (result: ScanResults) => void

반환 값

  • Promise<ScanResults>

    Chrome 96 이상

    Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

setOptions()

Promise Chrome 125 이상 
chrome.documentScan.setOptions(
  scannerHandle: string,
  options: OptionSetting[],
  callback?: function,
): Promise<SetOptionsResponse>

지정된 스캐너의 옵션을 설정하고 전달된 OptionSetting 객체의 순서대로 모든 값을 설정하려고 시도한 결과를 포함하는 SetOptionsResponse 객체로 확인되는 Promise를 반환합니다. 콜백이 사용되면 객체가 대신 콜백에 전달됩니다.

매개변수

  • scannerHandle

    문자열

    옵션을 설정할 스캐너의 핸들입니다. 이 값은 openScanner 호출에서 이전에 반환된 값이어야 합니다.

  • 옵션

    OptionSetting[]

    스캐너에 적용할 OptionSetting 객체 목록입니다.

  • callback

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (response: SetOptionsResponse) => void

반환 값

  • Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

startScan()

Promise Chrome 125 이상 
chrome.documentScan.startScan(
  scannerHandle: string,
  options: StartScanOptions,
  callback?: function,
): Promise<StartScanResponse>

지정된 스캐너에서 스캔을 시작하고 StartScanResponse로 확인되는 Promise를 반환합니다. 콜백이 사용되면 객체가 대신 콜백에 전달됩니다. 호출이 성공하면 스캔 데이터를 읽거나 스캔을 취소하는 후속 호출에 사용할 수 있는 작업 핸들이 응답에 포함됩니다.

매개변수

  • scannerHandle

    문자열

    열린 스캐너의 핸들입니다. 이 값은 openScanner 호출에서 이전에 반환된 값이어야 합니다.

  • 스캔에 사용할 옵션을 나타내는 StartScanOptions 객체입니다. StartScanOptions.format 속성은 스캐너의 ScannerInfo에 반환된 항목 중 하나와 일치해야 합니다.

  • callback

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (response: StartScanResponse) => void

반환 값

  • Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.