chrome.printing

توضیحات

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

مجوزها

printing

در دسترس بودن

فقط کروم او اس نسخه ۸۱ به بالا

مانیفست

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

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

مثال‌ها

مثال‌های زیر نحوه‌ی استفاده از هر یک از متدهای موجود در فضای نام printing را نشان می‌دهند. این کد از api-samples/printing در مخزن GitHub مربوط به extensions-samples کپی شده یا بر اساس آن است.

لغو کار ()

این مثال از هندلر onJobStatusChanged برای پنهان کردن دکمه 'cancel' استفاده می‌کند، زمانی که jobStatus نه در PENDING است و نه IN_PROGRESS . توجه داشته باشید که در برخی شبکه‌ها یا وقتی یک Chromebook مستقیماً به چاپگر متصل است، این حالت‌ها ممکن است خیلی سریع عبور کنند تا دکمه cancel به اندازه کافی قابل مشاهده باشد که فراخوانی شود. این یک مثال چاپ بسیار ساده شده است.

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() به سه چیز نیاز دارد.

  • یک ساختار ticket که مشخص می‌کند کدام قابلیت‌های چاپگر باید استفاده شوند. اگر کاربر نیاز به انتخاب از قابلیت‌های موجود داشته باشد، می‌توانید آن‌ها را برای یک چاپگر خاص با استفاده getPrinterInfo() بازیابی کنید.
  • یک ساختار SubmitJobRequest که چاپگر مورد استفاده و فایل یا تاریخ چاپ را مشخص می‌کند. این ساختار حاوی ارجاعی به ساختار ticket است.
  • تکه‌ای از فایل یا داده برای چاپ.

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

این یک نسخه ساده شده از مثال چاپ است. توجه داشته باشید که ticket به ساختار SubmitJobRequest (خط 8) پیوست شده است و داده ای که باید چاپ شود به یک blob تبدیل می شود (خط 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"
    }
  },
  ...
]

مقادیر موجود در کلید 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

وضعیت کار چاپ.

شمارشی

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

"در حال پیشرفت"
کار چاپ برای چاپ ارسال می‌شود.

«شکست خورد»
به دلیل برخی خطاها، کار چاپ متوقف شد.

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

«چاپ‌شده»
کار چاپ بدون هیچ خطایی چاپ شد.

Printer

خواص

  • توضیحات

    رشته

    توضیحات قابل خواندن توسط انسان در مورد چاپگر.

  • شناسه

    رشته

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

  • isDefault

    بولی

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

  • نام

    رشته

    نام چاپخانه.

  • اخیراً استفاده شده رتبه

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

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

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

  • یوری

    رشته

    آدرس اینترنتی چاپگر. افزونه‌ها می‌توانند از این آدرس برای انتخاب چاپگر برای کاربر استفاده کنند.

PrinterSource

منبع چاپگر.

شمارشی

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

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

PrinterStatus

وضعیت چاپگر.

شمارشی

«در_باز»
درب چاپگر باز است. چاپگر هنوز کارهای چاپی را می‌پذیرد.

«سینی_گمشده»
سینی چاپگر گم شده است. چاپگر هنوز کارهای چاپی را می‌پذیرد.

«خالی از جوهر»
جوهر چاپگر تمام شده است. چاپگر هنوز کارهای چاپی را می‌پذیرد.

«خارج از کاغذ»
کاغذ چاپگر تمام شده است. چاپگر هنوز کارهای چاپی را می‌پذیرد.

"خروجی_کامل"
قسمت خروجی چاپگر (مثلاً سینی) پر است. چاپگر هنوز کارهای چاپی را می‌پذیرد.

«کاغذ_گیر کرده»
چاپگر کاغذ گیر کرده است. چاپگر هنوز کارهای چاپی را می‌پذیرد.

"موضوع_عمومی"
یک مشکل عمومی. چاپگر هنوز کارهای چاپی را می‌پذیرد.

«متوقف شد»
چاپگر متوقف شده و چاپ نمی‌کند اما همچنان کارهای چاپی را می‌پذیرد.

«دست‌نیافتنی»
چاپگر در دسترس نیست و کارهای چاپی را قبول نمی‌کند.

«گواهینامه منقضی شده»
گواهی SSL منقضی شده است. چاپگر کارها را می‌پذیرد اما با خطا مواجه می‌شوند.

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

SubmitJobRequest

خواص

  • کار چاپی که باید ارسال شود. انواع محتوای پشتیبانی شده عبارتند از "application/pdf" و "image/png". تیکت کار ابری نباید شامل فیلدهای FitToPageTicketItem ، PageRangeTicketItem و ReverseOrderTicketItem باشد زیرا برای چاپ بومی بی‌ربط هستند. VendorTicketItem اختیاری است. همه فیلدهای دیگر باید وجود داشته باشند.

SubmitJobResponse

خواص

  • شناسه شغل

    رشته اختیاری

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

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

SubmitJobStatus

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

شمارشی

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

«کاربر رد شد»
درخواست کار چاپ ارسال شده توسط کاربر رد می‌شود.

خواص

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

حداکثر تعداد دفعاتی که getPrinterInfo می‌تواند در هر دقیقه فراخوانی شود.

ارزش

۲۰

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

حداکثر تعداد دفعاتی که submitJob می‌تواند در هر دقیقه فراخوانی شود.

ارزش

۴۰

روش‌ها

cancelJob()

وعده
chrome.printing.cancelJob(
  jobId: string,
  callback?: function,
): Promise<void>

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

پارامترها

  • شناسه شغل

    رشته

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

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    () => void

بازگشت‌ها

  • قول<void>

    کروم ۱۰۰+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getJobStatus()

قول کروم ۱۳۵+
chrome.printing.getJobStatus(
  jobId: string,
  callback?: function,
): Promise<JobStatus>

وضعیت کار چاپ را برمی‌گرداند. اگر کار چاپ با jobId داده شده وجود نداشته باشد، این فراخوانی با خطای زمان اجرا شکست می‌خورد. jobId : شناسه کار چاپ برای بازگرداندن وضعیت. این باید همان شناسه‌ای باشد که در SubmitJobResponse دریافت شده است.

پارامترها

  • شناسه شغل

    رشته

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (status: JobStatus) => void

بازگشت‌ها

  • Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getPrinterInfo()

وعده
chrome.printing.getPrinterInfo(
  printerId: string,
  callback?: function,
): Promise<GetPrinterInfoResponse>

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

پارامترها

بازگشت‌ها

  • کروم ۱۰۰+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

getPrinters()

وعده
chrome.printing.getPrinters(
  callback?: function,
): Promise<Printer[]>

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

پارامترها

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (printers: Printer[]) => void

بازگشت‌ها

  • قول< چاپگر []>

    کروم ۱۰۰+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

submitJob()

وعده
chrome.printing.submitJob(
  request: SubmitJobRequest,
  callback?: function,
): Promise<SubmitJobResponse>

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

پارامترها

بازگشت‌ها

  • کروم ۱۰۰+

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

رویدادها

onJobStatusChanged

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

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

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

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