chrome.printing

refresh date: 2026-09-25 robots: noindex

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

شرح

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

اجازه‌ها

printing

دردسترس بودن

Chrome نسخه ۸۱ به بالا فقط ChromeOS

مانیفست

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

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

مثال‌ها

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

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

​​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 (خط ۸) پیوست شده است و داده‌های چاپ به یک blob (خط ۱۰) تبدیل شده است. دریافت شناسه چاپگر (خط ۱) در نمونه پیچیده‌تر از چیزی است که در اینجا نشان داده شده است.

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. ممکن است دارایی وجود نداشته باشد.

• وضعیت

  PrinterStatus

  وضعیت چاپگر.

JobStatus

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

شمارشی

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

«IN_PROGRESS»
کار چاپ برای چاپ ارسال شده است.

«ناموفق»
کار چاپ به‌دلیل خطایی قطع شد.

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

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

Printer

مشخصات

• description

  رشته

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

• id

  رشته

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

• isDefault

  بولی

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

• نام

  رشته

  نام چاپگر.

• recentlyUsedRank

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

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

• منبع

  PrinterSource

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

• uri

  رشته

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

PrinterSource

منبع چاپگر.

شمارشی

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

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

PrinterStatus

وضعیت چاپگر.

شمارشی

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

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

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

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

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

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

«GENERIC_ISSUE»
مشکل عمومی. چاپگر همچنان کارهای چاپ را می‌پذیرد.

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

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

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

«دردسترس»
چاپگر دردسترس است.

SubmitJobRequest

مشخصات

• شغل

  PrintJob

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

SubmitJobResponse

مشخصات

• jobId

  رشته اختیاری

  شناسه کار چاپ ایجادشده. این شناسه در بین همه کارهای چاپ در دستگاه یکتا است. اگر وضعیت OK نباشد، jobId تهی خواهد بود.

• وضعیت

  SubmitJobStatus

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

SubmitJobStatus

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

شمارشی

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

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

مشخصات

MAX_GET_PRINTER_INFO_CALLS_PER_MINUTE

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

مقدار

20

MAX_SUBMIT_JOB_CALLS_PER_MINUTE

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

مقدار

‫۴۰

روش‌ها

cancelJob()

قول

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

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

پارامترها

• jobId

  رشته

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

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به‌صورت زیر است:

  () => void

بازگشتی‌ها

• Promise<void>

  Chrome نسخه ۱۰۰ به بالا

  ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getJobStatus()

Promise Chrome 135+

chrome.printing.getJobStatus(
  jobId: string,
  callback?: function,
): Promise<JobStatus>

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

پارامترها

• jobId

  رشته

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به‌صورت زیر است:

  (status: JobStatus) => void

  • وضعیت

    JobStatus

بازگشتی‌ها

• Promise<JobStatus>

  ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getPrinterInfo()

قول

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

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

پارامترها

• printerId

  رشته

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به‌صورت زیر است:

  (response: GetPrinterInfoResponse) => void

  • پاسخ

    GetPrinterInfoResponse

بازگشتی‌ها

• Promise<GetPrinterInfoResponse>

  Chrome نسخه ۱۰۰ به بالا

  ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

getPrinters()

قول

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

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

پارامترها

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به‌صورت زیر است:

  (printers: Printer[]) => void

  • چاپگرها

    چاپگر[]

بازگشتی‌ها

• Promise<Printer[]>

  Chrome نسخه ۱۰۰ به بالا

  ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

submitJob()

قول

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

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

پارامترها

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

  SubmitJobRequest

• تماس برگشتی

  تابع اختیاری

  پارامتر callback به‌صورت زیر است:

  (response: SubmitJobResponse) => void

  • پاسخ

    SubmitJobResponse

بازگشتی‌ها

• Promise<SubmitJobResponse>

  Chrome نسخه ۱۰۰ به بالا

  ‫Promises فقط برای «مانیفست نسخه ۳» و نسخه‌های جدیدتر پشتیبانی می‌شود، پلاتفرم‌های دیگر باید از callbacks استفاده کنند.

رویدادها

onJobStatusChanged

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

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

پارامترها

• تماس برگشتی

  عملکرد

  پارامتر callback به‌صورت زیر است:

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

  • jobId

    رشته

  • وضعیت

    JobStatus