chrome.documentScan

説明

chrome.documentScan API を使用すると、接続されたドキュメント スキャナから画像を検出、取得できます。

権限

documentScan

対象

Chrome 44 以降 ChromeOS のみ

Document Scan API

Document Scan API は、アプリや拡張機能が接続されたドキュメント スキャナでハードコピー ドキュメントの内容を表示できるように設計されています。

型

CancelScanResponse

Chrome 125 以降

プロパティ

  • ジョブ

    文字列

    cancelScan() に渡されたのと同じジョブハンドルを提供します。

  • 件の結果

    OperationResult

    バックエンドのキャンセル スキャン結果。結果が OperationResult.SUCCESS または OperationResult.CANCELLED の場合、スキャンはキャンセルされ、スキャナは新しいスキャンを開始する準備ができています。結果が OperationResult.DEVICE_BUSY の場合、スキャナはリクエストされたキャンセルをまだ処理しています。呼び出し元はしばらく待ってから、リクエストを再度試行する必要があります。その他の結果値は、再試行すべきではない永続的なエラーを示します。

CloseScannerResponse

Chrome 125 以降

プロパティ

  • 件の結果

    OperationResult

    スキャナを閉じた結果。この値が 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 の場合、スキャナ ドライバが提供する順序でオプション グループのリストを提供します。

  • 件の結果

    OperationResult

    オプション グループの取得結果。この値が SUCCESS の場合、groups プロパティが入力されます。

  • scannerHandle

    文字列

    getOptionGroups に渡されたものと同じスキャナ ハンドル。

GetScannerListResponse

Chrome 125 以降

プロパティ

  • 件の結果

    OperationResult

    列挙結果。エラーが示されている場合でも、部分的な結果が返されることがあります。

  • スキャナ

    ScannerInfo[]

    指定された DeviceFilter に一致するスキャナのリスト（空の場合もあります）。

OpenScannerResponse

Chrome 125 以降

プロパティ

  • オプション

    オブジェクト 省略可

    result が SUCCESS の場合、キーがデバイス固有のオプションで、値が ScannerOption のインスタンスであるキーと値のマッピングを提供します。

  • 件の結果

    OperationResult

    スキャナを開いた結果。この値が SUCCESS の場合、scannerHandle プロパティと options プロパティが入力されます。

  • scannerHandle

    文字列 省略可

    result が SUCCESS の場合、以降のオペレーションで使用できるスキャナのハンドル。

  • scannerId

    文字列

    openScanner() に渡されるスキャナ ID。

OperationResult

Chrome 125 以降

各オペレーションの結果を示す列挙型。

列挙型

「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

Chrome 125 以降

プロパティ

  • list

    string[] | number[] 省略可

  • 最大

    number 省略可

  • 分

    number 省略可

  • quant

    number 省略可

OptionGroup

Chrome 125 以降

プロパティ

  • メンバー

    string[]

    ドライバが提供する順序のオプション名の配列。

  • title

    文字列

    印刷可能なタイトル（「Geometry options」など）を指定します。

OptionSetting

Chrome 125 以降

プロパティ

  • name

    文字列

    設定するオプションの名前を示します。

  • type

    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 の範囲の double。解像度は 1/65535。value プロパティは、オプションが複数の値を取るかどうかによって、double または double[] になります。正確に表現できない double 値は、使用可能な範囲と精度に丸められます。

"STRING"
NUL（'\0'）を除く任意のバイトのシーケンス。value プロパティは DOMString になります。

「BUTTON」
このタイプのオプションには値がありません。代わりに、このタイプのオプションを設定すると、スキャナ ドライバでオプション固有の副作用が発生します。たとえば、スキャナ ドライバはボタン型のオプションを使用して、デフォルト値を選択する手段を提供したり、自動原稿送り装置に次の用紙に進むよう指示したりできます。

