chrome.printing

Deskripsi

Gunakan chrome.printing API untuk mengirim tugas cetak ke printer yang diinstal di Chromebook.

Izin

printing

Ketersediaan

Chrome 81+ Khusus ChromeOS

Semua metode dan peristiwa chrome.printing mengharuskan Anda mendeklarasikan izin "printing" di manifes ekstensi. Contoh:

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

Contoh

Contoh di bawah menunjukkan penggunaan setiap metode di namespace pencetakan. Kode ini disalin dari atau didasarkan pada api-samples/printing di repo GitHub extensions-samples.

cancelJob()

Contoh ini menggunakan pengendali onJobStatusChanged untuk menyembunyikan tombol 'batalkan' saat jobStatus bukan PENDING atau IN_PROGRESS. Perhatikan bahwa di beberapa jaringan atau saat Chromebook terhubung langsung ke printer, status ini mungkin berlalu terlalu cepat sehingga tombol batal tidak 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 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}`);

submitJob()

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 menggunakan getPrinterInfo().
  • Struktur SubmitJobRequest, yang menentukan printer yang akan digunakan, dan file atau tanggal yang akan dicetak. Struktur ini berisi referensi ke struktur ticket.
  • 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 ke struktur SubmitJobRequest (baris 8) dan data yang akan dicetak dikonversi menjadi blob (baris 10). Mendapatkan ID printer (baris 1) lebih rumit dalam contoh daripada yang ditampilkan 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 roll

Contoh ini menunjukkan cara membuat tiket printer untuk pencetakan berkelanjutan (atau roll), yang sering digunakan dengan pencetakan tanda terima. Objek submitJobRequest untuk pencetakan roll sama dengan yang ditampilkan untuk contoh submitJob().

Jika Anda perlu mengubah nilai default untuk pemotongan kertas, gunakan tombol vendor_ticket_item. (Default bervariasi dari printer ke printer.) Untuk mengubah nilai, berikan array dengan 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 mengharuskan tugas pencetakan disobek.

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" dari "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 khusus 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 lebarnya 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

    PrinterStatus

    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

    Flag yang menunjukkan apakah printer sesuai dengan aturan DefaultPrinterSelection. Perhatikan bahwa beberapa printer dapat ditandai.

  • nama

    string

    Nama printer.

  • recentlyUsedRank

    number opsional

    Nilai yang menunjukkan seberapa baru printer digunakan untuk mencetak dari Chrome. Makin rendah nilainya, makin 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

    PrinterSource

    Sumber printer (pengguna atau kebijakan yang dikonfigurasi).

  • uri

    string

    URI printer. Ini dapat digunakan oleh ekstensi untuk memilih printer bagi pengguna.

PrinterSource

Sumber printer.

Enum

"USER"
Printer was added by user.

"KEBIJAKAN"
Printer ditambahkan melalui kebijakan.

PrinterStatus

Status printer.

Enum

"DOOR_OPEN"
Tutup printer terbuka. Printer masih menerima tugas pencetakan.

"TRAY_MISSING"
Tray printer tidak ada. Printer masih menerima tugas pencetakan.

"OUT_OF_INK"
Printer kehabisan tinta. 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 dihentikan dan tidak mencetak, tetapi masih menerima tugas pencetakan.

"UNREACHABLE"
Printer tidak dapat dijangkau dan tidak menerima tugas pencetakan.

"EXPIRED_CERTIFICATE"
Masa berlaku sertifikat SSL telah berakhir. Printer menerima tugas, tetapi gagal.

"AVAILABLE"
Printer tersedia.

SubmitJobRequest

Properti

  • tugas

    PrintJob

    Tugas pencetakan yang akan dikirimkan. Satu-satunya jenis konten yang didukung adalah "application/pdf", dan Kartu Tugas Cloud tidak boleh menyertakan kolom FitToPageTicketItem, PageRangeTicketItem, ReverseOrderTicketItem, dan VendorTicketItem karena tidak relevan untuk pencetakan native. Semua kolom lainnya harus ada.

SubmitJobResponse

Properti

  • jobId

    string opsional

    ID tugas cetak yang dibuat. Ini adalah ID unik di antara semua tugas pencetakan di perangkat. Jika statusnya tidak OK, jobId akan menjadi null.

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

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

Membatalkan tugas yang sebelumnya dikirimkan.

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+

    Promise 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.

getJobStatus()

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

Menampilkan status tugas pencetakan. Panggilan ini akan gagal dengan error runtime jika tugas pencetakan dengan jobId yang diberikan tidak ada. jobId: ID tugas pencetakan yang akan menampilkan statusnya. ID ini harus sama dengan ID yang diterima di SubmitJobResponse.

Parameter

  • jobId

    string

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (status: JobStatus) => void

Hasil

  • Promise<JobStatus>

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

Promise 
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 diberikan yang diinstal.

Parameter

Hasil

  • Chrome 100+

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

Promise 
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

  • callback

    fungsi opsional

    Parameter callback terlihat seperti: 

    (printers: Printer[]) => void

Hasil

  • Promise<Printer[]>

    Chrome 100+

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

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

Mengirimkan tugas untuk dicetak. Jika ekstensi tidak tercantum dalam kebijakan PrintingAPIExtensionsAllowlist, pengguna akan diminta untuk menyetujui tugas pencetakan. Sebelum Chrome 120, fungsi ini tidak menampilkan promise.

Parameter

Hasil

  • Chrome 100+

    Promise 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.

Parameter

  • callback

    fungsi

    Parameter callback terlihat seperti: 

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