chrome.documentScan

説明

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

権限

documentScan

可用性

Chrome 44 以降 ChromeOS のみ

ドキュメント スキャン API

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

型

CancelScanResponse

Chrome 125 以降

プロパティ

  • ジョブ

    文字列

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

  • 件の結果

    OperationResult

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

CloseScannerResponse

Chrome 125 以降

プロパティ

  • 件の結果

    OperationResult

    スキャナを終了した結果。この値が SUCCESS でない場合でも、ハンドルは無効になるため、以降のオペレーションには使用しないでください。

  • scannerHandle

    文字列

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

Configurability

Chrome 125 以降

オプションの変更方法

列挙型

"NOT_CONFIGURABLE"
このオプションは読み取り専用です。

"SOFTWARE_CONFIGURABLE"
このオプションはソフトウェアで設定できます。

"HARDWARE_CONFIGURABLE"
このオプションは、ユーザーがスキャナのボタンを切り替えたり押したりすることで設定できます。

ConnectionType

Chrome 125 以降

スキャナがパソコンにどのように接続されているかを示します。

列挙型

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 のインスタンスである Key-Value マッピングを提供します。

  • 件の結果

    OperationResult

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

  • scannerHandle

    string（省略可）

    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 に十分なメモリがないため、操作を完了できません。

「接続できません」
デバイスにアクセスできません。

「MISSING」
デバイスの接続が解除されています。

"INTERNAL_ERROR"
呼び出し元のアプリケーション以外の場所でエラーが発生しました。

OptionConstraint

Chrome 125 以降

プロパティ

  • list

    string[]|number[] optional

  • max

    number（省略可）

  • 分

    number（省略可）

  • クオンツ

    number（省略可）

OptionGroup

Chrome 125 以降

プロパティ

  • メンバー

    string[]

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

  • title

    文字列

    印刷可能なタイトルを指定します（「ジオメトリ オプション」など）。

OptionSetting

Chrome 125 以降

プロパティ

  • name

    文字列

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

  • type

    OptionType

    オプションのデータ型を示します。リクエストするデータ型は、基になるオプションの実際のデータ型と一致する必要があります。

  • value

    string|number|boolean|number[] optional

    設定する値を示します。autoSettable が有効になっているオプションの自動設定をリクエストするには、未設定のままにします。value に指定するデータ型は type と一致する必要があります。

OptionType

Chrome 125 以降

オプションのデータタイプ。

列挙型

"UNKNOWN"
オプションのデータタイプが不明です。value プロパティは設定解除されます。

"BOOL"
value プロパティは、truefalse のいずれかになります。

"INT"
32 ビット符号付き整数。value プロパティは、オプションが複数の値を取るかどうかに応じて、long または long[] になります。

「修正済み」
-32768 ～ 32767.9999 の範囲の倍精度、解像度 1/65535。value プロパティは、オプションが複数の値を取るかどうかに応じて 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 タイプの配列。

  • メーカー

    文字列

    スキャナのメーカー。

  • model

    文字列

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

  • name

    文字列

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

  • protocolType

    文字列

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

  • scannerId

    文字列

    特定のスキャナの ID。

  • 安全

    boolean

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

ScannerOption

Chrome 125 以降

プロパティ

  • 構成の柔軟性

    構成の柔軟性

    オプションを変更できるかどうか、および変更できるかどうかを示します。

  • 制約

    OptionConstraint 省略可

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

  • description

    文字列

    オプションの詳細な説明。

  • isActive

    boolean

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

  • isAdvanced

    boolean

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

  • isAutoSettable

    boolean

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

  • isDetectable

    boolean

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

  • isEmulated

    boolean

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

  • name

    文字列

    小文字の ASCII 文字、数字、ダッシュを使用したオプション名。付加記号は使用できません。

  • title

    文字列

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

  • type

    OptionType

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

  • 単位

    OptionUnit

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

  • value

    string|number|boolean|number[] optional

    オプションの現在の値（該当する場合）。このプロパティのデータ型は、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（省略可）

    ゼロ以外の値を指定すると、1 回の readScanData レスポンスで返されるスキャンの最大バイト数をその値に制限します。指定できる最小値は 32,768（32 KB）です。このプロパティが指定されていない場合、返されるチャンクのサイズは、スキャンされたイメージ全体と同じ大きさになる可能性があります。

StartScanResponse

Chrome 125 以降

プロパティ

  • ジョブ

    string（省略可）

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

  • 件の結果

    OperationResult

    スキャンを開始した結果。この値が SUCCESS の場合、job プロパティに値が入力されます。

  • scannerHandle

    文字列

    startScan() に渡されたのと同じスキャナ ハンドルを提供します。