「GROUP」
グループ化オプション。値なし。これは互換性のために含まれていますが、通常は ScannerOption 値で返されません。getOptionGroups() を使用して、メンバー オプションを含むグループのリストを取得します。

OptionUnit

Chrome 125 以降

ScannerOption.unit のデータ型を示します。

列挙型

「UNITLESS」
値は単位のない数値です。たとえば、しきい値などです。

「PIXEL」
値はピクセル数です（スキャン ディメンションなど）。

「BIT」
値はビット数です（色の深度など）。

「MM」
値はミリメートル単位で測定されます（スキャン ディメンションなど）。

「DPI」
値は 1 インチあたりのドット数で測定されます（解像度など）。

「PERCENT」
値はパーセントです（明るさなど）。

「MICROSECOND」
値はマイクロ秒単位で測定されます（露出時間など）。

ReadScanDataResponse

Chrome 125 以降

プロパティ

  • データ

    ArrayBuffer 省略可

    result が SUCCESS の場合、スキャンされた画像データの次のチャンクが含まれます。result が EOF の場合、スキャンされた画像データの最後のチャンクが含まれます。

  • estimatedCompletion

    number 省略可

    result が SUCCESS の場合、スキャンデータの合計のうち、これまでに配信されたデータの推定値（0 ～ 100 の範囲）。

  • ジョブ

    文字列

    readScanData() に渡されたジョブハンドルを提供します。

  • 件の結果

    OperationResult

    データの読み取り結果。値が SUCCESS の場合、data には読み取り可能な画像データの次の（長さがゼロの可能性もある）チャンクが含まれます。値が EOF の場合、data には画像データの最後のチャンクが含まれます。

ScannerInfo

Chrome 125 以降

プロパティ

  • connectionType

    ConnectionType

    スキャナがパソコンに接続されている方法を示します。

  • deviceUuid

    文字列

    同じ物理デバイスを指す他の ScannerInfo エントリとの照合。

  • imageFormats

    string[]

    返されるスキャンでリクエストできる MIME タイプの配列。

  • メーカー

    文字列

    スキャナの製造元。

  • モデル

    文字列

    スキャナモデル（利用可能な場合）または一般的な説明。

  • name

    文字列

    UI に表示するスキャナの人が読める形式の名前。

  • protocolType

    文字列

    スキャナへのアクセスに使用されるプロトコルまたはドライバ（Mopria、WSD、epsonds など）の、人が読める形式の説明。これは主に、デバイスが複数のプロトコルをサポートしている場合に、ユーザーがプロトコルを選択できるようにするために役立ちます。

  • scannerId

    文字列

    特定のスキャナの ID。

  • 安全

    ブール値

    true の場合、スキャナ接続のトランスポートは、TLS や USB などのパッシブ リスナーによってインターセプトできません。

ScannerOption

Chrome 125 以降

プロパティ

  • 構成の柔軟性

    構成可能性

    オプションを変更できるかどうかと、変更できる場合はその方法を示します。

  • 制約

    OptionConstraint（省略可）

    現在のスキャナ オプションで OptionConstraint を定義します。

  • 説明

    文字列

    オプションの詳しい説明。

  • isActive

    ブール値

    オプションがアクティブで、設定または取得できることを示します。false の場合、value プロパティは設定されません。

  • isAdvanced

    ブール値

    UI でこのオプションをデフォルトで表示しないことを示します。

  • isAutoSettable

    ブール値

    スキャナ ドライバによって自動的に設定できます。

  • isDetectable

    ブール値

    このオプションがソフトウェアから検出可能であることを示します。

  • isEmulated

    ブール値

    true の場合、スキャナ ドライバによってエミュレートされます。

  • name

    文字列

    小文字の ASCII 文字、数字、ダッシュを使用したオプション名。発音区別符号は使用できません。

  • title

    文字列

    印刷可能な 1 行のタイトル。

  • type

    OptionType

    このオプションの設定に必要な value プロパティに含まれるデータ型。

  • 単位

    OptionUnit

    このオプションの測定単位。

  • 値

    string | number | boolean | number[] 省略可

    オプションの現在の値（関連する場合）。このプロパティのデータ型は、type で指定されたデータ型と一致する必要があります。

