хром.печать

Описание

Используйте API chrome.printing для отправки заданий печати на принтеры, установленные на Chromebook.

Разрешения

printing

Доступность

Chrome 81+ только для ChromeOS

Все методы и события 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,
)

Возвращает список доступных принтеров на устройстве. Сюда входят добавленные вручную, корпоративные и обнаруженные принтеры.

Параметры

  • перезвонить

    функция необязательна

    Параметр callback выглядит так:

    (printers: Printer[]) => void

Возврат

  • Обещание< Принтер []>

    Хром 100+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

submitJob()

Обещать
chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
)

Отправляет задание на печать. Если расширение не указано в политике PrintingAPIExtensionsAllowlist , пользователю будет предложено принять задание на печать. До Chrome 120 эта функция не возвращала обещание.

Параметры

Возврат

  • Обещание < SubmitJobResponse >

    Хром 100+

    Промисы поддерживаются в Манифесте V3 и более поздних версиях, но обратные вызовы предусмотрены для обратной совместимости. Вы не можете использовать оба при одном вызове функции. Промис разрешается с тем же типом, который передается в обратный вызов.

События

onJobStatusChanged

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

Событие возникает при изменении статуса задания. Это запускается только для заданий, созданных этим расширением.

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так:

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