browser.printing

설명

chrome.printing API를 사용하여 Chromebook에 설��된 프린터로 인쇄 작업을 전송합니다.

권한

printing

가용성

Chrome 81 이상 ChromeOS만 해당

모든 browser.printing 메서드와 이벤트는 확장 프로그램 매니페스트에서 "printing" 권한을 선언해야 합니다. 예를 들면 다음과 같습니다.

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

예

아래 예에서는 인쇄 네임스페이스의 각 메서드를 사용하는 방법을 보여줍니다. 이 코드는 extensions-samples Github 저장소의 api-samples/printing에서 복사하거나 이를 기반으로 합니다.

cancelJob()

이 예에서는 jobStatus이 PENDING도 IN_PROGRESS도 아닌 경우 onJobStatusChanged 핸들러를 사용하여 '취소' 버튼을 숨깁니다. 일부 네트워크에서 또는 Chromebook이 프린터에 직접 연결된 경우 이러한 상태가 너무 빨리 지나가 취소 버튼이 호출될 만큼 오랫동안 표시되지 않을 수 있습니다. 이 예는 인쇄를 크게 단순화한 것입니다.

browser.printing.onJobStatusChanged.addListener((jobId, status) => {
  const cancelButton = document.getElementById("cancelButton");
  cancelButton.addEventListener('click', () => {
    browser.printing.cancelJob(jobId).then((response) => {
      if (response !== undefined) {
        console.log(response.status);
      }
      if (browser.runtime.lastError !== undefined) {
        console.log(browser.runtime.lastError.message);
      }
    });
  });
  if (status !== "PENDING" && status !== "IN_PROGRESS") {
    cancelButton.style.visibility = 'hidden';
  } else {
    cancelButton.style.visibility = 'visible';
  }
}

getPrinters() and getPrinterInfo()

프린터 정보를 가져오려면 getPrinters()를 호출하여 가져오는 프린터 ID가 필요하므로 이러한 함수에는 단일 예가 사용됩니다. 이 예에서는 기본 프린터의 이름과 설명을 콘솔에 로깅합니다. 이 예는 인쇄 예의 간소화된 버전입니다.

​​const printers = await browser.printing.getPrinters();
const defaultPrinter = printers.find((printer) => {
  const printerInfo = await browser.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번째 줄). 프린터 ID 가져오기 (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'
    });
  }
};

