Описание
Используйте API chrome.printing
для отправки заданий печати на принтеры, установленные на Chromebook.
Разрешения
printing
Доступность
Все методы и события chrome.printing
требуют, чтобы вы объявили разрешение "printing"
в манифесте расширения . Например:
{
"name": "My extension",
...
"permissions": [
"printing"
],
...
}
Примеры
В примерах ниже показано использование каждого из методов в пространстве имен печати. Этот код скопирован или основан на API-образцах/печати в репозитории расширений-образцов Github.
отменитьЗадание()
В этом примере используется обработчик 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() и getPrinterInfo()
Для этих функций используется один пример, поскольку для получения информации о принтере требуется идентификатор принтера, который получается с помощью вызова 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()
требует трех вещей.
- Структура
ticket
, определяющая, какие возможности принтера следует использовать. Если пользователю необходимо выбрать доступные возможности, вы можете получить их для конкретного принтера с помощьюgetPrinterInfo()
. - Структура
SubmitJobRequest
, которая определяет используемый принтер, а также файл или дату для печати. Эта структура содержит ссылку на структуруticket
. - Большой объект файла или данных для печати.
Вызов submitJob()
вызывает диалоговое окно с просьбой подтвердить печать. Используйте PrintingAPIExtensionsAllowlist
чтобы обойти подтверждение.
Это упрощенная версия примера печати. Обратите внимание, что ticket
прикреплен к структуре SubmitJobRequest
(строка 8), а данные для печати преобразуются в большой двоичный объект (строка 10). Получить идентификатор принтера (строка 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
. (Значение по умолчанию варьируется от принтера к принтеру.) Чтобы изменить значение, предоставьте массив с одним членом: объект с 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 . Имущество может отсутствовать.
- статус
Состояние принтера.
JobStatus
Статус задания печати.
Перечисление
"В ОЖИДАНИИ" "В ХОДЕ ВЫПОЛНЕНИЯ" "НЕУСПЕШНЫЙ" «ОТМЕНЕНО» "ПЕЧАТАННЫЙ"
Задание печати получено на стороне Chrome, но еще не обработано.
Задание печати отправлено на печать.
Задание печати было прервано из-за какой-то ошибки.
Задание печати было отменено пользователем или через API.
Задание на печать было напечатано без ошибок.
Printer
Характеристики
- описание
нить
Удобочитаемое описание принтера.
- идентификатор
нить
Идентификатор принтера; гарантированно будет уникальным среди принтеров на устройстве.
- isDefault
логическое значение
Флаг, показывающий, соответствует ли принтер правилам DefaultPrinterSelection . Обратите внимание, что можно пометить несколько принтеров.
- имя
нить
Имя принтера.
- недавноИспользованныйРанг
номер необязательно
Значение, показывающее, как давно принтер использовался для печати из Chrome. Чем ниже значение, тем позже использовался принтер. Минимальное значение — 0. Отсутствие значения указывает на то, что принтер в последнее время не использовался. Это значение гарантированно будет уникальным среди принтеров.
- источник
Источник принтера (настроен пользователем или политикой).
- ури
нить
URI принтера. Расширения могут использовать это для выбора принтера для пользователя.
PrinterSource
Источник принтера.
Перечисление
"ПОЛЬЗОВАТЕЛЬ" "ПОЛИТИКА"
Принтер был добавлен пользователем.
Принтер был добавлен через политику.
PrinterStatus
Состояние принтера.
Перечисление
"ДВЕРЬ_ОТКРЫТА" "TRAY_MISSING" "OUT_OF_INK" "OUT_OF_PAPER" "ВЫХОД_ПОЛНЫЙ" "ПАПЕР_ЗАЖИМ" "GENERIC_ISSUE" "ОСТАНОВЛЕНО" «НЕДОСТИЖИМЫЙ» "EXPIRED_CERTIFICATE" "ДОСТУПНЫЙ"
Дверца принтера открыта. Принтер по-прежнему принимает задания на печать.
Лоток принтера отсутствует. Принтер по-прежнему принимает задания на печать.
В принтере закончились чернила. Принтер по-прежнему принимает задания на печать.
В принтере закончилась бумага. Принтер по-прежнему принимает задания на печать.
Выходная область принтера (например, лоток) заполнена. Принтер по-прежнему принимает задания на печать.
В принтере застряла бумага. Принтер по-прежнему принимает задания на печать.
Какая-то общая проблема. Принтер по-прежнему принимает задания на печать.
Принтер остановлен и не печатает, но продолжает принимать задания на печать.
Принтер недоступен и не принимает задания на печать.
Срок действия SSL-сертификата истек. Принтер принимает задания, но они не выполняются.
Принтер имеется.
SubmitJobRequest
Характеристики
- работа
Задание на печать, которое необходимо отправить. Единственный поддерживаемый тип контента — «application/pdf», и билет облачного задания не должен включать поля
FitToPageTicketItem
,PageRangeTicketItem
,ReverseOrderTicketItem
иVendorTicketItem
, поскольку они не имеют значения для собственной печати. Все остальные поля должны присутствовать.
SubmitJobResponse
Характеристики
- идентификатор вакансии
строка необязательна
Идентификатор созданного задания печати. Это уникальный идентификатор среди всех заданий печати на устройстве. Если статус не в порядке, jobId будет нулевым.
- статус
Статус запроса.
SubmitJobStatus
Статус запроса submitJob
.
Перечисление
"ХОРОШО" "USER_REJECTED"
Отправленный запрос на печать принят.
Отправленный запрос на печать отклонен пользователем.
Характеристики
MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE
Максимальное количество вызовов getPrinterInfo
в минуту.
Ценить
20
MAX_SUBMIT_JOB_CALLS_PER_MINUTE
Максимальное количество вызовов submitJob
в минуту.
Ценить
40
Методы
cancelJob()
chrome.printing.cancelJob(
jobId: string,
callback?: function,
)
Отменяет ранее отправленное задание.
Параметры
- идентификатор вакансии
нить
Идентификатор задания печати, которое необходимо отменить. Это должен быть тот же идентификатор, который был получен в
SubmitJobResponse
. - перезвонить
функция необязательна
Параметр
callback
выглядит так:() => void
Возврат
Обещание<void>
Хром 100+Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
callback?: function,
)
Возвращает состояние и возможности принтера в формате CDD . Этот вызов завершится ошибкой времени выполнения, если принтеры с данным идентификатором не установлены.
Параметры
- идентификатор принтера
нить
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(response: GetPrinterInfoResponse) => void
- ответ
Возврат
Обещание < GetPrinterInfoResponse >
Хром 100+Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
getPrinters()
chrome.printing.getPrinters(
callback?: function,
)
Возвращает список доступных принтеров на устройстве. Сюда входят добавленные вручную, корпоративные и обнаруженные принтеры.
Параметры
Возврат
Обещание< Принтер []>
Хром 100+Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
Отправляет задание на печать. Если расширение не указано в политике PrintingAPIExtensionsAllowlist
, пользователю будет предложено принять задание на печать. До Chrome 120 эта функция не возвращала обещание.
Параметры
- запрос
- перезвонить
функция необязательна
Параметр
callback
выглядит так:(response: SubmitJobResponse) => void
- ответ
Возврат
Обещание < SubmitJobResponse >
Хром 100+Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.
События
onJobStatusChanged
chrome.printing.onJobStatusChanged.addListener(
callback: function,
)
Событие возникает при изменении статуса задания. Это запускается только для заданий, созданных этим расширением.
Параметры
- перезвонить
функция
Параметр
callback
выглядит так:(jobId: string, status: JobStatus) => void
- идентификатор вакансии
нить
- статус