説明
chrome.printing
API を使用して、Chromebook にインストールされているプリンタに印刷ジョブを送信します。
権限
printing
対象
マニフェスト
chrome.printing
のすべてのメソッドとイベントで、拡張機能のマニフェストで "printing"
権限を宣言する必要があります。次に例を示します。
{
"name": "My extension",
...
"permissions": [
"printing"
],
...
}
例
以下の例では、print 名前空間の各メソッドの使用方法を示しています。このコードは、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()
プリンタ情報を取得するには、getPrinters()
を呼び出してプリンタ ID を取得する必要があるため、これらの関数では 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
キーを使用します。(デフォルトの設定はプリンタによって異なります)。指定する場合、このキーは 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
プロパティ
-
capabilities
オブジェクト 省略可
CDD 形式のプリンタ機能。宿泊施設が欠落している可能性があります。
-
status
プリンタのステータス。
JobStatus
印刷ジョブのステータス。
Enum
"PENDING"
Chrome 側で印刷ジョブを受信しましたが、まだ処理されていません。
"IN_PROGRESS"
印刷ジョブが送信されました。
"FAILED"
エラーが発生したため、印刷ジョブが中断されました。
"CANCELED"
印刷ジョブがユーザーまたは API によってキャンセルされました。
"PRINTED"
印刷ジョブはエラーなしで印刷されました。
Printer
プロパティ
-
description
文字列
人が読める形式のプリンタの説明。
-
id
文字列
プリンタの識別子。デバイス上のプリンタ間で一意であることが保証されています。
-
isDefault
boolean
プリンタが DefaultPrinterSelection のルールに適合しているかどうかを示すフラグ。なお、一部のプリンタにはフラグが付けられている場合があります。
-
name
文字列
プリンタの名前。
-
recentlyUsedRank
number(省略可)
プリンタが Chrome からの印刷にどのくらい最近使用されたかを示す値。値が小さいほど、プリンタが最近使用されたことを示します。最小値は 0 です。値がない場合、プリンタが最近使用されていないことを示します。この値は、プリンタ間で一意であることが保証されています。
-
target
プリンタのソース(設定済みのユーザーまたはポリシー)。
-
uri
文字列
プリンタの URI。拡張機能はこれを使用して、ユーザーのプリンタを選択できます。
PrinterSource
プリンタのソース。
Enum
"USER"
プリンタはユーザーによって追加されました。
"POLICY"
プリンタはポリシーによって追加されました。
PrinterStatus
プリンタのステータス。
Enum
"DOOR_OPEN"
プリンタのドアが開いています。プリンタは印刷ジョブを引き続き受け入れます。
"TRAY_MISSING"
プリンタのトレイがありません。プリンタは印刷ジョブを引き続き受け入れます。
"OUT_OF_INK"
プリンタのインクがありません。プリンタは印刷ジョブを引き続き受け入れます。
"OUT_OF_PAPER"
プリンタの用紙がありません。プリンタは印刷ジョブを引き続き受け入れます。
"OUTPUT_FULL"
プリンタの出力領域(トレイ)がいっぱいです。プリンタは印刷ジョブを引き続き受け入れます。
"PAPER_JAM"
プリンタに紙が詰まっています。プリンタは印刷ジョブを引き続き受け入れます。
"GENERIC_ISSUE"
一般的な問題。プリンタは印刷ジョブを引き続き受け入れます。
"STOPPED"
プリンタは停止しており、印刷は行いませんが、印刷ジョブは引き続き受け付けます。
"UNREACHABLE"
プリンタにアクセスできないため、印刷ジョブを受け付けない。
"EXPIRED_CERTIFICATE"
SSL 証明書の有効期限が切れています。プリンタがジョブを受け入れますが、失敗します。
"AVAILABLE"
プリンタは使用できます。
SubmitJobRequest
プロパティ
-
ジョブ
送信する印刷ジョブ。サポートされているコンテンツ タイプは「application/pdf」のみです。Cloud Job Ticket には、ネイティブ印刷とは無関係な
FitToPageTicketItem
、PageRangeTicketItem
、ReverseOrderTicketItem
、VendorTicketItem
の各フィールドを含めないでください。その他のフィールドはすべて存在する必要があります。
SubmitJobResponse
プロパティ
-
jobId
string(省略可)
作成された印刷ジョブの ID。これは、デバイス上のすべての印刷ジョブ間で一意の識別子です。ステータスが OK でない場合、jobId が null になります。
-
status
リクエストのステータス。
SubmitJobStatus
submitJob
リクエストのステータス。
Enum
"OK"
送信した印刷ジョブ リクエストが承認されました。
"USER_REJECTED"
送信した印刷ジョブ リクエストがユーザーによって拒否されました。
プロパティ
MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE
getPrinterInfo
を 1 分あたりに呼び出せる最大回数。
値
20
MAX_SUBMIT_JOB_CALLS_PER_MINUTE
submitJob
を 1 分あたりに呼び出せる最大回数。
値
40
Methods
cancelJob()
chrome.printing.cancelJob(
jobId: string,
callback?: function,
)
以前に送信したジョブをキャンセルします。
パラメータ
-
jobId
文字列
キャンセルする印刷ジョブの ID。これは
SubmitJobResponse
で受け取った ID と同じである必要があります。 -
callback
関数(省略可)
callback
パラメータは次のようになります。() => void
戻り値
-
Promise<void>
Chrome 100 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
callback?: function,
)
プリンタのステータスと機能を CDD 形式で返します。指定された ID のプリンタがインストールされていない場合、この呼び出しはランタイム エラーで失敗します。
パラメータ
-
printerId
文字列
-
callback
関数(省略可)
callback
パラメータは次のようになります。(response: GetPrinterInfoResponse) => void
-
レスポンス
-
戻り値
-
Promise<GetPrinterInfoResponse>
Chrome 100 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
getPrinters()
chrome.printing.getPrinters(
callback?: function,
)
デバイスで使用可能なプリンタのリストを返します。これには、手動で追加したプリンタ、企業プリンタ、検出されたプリンタが含まれます。
戻り値
-
Promise<Printer[]>
Chrome 100 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
印刷ジョブを送信します。拡張機能が PrintingAPIExtensionsAllowlist
ポリシーにない場合、ユーザーは印刷ジョブを受け入れるように求められます。
Chrome 120 より前では、この関数は Promise を返しませんでした。
パラメータ
-
request
-
callback
関数(省略可)
callback
パラメータは次のようになります。(response: SubmitJobResponse) => void
-
レスポンス
-
戻り値
-
Promise<SubmitJobResponse>
Chrome 100 以降Promise は Manifest V3 以降でのみサポートされます。他のプラットフォームではコールバックを使用する必要があります。