chrome.printing

설명

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

권한

printing

가용성

Chrome 81 이상 ChromeOS만 해당

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

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

예

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

cancelJob()

이 예에서는 jobStatus이 PENDING도 IN_PROGRESS도 아닌 경우 onJobStatusChanged 핸들러를 사용하여 '취소' 버튼을 숨깁니다. 일부 네트워크에서 또는 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()를 호출하여 가져오는 프린터 ID가 필요하므로 이러한 함수에는 단일 예가 사용됩니다. 이 예에서는 기본 프린터의 이름과 설명을 콘솔에 로깅합니다. 이 예는 인쇄 예의 간소화된 버전입니다.

​​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번째 줄). 프린터 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'     });   } };  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()를 호출하고 "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 형식의 프린터 기능 속성이 누락되었을 수 있습니다.

  • 상태

    PrinterStatus

    프린터의 상태입니다.

JobStatus

인쇄 작업의 상태입니다.

열거형

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

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

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

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

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

Printer

속성

  • 설명

    문자열

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

  • id

    문자열

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

  • isDefault

    부울

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

  • 이름

    문자열

    프린터 이름입니다.

  • recentlyUsedRank

    번호 선택사항

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

  • 출처

    PrinterSource

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

  • 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

속성

  • 작업

    PrintJob

    제출할 인쇄 작업입니다. 지원되는 콘텐츠 유형은 '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