chrome.printing

説明

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

権限

printing

対象

Chrome 81 以降 ChromeOS のみ

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

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

例

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

cancelJob()

この例では、jobStatus が PENDING でも IN_PROGRESS でもない場合に、onJobStatusChanged ハンドラを使用して [キャンセル] ボタンを非表示にします。一部のネットワークや、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 が必要になるため、1 つの例が使用されます。プリンタ 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() を呼び出し、"display_name" が "finishings/11" であるかどうかを確認します。

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

チケットの 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 です。値がない場合は、プリンタが最近使用されていないことを示します。この値は、プリンタ間で一意であることが保証されています。

  • source

    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」と「image/png」です。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()

chrome.printing.cancelJob(
  jobId: string,
): Promise<void>

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

パラメータ

  • jobId

    文字列

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

戻り値

  • Promise<void>

    Chrome 100 以降

getJobStatus()

Chrome 135 以降 
chrome.printing.getJobStatus(
  jobId: string,
): Promise<JobStatus>

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

パラメータ

  • jobId

    文字列

戻り値

getPrinterInfo()

chrome.printing.getPrinterInfo(
  printerId: string,
): Promise<GetPrinterInfoResponse>

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

パラメータ

  • printerId

    文字列

戻り値

getPrinters()

chrome.printing.getPrinters(): Promise<Printer[]>

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

戻り値

  • Promise<Printer[]>

    Chrome 100 以降

submitJob()

chrome.printing.submitJob(
  request: SubmitJobRequest,
): Promise<SubmitJobResponse>

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

パラメータ

戻り値

イベント

onJobStatusChanged

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

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

パラメータ

  • callback

    関数

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

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