chrome.printing

重要: この API は ChromeOS でのみ動作します。

説明

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

権限

printing

対象

Chrome 81 以降 ChromeOS のみ

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

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

例

次の例は、printing 名前空間の各メソッドの使用を示しています。このコードは、extensions-samples GitHub リポジトリの api-samples/printing からコピーされたか、そのコードに基づいています。

cancelJob()

この例では、onJobStatusChanged ハンドラを使用して、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()

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

​​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 キーを使用します。（デフォルトはプリンタによって異なります）。値を変更するには、id が 'finishings' のオブジェクトである 1 つのメンバーを含む配列を指定します。この値は、印刷の終了時にロールをカットするプリンタの場合は '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 形式）。プロパティが欠落している可能性があります。

• ステータス

  PrinterStatus

  プリンタのステータス。

JobStatus

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

列挙型

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

「IN_PROGRESS」
印刷ジョブが印刷に送信されています。

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

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

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

Printer

プロパティ

• description

  文字列

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

• id

  文字列

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

• isDefault

  ブール値

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

• name

  文字列

  プリンタの名前。

• recentlyUsedRank

  number（省略可）

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

• ソース

  PrinterSource

  プリンタのソース（ユーザーまたはポリシーで構成）。

• uri

  文字列

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

PrinterSource

プリンタのソース。

列挙型

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

「ポリシー」
プリンタがポリシーで追加されました。

PrinterStatus

プリンタのステータス。

列挙型

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

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

「OUT_OF_INK」
プリンタのインクが切れています。プリンタは引き続き印刷ジョブを受け入れます。

「OUT_OF_PAPER」
プリンタに紙がありません。プリンタは引き続き印刷ジョブを受け入れます。

「OUTPUT_FULL」
プリンタの出力エリア（トレイなど）がいっぱいです。プリンタは引き続き印刷ジョブを受け入れます。

「PAPER_JAM」
プリンタに紙詰まりが発生しています。プリンタは引き続き印刷ジョブを受け入れます。

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

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

「UNREACHABLE」
プリンタにアクセスできず、印刷ジョブを受け入れません。

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

「利用可能」
プリンタは使用できます。

SubmitJobRequest

プロパティ

• ジョブ

  PrintJob

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

SubmitJobResponse

プロパティ

• jobId

  文字列（省略可）

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

• ステータス

  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()

Promise

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

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

パラメータ

• jobId

  文字列

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

• callback

  function 省略可

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

  () => void

戻り値

• Promise<void>

  Chrome 100 以降

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

getJobStatus()

Promise 保留中

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

印刷ジョブのステータスを返します。指定された jobId の印刷ジョブが存在しない場合、この呼び出しはランタイム エラーで失敗します。jobId: ステータスを返す印刷ジョブの ID。これは、SubmitJobResponse で受け取った ID と同じである必要があります。

パラメータ

• jobId

  文字列

• callback

  function 省略可

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

  (status: JobStatus) => void

  • ステータス

    JobStatus

戻り値

• Promise<JobStatus>

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

getPrinterInfo()

Promise

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

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

パラメータ

• printerId

  文字列

• callback

  function 省略可

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

  (response: GetPrinterInfoResponse) => void

  • レスポンス

    GetPrinterInfoResponse

戻り値

• Promise<GetPrinterInfoResponse>

  Chrome 100 以降

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

getPrinters()

Promise

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

デバイスで使用可能なプリンタのリストを返します。手動で追加したプリンタ、エンタープライズ プリンタ、検出されたプリンタが含まれます。

パラメータ

• callback

  function 省略可

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

  (printers: Printer[]) => void

  • printers

    プリンタ[]

戻り値

• Promise<Printer[]>

  Chrome 100 以降

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

submitJob()

Promise

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

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

パラメータ

• リクエスト

  SubmitJobRequest

• callback

  function 省略可

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

  (response: SubmitJobResponse) => void

  • レスポンス

    SubmitJobResponse

戻り値

• Promise<SubmitJobResponse>

  Chrome 100 以降

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

イベント

onJobStatusChanged

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

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

パラメータ

• callback

  関数

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

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

  • jobId

    文字列

  • ステータス

    JobStatus