chrome.printing

مهم: این API فقط روی ChromeOS کار می‌کند.

توضیحات

از chrome.printing API برای ارسال کارهای چاپی به چاپگرهای نصب شده در Chromebook استفاده کنید.

مجوزها

printing

در دسترس بودن

فقط Chrome 81+ ChromeOS

همه روش‌ها و رویدادهای chrome.printing از شما می‌خواهند مجوز "printing" در مانیفست افزونه اعلام کنید. به عنوان مثال:

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

نمونه ها

مثال‌های زیر استفاده از هر یک از روش‌ها را در فضای نام چاپ نشان می‌دهند. این کد از یا بر اساس api-samples/printing در Extensions-Samps Repo Github کپی شده است.

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

یک مثال واحد برای این توابع استفاده می شود زیرا دریافت اطلاعات چاپگر به شناسه چاپگر نیاز دارد که با فراخوانی 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 است.
• لکه ای از فایل یا داده برای چاپ.

فراخوانی submitJob() یک کادر محاوره ای را راه اندازی می کند که از کاربر می خواهد چاپ را تأیید کند. از PrintingAPIExtensionsAllowlist برای دور زدن تایید استفاده کنید.

این یک نسخه ساده شده از نمونه چاپ است. توجه داشته باشید که ticket به ساختار SubmitJobRequest متصل شده است (خط 8) و داده های چاپ شده به یک لکه (خط 10) تبدیل می شود. دریافت شناسه چاپگر (خط 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() را فراخوانی کنید و به دنبال "display_name" از "finishings/11" بگردید.

"vendor_capability": [
  {
    "display_name": "finishings/11",
    "id": "finishings/11",
    "type": "TYPED_VALUE",
    "typed_value_cap": {
      "value_type": "BOOLEAN"
    }
  },
  ...
]

توجه: با شروع Chrome 124، vendor_ticket_item به همه موارد از vendor_capabilities چاپگر اجازه می دهد. به عنوان مثال، هر مقدار برگردانده شده توسط getPrinterInfo() معتبر است. قبل از این، فقط کلید finishings پشتیبانی می شد.

مقادیر موجود در کلید media_size بلیط برای هر چاپگر خاص است. برای انتخاب اندازه مناسب با getPrinterInfo() تماس بگیرید. GetPrinterResponse برگشتی حاوی آرایه‌ای از اندازه‌های رسانه پشتیبانی شده در "media_size"."option" . گزینه ای را انتخاب کنید که مقدار "is_continuous_feed" آن درست باشد. از مقادیر ارتفاع و عرض آن برای بلیط استفاده کنید.

"media_size": {
  "option": [
  {
    "custom_display_name": "",
    "is_continuous_feed": true,
    "max_height_microns": 2000000,
    "min_height_microns": 25400,
    "width_microns": 50800
  },
  ...
  ]
}

انواع

GetPrinterInfoResponse

خواص

• قابلیت ها

  شی اختیاری

  قابلیت های چاپگر در فرمت CDD . ممکن است ملک گم شده باشد.

• وضعیت

  وضعیت چاپگر

  وضعیت چاپگر

JobStatus

وضعیت کار چاپ

Enum

"در انتظار"
کار چاپ در سمت کروم دریافت شد اما هنوز پردازش نشده است.

"IN_PROGRESS"
کار چاپ برای چاپ ارسال می شود.

"شکست خورده"
کار چاپ به دلیل برخی خطا قطع شد.

"لغو"
کار چاپ توسط کاربر یا از طریق API لغو شد.

"چاپ شده"
کار چاپ بدون هیچ خطایی چاپ شد.

Printer

خواص

• توضیحات

  رشته

  توصیف انسان قابل خواندن چاپگر.

• شناسه

  رشته

  شناسه چاپگر؛ تضمین شده است که در بین چاپگرهای دستگاه منحصر به فرد است.

• پیش فرض است

  بولی

  پرچمی که نشان می دهد آیا چاپگر با قوانین DefaultPrinterSelection مطابقت دارد یا خیر. توجه داشته باشید که چندین چاپگر ممکن است علامت گذاری شوند.

• نام

  رشته

  نام چاپگر.

• اخیراًUsedRank

  شماره اختیاری

  مقداری که نشان می دهد چاپگر چقدر اخیر برای چاپ از Chrome استفاده شده است. هرچه این مقدار کمتر باشد چاپگر جدیدتر استفاده شده است. حداقل مقدار 0 است. مقدار از دست رفته نشان می دهد که چاپگر اخیراً استفاده نشده است. این مقدار تضمین شده است که در بین چاپگرها منحصر به فرد است.

• منبع

  منبع چاپگر

  منبع چاپگر (کاربر یا خط مشی پیکربندی شده است).

• اوری

  رشته

  URI چاپگر. این می تواند توسط برنامه های افزودنی برای انتخاب چاپگر برای کاربر استفاده شود.

PrinterSource

منبع چاپگر

Enum

"کاربر"
چاپگر توسط کاربر اضافه شد.

"سیاست"
چاپگر از طریق خط مشی اضافه شد.

PrinterStatus

وضعیت چاپگر

Enum

"DOOR_OPEN"
درب پرینتر باز است. چاپگر همچنان کارهای چاپ را می پذیرد.

"TRAY_MISSING"
سینی چاپگر وجود ندارد. چاپگر همچنان کارهای چاپ را می پذیرد.

"OUT_OF_INK"
جوهر چاپگر تمام شده است. چاپگر همچنان کارهای چاپ را می پذیرد.

"OUT_OF_PAPER"
کاغذ چاپگر تمام شده است. چاپگر همچنان کارهای چاپ را می پذیرد.

"OUTPUT_FULL"
ناحیه خروجی چاپگر (به عنوان مثال سینی) پر است. چاپگر همچنان کارهای چاپ را می پذیرد.

"PAPER_JAM"
چاپگر دارای گیر کردن کاغذ است. چاپگر همچنان کارهای چاپ را می پذیرد.

"GENERIC_ISSUE"
برخی از مسائل عمومی چاپگر همچنان کارهای چاپ را می پذیرد.

"توقف شد"
چاپگر متوقف شده است و چاپ نمی شود اما همچنان کارهای چاپ را می پذیرد.

"دست نیافتنی"
چاپگر قابل دسترسی نیست و کارهای چاپی را نمی پذیرد.

"EXPIRED_CERTIFICATE"
گواهی SSL منقضی شده است. چاپگر کارها را می پذیرد اما آنها شکست می خورند.

"موجود"
چاپگر موجود است.

SubmitJobRequest

خواص

• شغل

  PrintJob

  کار چاپی که باید ارسال شود. تنها نوع محتوای پشتیبانی شده «application/pdf» است و Cloud Job Ticket نباید شامل فیلدهای FitToPageTicketItem ، PageRangeTicketItem ، ReverseOrderTicketItem و VendorTicketItem باشد زیرا برای چاپ بومی نامربوط هستند. تمام فیلدهای دیگر باید وجود داشته باشد.

SubmitJobResponse

خواص

• job ID

  رشته اختیاری

  شناسه کار چاپ ایجاد شده این یک شناسه منحصر به فرد در بین تمام کارهای چاپی روی دستگاه است. اگر وضعیت خوب نباشد jobId null خواهد بود.

• وضعیت

  ارسال وضعیت شغلی

  وضعیت درخواست

SubmitJobStatus

وضعیت submitJob .

Enum

"باشه"
درخواست کار چاپ ارسالی پذیرفته می شود.

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

کار ارسال شده قبلی را لغو می کند.

پارامترها

• job ID

  رشته

  شناسه کار چاپ برای لغو. این باید همان شناسه دریافت شده در SubmitJobResponse باشد.

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  () => void

برمی گرداند

• قول<باطل>

  Chrome 100+

  Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getPrinterInfo()

قول بده

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

وضعیت و قابلیت های چاپگر را در قالب CDD برمی گرداند. اگر چاپگری با شناسه داده شده نصب نشود، این تماس با خطای زمان اجرا ناموفق خواهد بود.

پارامترها

• شناسه چاپگر

  رشته

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (response: GetPrinterInfoResponse) => void

  • پاسخ

    GetPrinterInfoResponse

برمی گرداند

• Promise< GetPrinterInfoResponse >

  Chrome 100+

  Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

getPrinters()

قول بده

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

لیست چاپگرهای موجود در دستگاه را برمی گرداند. این شامل چاپگرهای دستی، سازمانی و کشف شده می‌شود.

پارامترها

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (printers: Printer[]) => void

  • چاپگرها

    چاپگر []

برمی گرداند

• Promise< چاپگر []>

  Chrome 100+

  Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

submitJob()

قول بده

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

کار را برای چاپ ارسال می کند. اگر برنامه افزودنی در خط‌مشی PrintingAPIExtensionsAllowlist فهرست نشده باشد، از کاربر خواسته می‌شود کار چاپ را بپذیرد. قبل از کروم 120، این عملکرد قولی را برنمی‌گرداند.

پارامترها

• درخواست کنید

  ارسال درخواست کار

• پاسخ به تماس

  عملکرد اختیاری

  پارامتر callback به نظر می رسد:

  (response: SubmitJobResponse) => void

  • پاسخ

    ارسال کار پاسخ

برمی گرداند

• Promise< SubmitJobResponse >

  Chrome 100+

  Promises در Manifest V3 و نسخه های جدیدتر پشتیبانی می شود، اما callbacks برای سازگاری به عقب ارائه شده است. شما نمی توانید از هر دو در یک فراخوانی تابع استفاده کنید. وعده با همان نوعی که به callback ارسال می شود حل می شود.

رویدادها

onJobStatusChanged

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

زمانی که وضعیت کار تغییر می‌کند، رویداد اخراج می‌شود. این فقط برای مشاغل ایجاد شده توسط این افزونه اخراج می شود.

پارامترها

• پاسخ به تماس

  تابع

  پارامتر callback به نظر می رسد:

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

  • job ID

    رشته

  • وضعیت

    وضعیت شغلی