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()

이 예시에서는 onJobStatusChanged 핸들러를 사용하여 'cancel'을 숨깁니다. 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()를 호출하여 가져오는 프린터 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

인쇄 작업의 상태입니다.

열거형

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

'IN_PROGRESS'
인쇄 작업이 전송되어 인쇄됩니다.

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

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

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

Printer

속성

  • 설명

    문자열

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

  • id

    문자열

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

  • isDefault

    부울

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

  • 이름

    문자열

    프린터의 이름입니다.

  • recentlyUsedRank

    번호 선택사항

    Chrome에서 인쇄하는 데 프린터가 얼마나 최근에 사용되었는지를 보여주는 값입니다. 값이 낮을수록 프린터가 더 최근에 사용된 것입니다. 최솟값은 0입니다. 값이 없으면 최근에 프린터를 사용하지 않았음을 나타냅니다. 이 값은 프린터 간에 고유합니다.

  • source

    PrinterSource

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

  • uri

    문자열

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

PrinterSource

프린터의 소스입니다.

열거형

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

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

PrinterStatus

프린터의 상태입니다.

열거형

'DOOR_OPEN'
프린터 덮개가 열려 있습니다. 프린터가 여전히 인쇄 작업을 수락합니다.

"TRAY_MISSING"
프린터의 트레이가 없습니다. 프린터가 여전히 인쇄 작업을 수락합니다.

'OUT_OF_INK'
프린터에 잉크가 없습니다. 프린터가 여전히 인쇄 작업을 수락합니다.

"OUT_OF_PAPER"
프린터에 용지가 없습니다. 프린터가 여전히 인쇄 작업을 수락합니다.

"OUTPUT_FULL"
프린터의 출력 영역 (예: 트레이)이 가득 찼습니다. 프린터가 여전히 인쇄 작업을 수락합니다.

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

"GENERIC_ISSUE"
일반적인 문제입니다. 프린터가 여전히 인쇄 작업을 수락합니다.

'중지됨'
프린터가 중지되어 인쇄하지 않지만 인쇄 작업은 계속 수락합니다.

"UNREACHABLE"
프린터에 연결할 수 없으며 인쇄 작업을 허용하지 않습니다.

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

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

SubmitJobRequest

속성

  • job

    PrintJob

    제출할 인쇄 작업입니다. 지원되는 유일한 콘텐츠 유형은 'application/pdf'이며 Cloud Job Ticket에는 FitToPageTicketItem, PageRangeTicketItem, ReverseOrderTicketItem, VendorTicketItem 필드가 포함되어서는 안 됩니다. 이러한 필드는 네이티브 인쇄와 관련이 없기 때문입니다. 다른 모든 필드가 있어야 합니다.

SubmitJobResponse

속성

  • jobId

    문자열 선택사항

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

  • 요청 상태입니다.

SubmitJobStatus

submitJob 요청의 상태입니다.

열거형

"확인"
전송한 인쇄 작업 요청이 수락되었습니다.

"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,
)

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

매개변수

  • jobId

    문자열

    취소할 인쇄 작업의 ID입니다. SubmitJobResponse에 수신된 것과 동일한 ID여야 합니다.

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • Promise<void>

    Chrome 100 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getPrinterInfo()

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

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

매개변수

반환 값

  • Promise&lt;GetPrinterInfoResponse&gt;

    Chrome 100 이상

    Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

getPrinters()

Promise 
chrome.printing.getPrinters(
  callback?: function,
)

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

매개변수

  • 콜백

    함수 선택사항

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

    (printers: Printer[]) => void

반환 값

  • Promise<Printer[]>

    Chrome 100 이상

    Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

submitJob()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
)

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

매개변수

반환 값

  • Chrome 100 이상

    Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.

이벤트

onJobStatusChanged

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

작업 상태가 변경될 때 실행되는 이벤트입니다. 이는 이 확장 프로그램으로 만든 작업에 대해서만 실행됩니다.

매개변수

  • 콜백

    함수

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

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