chrome.printing

説明

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 ハンドラを使用して「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() と 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"
    }
  },
  ...
]

チケットの 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

    文字列

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

  • isDefault

    ブール値

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

  • name

    文字列

    プリンタの名前。

  • recentlyUsedRank

    number（省略可）

    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 になります。

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

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

    関数（省略可）

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

    () => void

戻り値

  • 約束 <void>

    Chrome 100 以降

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

getPrinterInfo()

<ph type="x-smartling-placeholder"></ph> 約束 
chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
)

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

パラメータ

戻り値

  • Promise&lt;GetPrinterInfoResponse&gt;

    Chrome 100 以降

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

getPrinters()

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

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

パラメータ

  • callback

    関数（省略可）

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

    (printers: Printer[]) => void

戻り値

  • Promise<Printer[]>

    Chrome 100 以降

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

submitJob()

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

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

パラメータ

戻り値

  • Promise&lt;SubmitJobResponse&gt;

    Chrome 100 以降

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

イベント

onJobStatusChanged

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

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

パラメータ

  • callback

    関数

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

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