chrome.printing

중요: 이 API는 ChromeOS에서만 작동합니다.

설명

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

권한

printing

가용성

Chrome 81 이상 ChromeOS만 해당

매니페스트

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

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

예

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

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()를 호출하여 가져오는 인쇄기 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

프린터의 소스입니다.

열거형

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

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

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

  요청 상태입니다.

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

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

매개변수

• jobId

  문자열

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

• 콜백

  함수 선택사항

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

  () => void

반환 값

• Promise<void>

  Chrome 100 이상

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

getJobStatus()

Promise 대기 중

chrome.printing.getJobStatus(
  jobId: string,
  callback?: function,
)

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

매개변수

• jobId

  문자열

• 콜백

  함수 선택사항

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

  (status: JobStatus) => void

  • 상태

    JobStatus

반환 값

• Promise<JobStatus>

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

getPrinterInfo()

Promise

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

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

매개변수

• printerId

  문자열

• 콜백

  함수 선택사항

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

  (response: GetPrinterInfoResponse) => void

  • 응답

    GetPrinterInfoResponse

반환 값

• Promise<GetPrinterInfoResponse>

  Chrome 100 이상

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

getPrinters()

Promise

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

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

매개변수

• 콜백

  함수 선택사항

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

  (printers: Printer[]) => void

  • 프린터

    Printer[]

반환 값

• Promise<Printer[]>

  Chrome 100 이상

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

submitJob()

Promise

chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
)

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

매개변수

• 요청

  SubmitJobRequest

• 콜백

  함수 선택사항

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

  (response: SubmitJobResponse) => void

  • 응답

    SubmitJobResponse

반환 값

• Promise<SubmitJobResponse>

  Chrome 100 이상

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

이벤트

onJobStatusChanged

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

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

매개변수

• 콜백

  함수

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

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

  • jobId

    문자열

  • 상태

    JobStatus