ScanOptions

プロパティ

  • maxImages

    number 省略可

    スキャンできる画像の数。デフォルトは 1 です。

  • mimeTypes

    string[] 省略可

    呼び出し元で受け入れられる MIME タイプ。

ScanResults

プロパティ

  • dataUrls

    string[]

    イメージタグの「src」値として渡すことができる形式のデータ画像 URL の配列。

  • mimeType

    文字列

    dataUrls の MIME タイプ。

SetOptionResult

Chrome 125 以降

プロパティ

  • name

    文字列

    設定されたオプションの名前を示します。

  • 件の結果

    OperationResult

    オプションの設定結果を示します。

SetOptionsResponse

Chrome 125 以降

プロパティ

  • オプション

    オブジェクト 省略可

    指定されたすべてのオプションの設定を試みた後、新しい構成を含むオプション名から ScannerOption 値への更新された Key-Value マッピング。これは、OpenScannerResponse の options プロパティと同じ構造です。

    このプロパティは、一部のオプションが正常に設定されなかった場合でも設定されますが、更新された構成の取得に失敗した場合は設定解除されます（たとえば、スキャナがスキャン中に切断された場合など）。

  • 結果

    SetOptionResult[]

    渡された OptionSetting ごとに 1 つの結果を含む配列。

  • scannerHandle

    文字列

    setOptions() に渡されたスキャナ ハンドルを提供します。

StartScanOptions

Chrome 125 以降

プロパティ

  • 形式

    文字列

    スキャンしたデータを返す MIME タイプを指定します。

  • maxReadSize

    number 省略可

    ゼロ以外の値が指定されている場合、単一の readScanData レスポンスで返される最大スキャン バイト数をその値に制限します。最小許容値は 32768（32 KB）です。このプロパティが指定されていない場合、返されるチャンクのサイズはスキャンされた画像全体と同じくらい大きくなることがあります。

StartScanResponse

Chrome 125 以降

プロパティ

  • ジョブ

    文字列 省略可

    result が SUCCESS の場合、スキャンデータの読み取りやジョブのキャンセルに使用できるハンドルを提供します。

  • 件の結果

    OperationResult

    スキャンを開始した結果。この値が 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 を返します。コールバックがこの関数に渡されると、代わりに返されたデータがコールバックに渡されます。

パラメータ

  • scannerHandle

    文字列

    openScanner の呼び出しから返された、開いているスキャナのハンドル。

  • callback

    関数 省略可

    callback パラメータは次のようになります。 

    (response: GetOptionGroupsResponse) => void

戻り値

  • 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 を返します。コールバックが使用されている場合は、代わりにオブジェクトが渡されます。

**注:**レスポンス結果が SUCCESS で、長さがゼロの data メンバーを持つことは有効です。これは、スキャナはまだ動作しているが、追加のデータがまだ準備できていないことを意味します。発信者はしばらく待ってからもう一度お試しください。

スキャンジョブが完了すると、レスポンスに EOF の結果値が含まれます。このレスポンスには、最終的なゼロ以外の data メンバーが含まれている場合があります。

パラメータ

  • ジョブ

    文字列

    以前に startScan から返されたアクティブなジョブハンドル。

  • callback

    関数 省略可

    callback パラメータは次のようになります。 

    (response: ReadScanDataResponse) => void

戻り値

  • 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 オブジェクト。StartScanOptions.format プロパティは、スキャナの ScannerInfo で返されたエントリのいずれかと一致する必要があります。

  • callback

    関数 省略可

    callback パラメータは次のようになります。 

    (response: StartScanResponse) => void

戻り値

  • Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。