설명
chrome.printing API를 사용하여 Chromebook에 설치된 프린터로 인쇄 작업을 전송합니다.
권한
printing가용성
모든 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()
프린터 정보를 가져오려면 프린터 ID가 필요하며 이 ID는 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행). 프린터 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 형식) 속성이 누락되었을 수 있습니다.
-
프린터의 상태입니다.
JobStatus
인쇄 작업의 상태입니다.
열거형
'대기중'
인쇄 작업이 Chrome 측에서 수신되었지만 아직 처리되지 않았습니다.
"IN_PROGRESS"
인쇄 작업이 인쇄를 위해 전송됩니다.
'FAILED'
오류로 인해 인쇄 작업이 중단되었습니다.
'취소됨'
인쇄 작업이 사용자 또는 API를 통해 취소되었습니다.
"PRINTED"
인쇄 작업이 오류 없이 인쇄되었습니다.
Printer
속성
-
설명
문자열
사람이 읽을 수 있는 프린터 설명입니다.
-
id
문자열
프린터의 식별자입니다. 장치의 프린터 간에 고유합니다.
-
isDefault
부울
프린터가 DefaultPrinterSelection 규칙에 부합하는지 표시하는 플래그입니다. 여러 프린터가 신고될 수 있습니다.
-
이름
문자열
프린터의 이름입니다.
-
recentlyUsedRank
숫자 선택사항
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"
일반적인 문제입니다. 프린터에서 계속 인쇄 작업을 수락합니다.
"중지됨"
프린터가 중지되어 인쇄되지 않지만 인쇄 작업은 계속 수행할 수 있습니다.
"UNREACHABLE"
프린터에 연결할 수 없으며 인쇄 작업을 허용하지 않습니다.
"EXPIRED_CERTIFICATE"
SSL 인증서가 만료되었습니다. 프린터에서 작업을 수락하지만 실패합니다.
"AVAILABLE"
프린터를 사용할 수 있습니다.
SubmitJobRequest
속성
-
job
제출할 인쇄 작업입니다. 지원되는 유일한 콘텐츠 유형은 'application/pdf'이며,
FitToPageTicketItem,PageRangeTicketItem,ReverseOrderTicketItem,VendorTicketItem필드는 기본 인쇄와 관련이 없으므로 Cloud Job Ticket에 포함하면 안 됩니다. 다른 모든 필드가 있어야 합니다.
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()
chrome.printing.cancelJob(
jobId: string,
callback?: function,
)
이전에 제출된 작업을 취소합니다.
매개변수
-
jobId
문자열
취소할 인쇄 작업의 ID입니다.
SubmitJobResponse에 수신된 것과 동일한 ID여야 합니다. -
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.() => void
반환 값
-
프로미스<void>
Chrome 100 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
getPrinterInfo()
chrome.printing.getPrinterInfo(
printerId: string,
callback?: function,
)
프린터의 상태 및 기능을 CDD 형식으로 반환합니다. 지정된 ID의 프린터가 설치되어 있지 않으면 런타임 오류가 발생하여 이 호출이 실패합니다.
매개변수
-
printerId
문자열
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(response: GetPrinterInfoResponse) => void
반환 값
-
Promise<GetPrinterInfoResponse>
Chrome 100 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
getPrinters()
chrome.printing.getPrinters(
callback?: function,
)
기기에서 사용 가능한 프린터 목록을 반환합니다. 여기에는 수동으로 추가한 프린터, 엔터프라이즈 프린터 및 검색된 프린터가 포함됩니다.
반환 값
-
프로미스<프린터[]>
Chrome 100 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.
submitJob()
chrome.printing.submitJob(
request: SubmitJobRequest,
callback?: function,
)
인쇄 작업을 제출합니다. 확장 프로그램이 PrintingAPIExtensionsAllowlist 정책에 포함되어 있지 않으면 사용자에게 인쇄 작업을 수락하라는 메시지가 표시됩니다.
Chrome 120 이전에는 이 함수가 프로미스를 반환하지 않았습니다.
매개변수
-
콜백
함수 선택사항
callback매개변수는 다음과 같습니다.(response: SubmitJobResponse) => void
반환 값
-
Promise<SubmitJobResponse>
Chrome 100 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.