chrome.printing

refresh date: 2026-09-25 robots: noindex

Описание

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

Разрешения

printing

Доступность

Chrome 81 и более поздних версий Только для ChromeOS

Манифест

Для всех методов и событий chrome.printing необходимо объявить разрешение "printing" в манифесте расширения. Пример:

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

Примеры

В примерах ниже показано, как использовать каждый из методов в пространстве имен printing. Этот код скопирован или основан на api-samples/printing в репозитории extensions-samples на GitHub.

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(). В этом примере в консоль записывается название и описание принтера по умолчанию. Это упрощенная версия примера печати.

​​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() требуется три вещи.

  • Структура ticket, указывающая, какие возможности принтера следует использовать. Если пользователю нужно выбрать из доступных возможностей, вы можете получить их для определенного принтера с помощью getPrinterInfo().
  • Структура SubmitJobRequest, которая указывает, какой принтер использовать, а также файл или дату для печати. Эта структура содержит ссылку на структуру ticket.
  • Объект Blob, содержащий файл или данные для печати.

Вызов submitJob() открывает диалоговое окно, в котором пользователю предлагается подтвердить печать. Чтобы пропустить подтверждение, используйте PrintingAPIExtensionsAllowlist.

Это упрощенная версия примера печати. Обратите внимание, что ticket прикреплен к структуре SubmitJobRequest (строка 8), а данные для печати преобразованы в blob-объект (строка 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. Возможно, свойство отсутствует.

  • статус

    PrinterStatus

    Статус принтера.

JobStatus

Статус задания печати.

Перечисление

PENDING
Задание печати получено Chrome, но ещё не обработано.

"IN_PROGRESS"
Задание отправлено на печать.

FAILED
Задание печати было прервано из-за ошибки.

CANCELED
Задание печати отменено пользователем или через API.

"PRINTED"
Задание печати выполнено без ошибок.

Printer

Свойства

  • описание

    string

    Человекочитаемое описание принтера.

  • id

    string

    Идентификатор принтера, уникальный для принтеров на устройстве.

  • isDefault

    Логическое значение

    Флаг, который показывает, соответствует ли принтер правилам DefaultPrinterSelection. Обратите внимание, что помечены могут быть несколько принтеров.

  • name

    string

    Название принтера.

  • recentlyUsedRank

    number (необязательно)

    Значение, показывающее, как давно принтер использовался для печати из Chrome. Чем меньше значение, тем недавно использовался принтер. Минимальное значение – 0. Если значение отсутствует, значит принтер не использовался в последнее время. Это значение гарантированно уникально для каждого принтера.

  • source

    PrinterSource

    Источник принтера (настроенный пользователем или правилом).

  • URI

    string

    URI принтера. Расширения могут использовать это свойство, чтобы выбрать принтер для пользователя.

PrinterSource

Источник принтера.

Перечисление

USER
Принтер добавлен пользователем.

POLICY
Принтер добавлен с помощью правила.

PrinterStatus

Статус принтера.

Перечисление

"DOOR_OPEN"
Дверца принтера открыта. Принтер по-прежнему принимает задания печати.

TRAY_MISSING
Отсутствует лоток принтера. Принтер по-прежнему принимает задания печати.

"OUT_OF_INK"
В принтере закончились чернила. Принтер по-прежнему принимает задания печати.

"OUT_OF_PAPER"
В принтере закончилась бумага. Принтер по-прежнему принимает задания печати.

"OUTPUT_FULL"
Выходная область принтера (например, лоток) заполнена. Принтер по-прежнему принимает задания печати.

"PAPER_JAM"
В принтере застряла бумага. Принтер по-прежнему принимает задания печати.

"GENERIC_ISSUE"
Общая проблема. Принтер по-прежнему принимает задания печати.

STOPPED
Принтер остановлен и не печатает, но по-прежнему принимает задания на печать.

UNREACHABLE
Принтер недоступен и не принимает задания на печать.

"EXPIRED_CERTIFICATE"
Срок действия SSL-сертификата истек. Принтер принимает задания, но не выполняет их.

AVAILABLE
Принтер доступен.

SubmitJobRequest

Свойства

  • работа

    PrintJob

    Задание печати, которое нужно отправить. Поддерживаемые типы контента: application/pdf и image/png. Билет на задание облачной печати не должен содержать поля FitToPageTicketItem, PageRangeTicketItem и ReverseOrderTicketItem, поскольку они не имеют отношения к встроенной печати. VendorTicketItem – необязательный параметр. Все остальные поля должны быть заполнены.

SubmitJobResponse

Свойства

  • jobId

    Строка (необязательно)

    Идентификатор созданного задания печати. Это уникальный идентификатор среди всех заданий печати на устройстве. Если статус не OK, то jobId будет иметь значение null.

  • статус

    SubmitJobStatus

    Статус запроса.

SubmitJobStatus

Статус запроса submitJob.

Перечисление

OK
Запрос на печать принят.

USER_REJECTED
Запрос на отправку задания печати отклонен пользователем.

Свойства

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

Максимальное количество вызовов getPrinterInfo в минуту.

Значение

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

Максимальное количество вызовов submitJob в минуту.

Значение

40

Методы

cancelJob()

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

Отменяет ранее отправленное задание.

Параметры

  • jobId

    string

    Идентификатор задания печати, которое нужно отменить. Это должен быть тот же идентификатор, который был получен в SubmitJobResponse.

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Promise<void>

    Chrome 100+

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getJobStatus()

Promise Chrome 135+ 
chrome.printing.getJobStatus(
  jobId: string,
  callback?: function,
): Promise<JobStatus>

Возвращает статус задания печати. Если задания печати с указанным jobId не существует, вызов завершится ошибкой выполнения. jobId: идентификатор задания печати, статус которого нужно вернуть. Это должен быть тот же идентификатор, который был получен в SubmitJobResponse.

Параметры

  • jobId

    string

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (status: JobStatus) => void

Возвраты

  • Promise<JobStatus>

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getPrinterInfo()

Promise 
chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
): Promise<GetPrinterInfoResponse>

Возвращает статус и возможности принтера в формате CDD. Если принтеры с указанным идентификатором не установлены, вызов завершится ошибкой выполнения.

Параметры

  • printerId

    string

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (response: GetPrinterInfoResponse) => void

Возвраты

  • Chrome 100+

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

getPrinters()

Promise 
chrome.printing.getPrinters(
  callback?: function,
): Promise<Printer[]>

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

Параметры

  • обратный вызов

    function необязательно

    Параметр callback выглядит следующим образом: 

    (printers: Printer[]) => void

Возвраты

  • Promise<Printer[]>

    Chrome 100+

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

submitJob()

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

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

Параметры

Возвраты

  • Chrome 100+

    Объекты Promise поддерживаются только в Manifest V3 и более поздних версиях. На других платформах нужно использовать обратные вызовы.

События

onJobStatusChanged

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

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

Параметры

  • обратный вызов

    function

    Параметр callback выглядит следующим образом: 

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