chrome.printing

重要: この API は ChromeOS でのみ機能します。

説明

chrome.printing API を使用して、Chromebook にインストールされたプリンタに印刷ジョブを送信します。

権限

printing

対象

Chrome 81 以降 ChromeOS のみ をご覧ください。

すべての chrome.printing メソッドとイベントでは、拡張機能のマニフェストで "printing" 権限を宣言する必要があります。例:

{
  "name": "My extension",
  ...
  "permissions": [
    "printing"
  ],
  ...
}

例

以下の例は、print 名前空間での各メソッドの使用方法を示しています。このコードは、extensions-samples GitHub リポジトリの api-samples/printing からコピーされるか、そのベースになります。

cancelJob()

この例では、onJobStatusChanged ハンドラを使用して「cancel」を非表示にしています。jobStatus が PENDING でも IN_PROGRESS でもない場合にボタン。ネットワークによっては、または Chromebook がプリンタに直接接続されている場合、これらの状態が急速に進行しすぎて、キャンセル ボタンが呼び出されるまで長く表示されないことがあります。これは非常に簡略化した印刷例です。

chrome.printing.onJobStatusChanged.addListener((jobId, status) => {
  const cancelButton = document.getElementById("cancelButton");
  cancelButton.addEventListener('click', () => {
    chrome.printing.cancelJob(jobId).then((response) => {
      if (response !== undefined) {
        console.log(response.status);
      }
      if (chrome.runtime.lastError !== undefined) {
        console.log(chrome.runtime.lastError.message);
      }
    });
  });
  if (status !== "PENDING" && status !== "IN_PROGRESS") {
    cancelButton.style.visibility = 'hidden';
  } else {
    cancelButton.style.visibility = 'visible';
  }
}

getPrinters() and getPrinterInfo()

これらの関数では 1 つの例を使用していますが、これはプリンタ情報を取得するにはプリンタ ID が必要で、プリンタ ID は getPrinters() を呼び出して取得するためです。この例では、デフォルト プリンタの名前と説明をコンソールに記録しています。これは、印刷例の簡略版です。

​​const printers = await chrome.printing.getPrinters();
const defaultPrinter = printers.find((printer) => {
  const printerInfo = await chrome.printing.getPrinterInfo(printer.id);
  return printerInfo.isDefault;
}
console.log(`Default printer: ${defaultPrinter.name}.\n\t${defaultPrinter.description}`);

submitJob()

submitJob() メソッドには 3 つのものが必要です。

• 使用するプリンタの機能を指定する ticket 構造体。ユーザーが利用可能な機能から選択する必要がある場合は、getPrinterInfo() を使用して特定のプリンタ用に取得できます。
• SubmitJobRequest 構造体。使用するプリンタ、印刷するファイルまたは日付を指定します。この構造体には、ticket 構造体への参照が含まれています。
• 印刷するファイルまたはデータの blob。

submitJob() を呼び出すと、印刷を確認するダイアログ ボックスがユーザーに表示されます。PrintingAPIExtensionsAllowlist を使用して確認を省略します。

これは、印刷例の簡略版です。ticket が SubmitJobRequest 構造体にアタッチされ（8 行目）、出力するデータが blob に変換されます（10 行目）。プリンタの ID（1 行目）を取得する方法は、サンプルではここで示されているよりも複雑です。

const defaultPrinter = getDefaultPrinter();
const ticket = getPrinterTicket(defaultPrinter);
const arrayBuffer = getPrintData();
const submitJobRequest = {
  job: {
    printerId: defaultPrinter,
    title: 'test job',
    ticket: ticket,
    contentType: 'application/pdf',
    document: new Blob([new Uint8Array(arrayBuffer)], {
      type: 'application/pdf'
    });
  }
};

chrome.printing.submitJob(submitJobRequest, (response) => {
  if (response !== undefined) {
    console.log(response.status);
  }
  if (chrome.runtime.lastError !== undefined) {
    console.log(chrome.runtime.lastError.message);
  }
});

ロール印刷

この例では、レシート印刷でよく使用される連続（ロール）印刷のプリンタ チケットを作成する方法を示します。ロール印刷用の submitJobRequest オブジェクトは、submitJob() の例で示したオブジェクトと同じです。

用紙切り取りのデフォルト値を変更する必要がある場合は、vendor_ticket_item キーを使用します。（デフォルトはプリンタによって異なります）。値を変更するには、メンバーを 1 つ（id が 'finishings' のオブジェクト）配列を指定します。印刷の最後にロールをカットするプリンタの場合、値は 'trim' です。印刷ジョブを切断する必要があるプリンタの場合、値は 'none' です。

const ticket = {
  version: '1.0',
  print: {
    vendor_ticket_item: [{id: 'finishings', value: 'trim'}],
    color: {type: 'STANDARD_MONOCHROME'},
    duplex: {type: 'NO_DUPLEX'},
    page_orientation: {type: 'PORTRAIT'},
    copies: {copies: 1},
    dpi: {horizontal_dpi: 300, vertical_dpi: 300},
    media_size: {
      width_microns: 72320,
      height_microns: 100000
    },
    collate: {collate: false}
  }
};

一部のプリンタは "finishings" オプションに対応していません。プリンタが対応しているかどうかを確認するには、getPrinterInfo() を呼び出して "finishings/11" の "display_name" を探します。

"vendor_capability": [
  {
    "display_name": "finishings/11",
    "id": "finishings/11",
    "type": "TYPED_VALUE",
    "typed_value_cap": {
      "value_type": "BOOLEAN"
    }
  },
  ...
]

注: Chrome 124 以降では、vendor_ticket_item によりプリンタの vendor_capabilities のすべてのアイテムが許可されます。たとえば、getPrinterInfo() が返す値はすべて有効です。以前は、finishings キーのみがサポートされていました。

チケットの media_size キーの値はプリンタごとに固有です。適切なサイズを選択するには、getPrinterInfo() を呼び出します。返される GetPrinterResponse には、"media_size"."option" でサポートされているメディアサイズの配列が含まれます。"is_continuous_feed" の値が true であるオプションを選択します。チケットの高さと幅の値を使用します。

"media_size": {
  "option": [
  {
    "custom_display_name": "",
    "is_continuous_feed": true,
    "max_height_microns": 2000000,
    "min_height_microns": 25400,
    "width_microns": 50800
  },
  ...
  ]
}

型

GetPrinterInfoResponse

プロパティ

• 機能

  オブジェクト（省略可）

  CDD 形式のプリンタ機能。宿泊施設が含まれていない可能性があります。

• status

  PrinterStatus

  プリンタのステータス。

JobStatus

印刷ジョブのステータス。

列挙型

"PENDING"
印刷ジョブは Chrome 側で受信されましたが、まだ処理されていません。

"IN_PROGRESS"
印刷ジョブは印刷のために送信されました。

「FAILED」
エラーが発生したため、印刷ジョブが中断されました。

「CANCELED」
ユーザーまたは API によって印刷ジョブがキャンセルされました。

「PRINTED」
印刷ジョブはエラーなしで印刷されました。

Printer

プロパティ

• description

  文字列

  人が読める形式のプリンタの説明。

• id

  文字列

  プリンタの ID。デバイス上のプリンタ間で一意であることが保証されます。

• isDefault

  ブール値

  プリンタが DefaultPrinterSelection ルールに適合しているかどうかを示すフラグ。複数のプリンタにフラグが付けられている場合があります。

• name

  文字列

  プリンタの名前。

• recentlyUsedRank

  数値（省略可）

  Chrome からの印刷にプリンタが使用された日時を示す値です。値が小さいほど、プリンタが最後に使われたことを示します。最小値は 0 です。値がない場合は、プリンタが最近使用されていないことを示します。この値はプリンタ間で一意であることが保証されています。

• ソース

  PrinterSource

  プリンタの提供元（ユーザーまたはポリシーの設定）。

• uri

  文字列

  プリンタの URI。拡張機能がユーザーのプリンタを選択するためにこれを使用します。

PrinterSource

プリンタのソース。

列挙型

"USER"
プリンタはユーザーによって追加されました。

"POLICY"
プリンタはポリシーによって追加されました。

PrinterStatus

プリンタのステータス。

列挙型

"DOOR_OPEN"
プリンタのドアが開いています。プリンタは引き続き印刷ジョブを受け付けます。

"TRAY_MISSING"
プリンタのトレイがありません。プリンタは引き続き印刷ジョブを受け付けます。

"OUT_OF_INK"
プリンタのインクがありません。プリンタは引き続き印刷ジョブを受け付けます。

"OUT_OF_PAPER"
プリンタの用紙がありません。プリンタは引き続き印刷ジョブを受け付けます。

"OUTPUT_FULL"
プリンタの出力領域（トレイなど）がいっぱいです。プリンタは引き続き印刷ジョブを受け付けます。

"PAPER_JAM"
プリンタで紙詰まりが発生しています。プリンタは引き続き印刷ジョブを受け付けます。

"GENERIC_ISSUE"
一般的な問題。プリンタは引き続き印刷ジョブを受け付けます。

「STOPPED」
プリンタは停止しており、印刷はされませんが、印刷ジョブは受け付けます。

"UNREACHABLE"
プリンタにアクセスできないため、印刷ジョブを受け付けません。

"EXPIRED_CERTIFICATE"
SSL 証明書の有効期限が切れています。プリンタはジョブを受け付けるが失敗する。

"AVAILABLE"
プリンタは使用可能です。

SubmitJobRequest

プロパティ

• ジョブ

  PrintJob

  送信する印刷ジョブ。サポートされているコンテンツ タイプは「application/pdf」のみです。Cloud Job Ticket には、FitToPageTicketItem、PageRangeTicketItem、ReverseOrderTicketItem、VendorTicketItem フィールドはネイティブ印刷には無関係であるため、含めないでください。その他のフィールドはすべて指定する必要があります。

SubmitJobResponse

プロパティ

• jobId

  文字列（省略可）

  作成された印刷ジョブの ID。デバイス上のすべての印刷ジョブの一意の識別子です。ステータスが OK でない場合、jobId は null になります。

• status

  SubmitJobStatus

  リクエストのステータス。

SubmitJobStatus

submitJob リクエストのステータス。

列挙型

「OK」
送信済みの印刷ジョブ リクエストは受け入れられます。

"USER_REJECTED"
送信した印刷ジョブ リクエストがユーザーによって拒否されました。

プロパティ

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

1 分間に getPrinterInfo を呼び出せる最大回数。

値

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

1 分間に submitJob を呼び出せる最大回数。

値

40

メソッド

cancelJob()

<ph type="x-smartling-placeholder"></ph> 約束

chrome.printing.cancelJob(
  jobId: string,
  callback?: function,
)

以前に送信したジョブをキャンセルします。

パラメータ

• jobId

  文字列

  キャンセルする印刷ジョブの ID。SubmitJobResponse で受け取った ID と同じものである必要があります。

• callback

  関数（省略可）

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

  () => void

戻り値

• 約束 <void>

  Chrome 100 以降

  Promise は Manifest V3 以降でサポートされていますが、 下位互換性が確保されます同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

getPrinterInfo()

<ph type="x-smartling-placeholder"></ph> 約束

chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
)

プリンタのステータスと機能を CDD 形式で返します。この呼び出しは、指定された ID のプリンタがインストールされていない場合、ランタイム エラーで失敗します。

パラメータ

• printerId

  文字列

• callback

  関数（省略可）

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

  (response: GetPrinterInfoResponse) => void

  • レスポンス

    GetPrinterInfoResponse

戻り値

• Promise&lt;GetPrinterInfoResponse&gt;

  Chrome 100 以降

  Promise は Manifest V3 以降でサポートされていますが、 下位互換性が確保されます同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

getPrinters()

<ph type="x-smartling-placeholder"></ph> 約束

chrome.printing.getPrinters(
  callback?: function,
)

デバイスで使用可能なプリンタのリストを返します。これには、手動で追加したプリンタ、企業向けプリンタ、検出されたプリンタも含まれます。

パラメータ

• callback

  関数（省略可）

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

  (printers: Printer[]) => void

  • printers

    プリンタ[]

戻り値

• Promise<Printer[]>

  Chrome 100 以降

  Promise は Manifest V3 以降でサポートされていますが、 下位互換性が確保されます同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

submitJob()

<ph type="x-smartling-placeholder"></ph> 約束

chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
)

印刷するジョブを送信します。拡張機能が PrintingAPIExtensionsAllowlist ポリシーに記載されていない場合、ユーザーは印刷ジョブを承認するよう求められます。 Chrome 120 より前では、この関数は Promise を返しませんでした。

パラメータ

• request

  SubmitJobRequest

• callback

  関数（省略可）

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

  (response: SubmitJobResponse) => void

  • レスポンス

    SubmitJobResponse

戻り値

• Promise&lt;SubmitJobResponse&gt;

  Chrome 100 以降

  Promise は Manifest V3 以降でサポートされていますが、 下位互換性が確保されます同じ関数呼び出しで両方を使用することはできません。「 Promise はコールバックに渡された型と同じ型で解決されます。

イベント

onJobStatusChanged

chrome.printing.onJobStatusChanged.addListener(
  callback: function,
)

ジョブのステータスが変更されたときに発生するイベント。これは、この拡張機能によって作成されたジョブに対してのみ呼び出されます。

パラメータ

• callback

  関数

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

  (jobId: string, status: JobStatus) => void

  • jobId

    文字列

  • status

    JobStatus