Deskripsi
Gunakan chrome.printing
API untuk mengirimkan tugas pencetakan ke printer yang diinstal di Chromebook.
Izin
printing
Ketersediaan
Semua metode dan peristiwa chrome.printing
mengharuskan Anda menyatakan izin "printing"
dalam manifes ekstensi. Contoh:
{
"name": "My extension",
...
"permissions": [
"printing"
],
...
}
Contoh
Contoh di bawah menunjukkan penggunaan masing-masing metode dalam namespace pencetakan. Kode ini disalin dari atau berdasarkan api-samples/printing di repo GitHub contoh ekstensi.
cancelJob()
Contoh ini menggunakan pengendali onJobStatusChanged
untuk menyembunyikan tombol 'cancel' jika jobStatus
bukan PENDING
atau IN_PROGRESS
. Perhatikan bahwa pada beberapa jaringan atau saat Chromebook terhubung langsung ke printer, status ini mungkin berjalan terlalu cepat sehingga tombol batal terlihat cukup lama untuk dipanggil. Ini adalah contoh pencetakan yang sangat disederhanakan.
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()
Satu contoh digunakan untuk fungsi ini karena untuk mendapatkan informasi printer memerlukan ID printer, yang diambil dengan memanggil getPrinters()
. Contoh ini mencatat nama dan deskripsi printer default ke konsol. Ini adalah versi sederhana dari contoh pencetakan.
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}`);
kirimJob()
Metode submitJob()
memerlukan tiga hal.
- Struktur
ticket
yang menentukan kemampuan printer yang akan digunakan. Jika pengguna perlu memilih dari kemampuan yang tersedia, Anda dapat mengambilnya untuk printer tertentu menggunakangetPrinterInfo()
. - Struktur
SubmitJobRequest
, yang menentukan printer yang akan digunakan, dan file atau tanggal untuk dicetak. Struktur ini berisi referensi ke strukturticket
. - Blob file atau data yang akan dicetak.
Memanggil submitJob()
akan memicu kotak dialog yang meminta pengguna untuk mengonfirmasi pencetakan. Gunakan PrintingAPIExtensionsAllowlist
untuk mengabaikan konfirmasi.
Ini adalah versi sederhana dari contoh pencetakan. Perhatikan bahwa ticket
dilampirkan pada struktur SubmitJobRequest
(baris 8) dan bahwa data yang akan dicetak dikonversi menjadi blob (baris 10). Mendapatkan ID printer (baris 1) lebih rumit dalam contoh daripada yang ditunjukkan di sini.
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);
}
});
Pencetakan gulungan
Contoh ini menunjukkan cara membuat tiket printer untuk pencetakan berkelanjutan (atau roll), yang sering digunakan dengan pencetakan tanda terima. Objek submitJobRequest
untuk pencetakan gulungan sama dengan yang ditunjukkan untuk contoh submitJob()
.
Jika Anda perlu mengubah nilai default untuk pemotong kertas, gunakan kunci vendor_ticket_item
. (Nilai defaultnya berbeda-beda untuk setiap printer.) Untuk mengubah nilai, sediakan array yang berisi satu anggota: objek yang id
-nya adalah 'finishings'
. Nilainya dapat berupa 'trim'
untuk printer yang memotong gulungan di akhir pencetakan atau 'none'
untuk printer yang memerlukan tugas pencetakan untuk dihapus.
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}
}
};
Beberapa printer tidak mendukung opsi "finishings"
. Untuk menentukan apakah printer Anda mendukungnya, panggil getPrinterInfo()
dan cari "display_name"
"finishings/11"
.
"vendor_capability": [
{
"display_name": "finishings/11",
"id": "finishings/11",
"type": "TYPED_VALUE",
"typed_value_cap": {
"value_type": "BOOLEAN"
}
},
...
]
Nilai dalam kunci media_size
tiket bersifat spesifik untuk setiap printer. Untuk memilih ukuran yang sesuai, panggil getPrinterInfo()
. GetPrinterResponse
yang ditampilkan berisi array ukuran media yang didukung di "media_size"."option"
. Pilih opsi yang nilai "is_continuous_feed"
-nya benar. Gunakan nilai tinggi dan lebar untuk tiket.
"media_size": {
"option": [
{
"custom_display_name": "",
"is_continuous_feed": true,
"max_height_microns": 2000000,
"min_height_microns": 25400,
"width_microns": 50800
},
...
]
}
Jenis
GetPrinterInfoResponse
Properti
-
capabilities
objek opsional
Kemampuan printer dalam format CDD. Properti mungkin tidak ada.
-
status
Status printer.
JobStatus
Status tugas pencetakan.
Enum
"TERTUNDA"
Tugas pencetakan diterima di sisi Chrome, tetapi belum diproses.
"IN_PROGRESS"
Tugas pencetakan dikirim untuk dicetak.
"FAILED"
Tugas pencetakan terganggu karena beberapa error.
"CANCELED"
Tugas pencetakan dibatalkan oleh pengguna atau melalui API.
"PRINTED"
Tugas pencetakan dicetak tanpa error.
Printer
Properti
-
deskripsi
string
Deskripsi printer yang dapat dibaca manusia.
-
id
string
ID printer; dijamin unik di antara printer di perangkat.
-
isDefault
boolean
Tanda yang menunjukkan apakah printer sesuai dengan aturan DefaultPrinterSelection. Perhatikan bahwa beberapa printer dapat ditandai.
-
name
string
Nama printer.
-
recentlyUsedRank
nomor opsional
Nilai menunjukkan seberapa baru printer digunakan untuk mencetak dari Chrome. Semakin rendah nilainya, semakin baru printer digunakan. Nilai minimumnya adalah 0. Nilai yang tidak ada menunjukkan bahwa printer tidak digunakan baru-baru ini. Nilai ini dijamin unik di antara printer.
-
source
Sumber printer (pengguna atau kebijakan telah dikonfigurasi).
-
uri
string
URI printer. Link ini dapat digunakan oleh ekstensi untuk memilih printer bagi pengguna.
PrinterSource
Sumber printer.
Enum
"PENGGUNA"
Printer ditambahkan oleh pengguna.
"POLICY"
Printer ditambahkan melalui kebijakan.
PrinterStatus
Status printer.
Enum
"DOOR_OPEN"
Pintu printer terbuka. Printer masih menerima tugas pencetakan.
"TRAY_MISSING"
Baki printer tidak ada. Printer masih menerima tugas pencetakan.
"OUT_OF_INK"
Tinta printer habis. Printer masih menerima tugas pencetakan.
"OUT_OF_PAPER"
Printer kehabisan kertas. Printer masih menerima tugas pencetakan.
"OUTPUT_FULL"
Area output printer (misalnya, baki) penuh. Printer masih menerima tugas pencetakan.
"PAPER_JAM"
Printer mengalami kertas macet. Printer masih menerima tugas pencetakan.
"GENERIC_ISSUE"
Beberapa masalah umum. Printer masih menerima tugas pencetakan.
"STOPPED"
Printer berhenti dan tidak mencetak, tetapi masih menerima tugas pencetakan.
"UNREACHABLE"
Printer tidak dapat dijangkau dan tidak menerima tugas pencetakan.
"EXPIRED_CERTIFICATE"
Masa berlaku sertifikat SSL sudah berakhir. Printer menerima tugas, tetapi gagal.
"AVAILABLE"
Printer tersedia.
SubmitJobRequest
Properti
-
tugas
Tugas pencetakan yang akan dikirimkan. Satu-satunya jenis konten yang didukung adalah "application/pdf", dan Cloud Job Ticket tidak boleh menyertakan kolom
FitToPageTicketItem
,PageRangeTicketItem
,ReverseOrderTicketItem
, danVendorTicketItem
karena tidak relevan untuk pencetakan native. Semua kolom lainnya harus ada.
SubmitJobResponse
Properti
-
jobId
string opsional
ID tugas pencetakan yang dibuat. ID ini adalah ID unik di antara semua tugas pencetakan pada perangkat. Jika statusnya tidak Oke, jobId akan null.
-
status
Status permintaan.
SubmitJobStatus
Status permintaan submitJob
.
Enum
"Oke"
Permintaan tugas pencetakan yang dikirim diterima.
"USER_REJECTED"
Permintaan tugas pencetakan yang dikirim ditolak oleh pengguna.
Properti
MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE
Frekuensi maksimum getPrinterInfo
dapat dipanggil per menit.
Nilai
20
MAX_SUBMIT_JOB_CALLS_PER_MINUTE
Frekuensi maksimum submitJob
dapat dipanggil per menit.
Nilai
40
Metode
cancelJob()
chrome.printing.cancelJob(
jobId: string,
callback?: function,
)
Membatalkan tugas yang dikirim sebelumnya.
Parameter
-
jobId
string
ID tugas pencetakan yang akan dibatalkan. ID ini harus sama dengan ID yang diterima di
SubmitJobResponse
. -
callback
fungsi opsional
Parameter
callback
terlihat seperti:() => void
Hasil
-
Promise<void>
Chrome 100 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
callback?: function,
)
Menampilkan status dan kemampuan printer dalam format CDD. Panggilan ini akan gagal dengan error runtime jika tidak ada printer dengan ID yang diinstal.
Parameter
-
printerId
string
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(response: GetPrinterInfoResponse) => void
-
respons
-
Hasil
-
Promise<GetPrinterInfoResponse>
Chrome 100 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
getPrinters()
chrome.printing.getPrinters(
callback?: function,
)
Menampilkan daftar printer yang tersedia di perangkat. Hal ini mencakup printer yang ditambahkan secara manual, printer perusahaan, dan printer yang ditemukan.
Parameter
Hasil
-
Promise<Printer[]>
Chrome 100 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
Mengirimkan tugas untuk dicetak. Jika ekstensi tidak tercantum dalam kebijakan PrintingAPIExtensionsAllowlist
, pengguna akan diminta untuk menerima tugas pencetakan.
Sebelum Chrome 120, fungsi ini tidak menampilkan promise.
Parameter
-
minta
-
callback
fungsi opsional
Parameter
callback
terlihat seperti:(response: SubmitJobResponse) => void
-
respons
-
Hasil
-
Promise<SubmitJobResponse>
Chrome 100 dan yang lebih baruPromise didukung di Manifes V3 dan yang lebih baru, tetapi callback disediakan untuk kompatibilitas mundur. Anda tidak dapat menggunakan keduanya pada panggilan fungsi yang sama. Promise di-resolve dengan jenis yang sama yang diteruskan ke callback.
Acara
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback: function,
)
Peristiwa diaktifkan saat status tugas diubah. Ini hanya diaktifkan untuk tugas yang dibuat oleh ekstensi ini.