メソッド

cancelScan()

Promise Chrome 125 以降 
chrome.documentScan.cancelScan(
  job: string,
  callback?: function,
)

開始したスキャンをキャンセルし、CancelScanResponse オブジェクトで解決される Promise を返します。コールバックが使用されている場合は、代わりにオブジェクトが渡されます。

パラメータ

  • ジョブ

    文字列

    以前に startScan の呼び出しから返されたアクティブなスキャンジョブのハンドル。

  • callback

    関数（省略可）

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

    (response: CancelScanResponse)=>void

戻り値

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

closeScanner()

Promise Chrome 125 以降 
chrome.documentScan.closeScanner(
  scannerHandle: string,
  callback?: function,
)

渡されたハンドルでスキャナを閉じ、CloseScannerResponse オブジェクトで解決される Promise を返します。コールバックが使用されている場合は、代わりにオブジェクトが渡されます。レスポンスが成功でない場合でも、指定されたハンドルは無効になるため、以降のオペレーションには使用しないでください。

パラメータ

  • scannerHandle

    文字列

    以前に openScanner の呼び出しで返された、開いているスキャナのハンドルを指定します。

  • callback

    関数（省略可）

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

    (response: CloseScannerResponse)=>void

戻り値

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

getOptionGroups()

Promise Chrome 125 以降 
chrome.documentScan.getOptionGroups(
  scannerHandle: string,
  callback?: function,
)

以前に openScanner が開いたスキャナからグループ名とメンバー オプションを取得します。このメソッドは、GetOptionGroupsResponse オブジェクトで解決される Promise を返します。この関数にコールバックが渡されると、返されたデータが代わりに渡されます。

パラメータ

  • scannerHandle

    文字列

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

  • callback

    関数（省略可）

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

    (response: GetOptionGroupsResponse)=>void

戻り値

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

getScannerList()

Promise Chrome 125 以降 
chrome.documentScan.getScannerList(
  filter: DeviceFilter,
  callback?: function,
)

使用可能なスキャナのリストを取得し、GetScannerListResponse オブジェクトで解決される Promise を返します。この関数にコールバックが渡されると、返されたデータが代わりに渡されます。

パラメータ

戻り値

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

openScanner()

Promise Chrome 125 以降 
chrome.documentScan.openScanner(
  scannerId: string,
  callback?: function,
)

排他的なアクセスのためにスキャナを開き、OpenScannerResponse オブジェクトで解決される Promise を返します。この関数にコールバックが渡されると、返されたデータが代わりに渡されます。

パラメータ

  • scannerId

    文字列

    開くスキャナの ID。この値は、前回の getScannerList の呼び出しから返された値です。

  • callback

    関数（省略可）

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

    (response: OpenScannerResponse)=>void

戻り値

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

readScanData()

Promise Chrome 125 以降 
chrome.documentScan.readScanData(
  job: string,
  callback?: function,
)

アクティブなジョブハンドルから使用可能な画像データの次のチャンクを読み取り、ReadScanDataResponse オブジェクトで解決される Promise を返します。コールバックが使用されている場合は、代わりにオブジェクトが渡されます。

**注:**長さがゼロの data メンバーを含むレスポンス結果が SUCCESS になることは有効です。つまり、スキャナは動作していますが、追加のデータがまだ準備されていません。発信者はしばらく待ってから再試行する必要があります。

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

パラメータ

  • ジョブ

    文字列

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

  • callback

    関数（省略可）

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

    (response: ReadScanDataResponse)=>void

戻り値

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

scan()

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

ドキュメント スキャンを実行し、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,
)

指定されたスキャナにオプションを設定し、渡された 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,
)

指定されたスキャナのスキャンを開始し、StartScanResponse で解決される Promise を返します。コールバックが使用されている場合は、代わりにオブジェクトが渡されます。呼び出しが成功した場合、レスポンスには、スキャンデータの読み取りやスキャンのキャンセルなどの後続の呼び出しで使用できるジョブ ハンドルが含まれます。

パラメータ

  • scannerHandle

    文字列

    開いているスキャナのハンドル。これは、以前に openScanner の呼び出しで返された値になります。

  • オプション

    StartScanOptions

    スキャンに使用するオプションを示す StartScanOptions オブジェクト。StartScanOptions.format プロパティは、スキャナの ScannerInfo で返されるエントリのいずれかと一致する必要があります。

  • callback

    関数（省略可）

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

    (response: StartScanResponse)=>void

戻り値

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