browser.printing.submitJob(submitJobRequest, (response) => {
  if (response !== undefined) {
    console.log(response.status);
  }
  if (browser.runtime.lastError !== undefined) {
    console.log(browser.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()를 호출하고 "finishings/11"의 "display_name"를 찾습니다.

"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

속성

  • capabilities

    객체 선택사항

    CDD 형식의 프린터 기능 속성이 누락되었을 수 있습니다.

  • 상태

    프린터의 상태입니다.

JobStatus

인쇄 작업의 상태입니다.

열거형

'PENDING'
인쇄 작업이 Chrome 측에서 수신되었지만 아직 처리되지 않았습니다.

'IN_PROGRESS'
인쇄 작업이 인쇄를 위해 전송됩니다.

'FAILED'
오류로 인해 인쇄 작업이 중단되었습니다.

'CANCELED'
사용자 또는 API를 통해 인쇄 작업이 취소되었습니다.

'PRINTED'
인쇄 작업이 오류 없이 인쇄되었습니다.

Printer

속성

  • 설명

    문자열

    프린터에 대한 인간이 읽을 수 있는 설명입니다.

  • id

    문자열

    프린터의 식별자입니다. 기기의 프린터 간에 고유합니다.

  • isDefault

    부울

    프린터가 DefaultPrinterSelection 규칙에 적합한지 여부를 나타내는 플래그입니다. 여러 프린터가 표시될 수 있습니다.

  • 이름

    문자열

    프린터 이름입니다.

  • recentlyUsedRank

    number(숫자) 선택사항

    Chrome에서 인쇄하는 데 프린터를 사용한 시점을 나타내는 값입니다. 값이 낮을수록 프린터를 최근에 사용한 것입니다. 최솟값은 0입니다. 값이 누락되면 프린터가 최근에 사용되지 않았음을 나타냅니다. 이 값은 프린터 간에 고유한 것으로 보장됩니다.

  • source

    프린터의 소스 (사용자 또는 정책 구성)입니다.

  • uri

    문자열

    프린터 URI입니다. 확장 프로그램에서 이를 사용하여 사용자의 프린터를 선택할 수 있습니다.

PrinterSource

프린터의 소스입니다.

열거형

'USER'
사용자가 프린터를 추가했습니다.

'POLICY'
정책을 통해 프린터가 추가되었습니다.

PrinterStatus

프린터의 상태입니다.

열거형

"DOOR_OPEN"
프린터의 도어가 열려 있습니다. 프린터에서 인쇄 작업을 계속 수락합니다.

'TRAY_MISSING'
프린터의 트레이가 없습니다. 프린터에서 인쇄 작업을 계속 수락합니다.

'OUT_OF_INK'
프린터에 잉크가 없습니다. 프린터에서 인쇄 작업을 계속 수락합니다.

'OUT_OF_PAPER'
프린터에 용지가 없습니다. 프린터에서 인쇄 작업을 계속 수락합니다.

'OUTPUT_FULL'
프린터의 출력 영역 (예: 트레이)이 가득 찼습니다. 프린터에서 인쇄 작업을 계속 수락합니다.

'PAPER_JAM'
프린터에 용지 걸림이 있습니다. 프린터에서 인쇄 작업을 계속 수락합니다.

'GENERIC_ISSUE'
일반적인 문제. 프린터에서 인쇄 작업을 계속 수락합니다.

'STOPPED'
프린터가 중지되어 인쇄하지 않지만 인쇄 작업은 계속 허용합니다.

'연결할 수 없음'
프린터에 연결할 수 없으며 인쇄 작업을 수락하지 않습니다.

'EXPIRED_CERTIFICATE'
SSL 인증서가 만료되었습니다. 프린터가 작업을 수락하지만 실패합니다.

'AVAILABLE'
프린터를 사용할 수 있습니다.

SubmitJobRequest

속성

  • ���업

    제출할 인쇄 작업입니다. 지원되는 콘텐츠 유형은 'application/pdf' 및 'image/png'입니다. 클라우드 작업 티켓에는 FitToPageTicketItem, PageRangeTicketItem, ReverseOrderTicketItem 필드가 포함되어서는 안 됩니다. 기본 인쇄와 관련이 없기 때문입니다. VendorTicketItem은 선택사항입니다. 다른 모든 필드는 있어야 합니다.

SubmitJobResponse

속성

  • jobId

    문자열 선택사항

    생성된 인쇄 작업의 ID입니다. 기기의 모든 인쇄 작업 중에서 고유한 식별자입니다. 상태가 OK가 아니면 jobId가 null입니다.

  • 요청 상태입니다.

SubmitJobStatus

submitJob 요청의 상태입니다.

열거형

'OK'
전송된 인쇄 작업 요청이 수락되었습니다.

'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,
)
: Promise<void>

이전에 제출된 작업을 취소합니다.

매개변수

  • jobId

    문자열

    취소할 인쇄 작업의 ID입니다. SubmitJobResponse에서 수신한 ID와 동일해야 합니다.

반환 값

  • Promise<void>

    Chrome 100 이상

getJobStatus()

Chrome 135 이상
chrome.printing.getJobStatus(
  jobId: string,
)
: Promise<JobStatus>

인쇄 작업의 상태를 반환합니다. 지정된 jobId가 있는 인쇄 작업이 없으면 이 호출은 런타임 오류와 함께 실패합니다. jobId: 상태를 반환할 인쇄 작업의 ID입니다. SubmitJobResponse에서 수신한 ID와 동일해야 합니다.

매개변수

  • jobId

    문자열

반환 값

getPrinterInfo()

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

CDD 형식으로 프린터의 상태와 기능을 반환합니다. 지정된 ID의 프린터가 설치되어 있지 않으면 이 호출은 런타임 오류와 함께 실패합니다.

매개변수

  • printerId

    문자열

반환 값

getPrinters()

chrome.printing.getPrinters(): Promise<Printer[]>

기기에서 사용 가능한 프린터 목록을 반환합니다. 여기에는 수동으로 추가된 프린터, 엔터프라이즈 프린터, 검색된 프린터가 포함됩니다.

반환 값

  • Promise<Printer[]>

    Chrome 100 이상

submitJob()

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

인쇄 작업을 제출합니다. 확장 프로그램이 PrintingAPIExtensionsAllowlist 정책에 나열되지 않으면 사용자에게 인쇄 작업을 수락하라는 메시지가 표시됩니다. Chrome 120 이전에는 이 함수가 프로미스를 반환하지 않았습니다.

매개변수

반환 값

이벤트

onJobStatusChanged

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

작업 상태가 변경될 때 발생하는 이벤트입니다. 이 이벤트는 이 확장 프로그램에서 생성된 작업에 대해서만 발생합니다.

매개변수

  • callback

    함수

    callback 매개변수는 다음과 같습니다.

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