chrome.tabs

توضیحات

از API chrome.tabs برای تعامل با سیستم تب‌های مرورگر استفاده کنید. می‌توانید از این API برای ایجاد، تغییر و تنظیم مجدد تب‌ها در مرورگر استفاده کنید.

API تب‌ها نه تنها امکاناتی برای دستکاری و مدیریت تب‌ها ارائه می‌دهد، بلکه می‌تواند زبان تب را نیز تشخیص دهد، از آن اسکرین‌شات بگیرد و با اسکریپت‌های محتوای تب ارتباط برقرار کند .

مجوزها

اکثر ویژگی‌ها برای استفاده به هیچ مجوزی نیاز ندارند. برای مثال: ایجاد یک تب جدید، بارگذاری مجدد یک تب، رفتن به یک URL دیگر و غیره.

سه مجوز وجود دارد که توسعه‌دهندگان باید هنگام کار با Tabs API از آنها آگاه باشند.

مجوز «زبانه‌ها»

این مجوز به فضای نام chrome.tabs دسترسی نمی‌دهد. در عوض، به یک افزونه این امکان را می‌دهد که tabs.query() را در برابر چهار ویژگی حساس در نمونه‌های tabs.Tab فراخوانی کند: url ، pendingUrl ، title و favIconUrl .

{
  "name": "My extension",
  ...
  "permissions": [
    "tabs"
  ],
  ...
}
مجوزهای میزبان

مجوزهای میزبان به یک افزونه اجازه می‌دهند تا چهار ویژگی حساس tabs.Tab یک تب منطبق را بخواند و از آنها پرس‌وجو کند. آنها همچنین می‌توانند با استفاده از روش‌هایی مانند tabs.captureVisibleTab() ، scripting.executeScript() ، scripting.insertCSS() و scripting.removeCSS() مستقیماً با تب‌های منطبق تعامل داشته باشند.

{
  "name": "My extension",
  ...
  "host_permissions": [
    "http://*/*",
    "https://*/*"
  ],
  ...
}
مجوز "activeTab"

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

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

موارد استفاده

بخش‌های زیر برخی از موارد استفاده رایج را نشان می‌دهند.

باز کردن صفحه افزونه در تب جدید

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

پس‌زمینه.js:

chrome.runtime.onInstalled.addListener(({reason}) => {
  if (reason === 'install') {
    chrome.tabs.create({
      url: "onboarding.html"
    });
  }
});

دریافت برگه فعلی

این مثال نشان می‌دهد که چگونه سرویس ورکر یک افزونه می‌تواند تب فعال را از پنجره‌ی متمرکز فعلی (یا آخرین پنجره‌ی متمرکز، اگر هیچ پنجره‌ی کرومی متمرکز نباشد) بازیابی کند. این معمولاً می‌تواند به عنوان تب فعلی کاربر در نظر گرفته شود. 

  async function getCurrentTab() {
    let queryOptions = { active: true, lastFocusedWindow: true };
    // `tab` will either be a `tabs.Tab` instance or `undefined`.
    let [tab] = await chrome.tabs.query(queryOptions);
    return tab;
  }


  function getCurrentTab(callback) {
    let queryOptions = { active: true, lastFocusedWindow: true };
    chrome.tabs.query(queryOptions, ([tab]) => {
      if (chrome.runtime.lastError)
      console.error(chrome.runtime.lastError);
      // `tab` will either be a `tabs.Tab` instance or `undefined`.
      callback(tab);
    });
  }

بی‌صدا کردن تب مشخص‌شده

این مثال نشان می‌دهد که چگونه یک افزونه می‌تواند حالت بی‌صدا را برای یک تب مشخص تغییر دهد. 

  async function toggleMuteState(tabId) {
    const tab = await chrome.tabs.get(tabId);
    const muted = !tab.mutedInfo.muted;
    await chrome.tabs.update(tabId, {muted});
    console.log(`Tab ${tab.id} is ${muted ? "muted" : "unmuted"}`);
  }


  function toggleMuteState(tabId) {
    chrome.tabs.get(tabId, async (tab) => {
      let muted = !tab.mutedInfo.muted;
      await chrome.tabs.update(tabId, { muted });
      console.log(`Tab ${tab.id} is ${ muted ? "muted" : "unmuted" }`);
    });
  }

انتقال تب فعلی به اولین موقعیت هنگام کلیک

این مثال نحوه جابجایی یک تب را در حین انجام یا عدم انجام عمل کشیدن نشان می‌دهد. اگرچه این مثال از chrome.tabs.move استفاده می‌کند، می‌توانید از الگوی انتظار مشابه برای سایر فراخوانی‌هایی که تب‌ها را در حین انجام کشیدن تغییر می‌دهند، استفاده کنید. 

  chrome.tabs.onActivated.addListener(moveToFirstPosition);

  async function moveToFirstPosition(activeInfo) {
    try {
      await chrome.tabs.move(activeInfo.tabId, {index: 0});
      console.log("Success.");
    } catch (error) {
      if (error == "Error: Tabs cannot be edited right now (user may be dragging a tab).") {
        setTimeout(() => moveToFirstPosition(activeInfo), 50);
      } else {
        console.error(error);
      }
    }
  }


  chrome.tabs.onActivated.addListener(moveToFirstPositionMV2);

  function moveToFirstPositionMV2(activeInfo) {
    chrome.tabs.move(activeInfo.tabId, { index: 0 }, () => {
      if (chrome.runtime.lastError) {
        const error = chrome.runtime.lastError;
        if (error == "Error: Tabs cannot be edited right now (user may be dragging a tab).") {
          setTimeout(() => moveToFirstPositionMV2(activeInfo), 50);
        } else {
          console.error(error);
        }
      } else {
        console.log("Success.");
      }
    });
  }

ارسال پیام به اسکریپت محتوای تب انتخاب شده

این مثال نشان می‌دهد که چگونه سرویس ورکر یک افزونه می‌تواند با استفاده از tabs.sendMessage() با اسکریپت‌های محتوا در تب‌های خاص مرورگر ارتباط برقرار کند. 

function sendMessageToActiveTab(message) {
  const [tab] = await chrome.tabs.query({ active: true, lastFocusedWindow: true });
  const response = await chrome.tabs.sendMessage(tab.id, message);
  // TODO: Do something with the response.
}

نمونه‌های افزونه

برای مشاهده‌ی دموهای بیشتر از افزونه‌های Tabs API، هر یک از موارد زیر را بررسی کنید:

انواع

MutedInfo

کروم ۴۶+

وضعیت بی‌صدا بودن تب و دلیل آخرین تغییر وضعیت.

خواص

  • شناسه افزونه

    رشته اختیاری

    شناسه افزونه‌ای که وضعیت بی‌صدا را تغییر داده است. اگر آخرین تغییر وضعیت بی‌صدا به دلیل یک افزونه نبوده باشد، تنظیم نمی‌شود.

  • خاموش

    بولی

    اینکه آیا زبانه بی‌صدا شده است (از پخش صدا جلوگیری می‌شود). حتی اگر زبانه پخش نشده باشد یا در حال حاضر صدایی پخش نکند، ممکن است بی‌صدا باشد. معادل این است که آیا نشانگر صدای «بی‌صدا» نمایش داده می‌شود یا خیر.

  • دلیل

    دلیل اطلاعات خاموش اختیاری است

    دلیل بی‌صدا یا بی‌صدا کردن تب. اگر وضعیت بی‌صدا کردن تب هرگز تغییر نکرده باشد، تنظیم نمی‌شود.

MutedInfoReason

کروم ۴۶+

رویدادی که باعث تغییر وضعیت بی‌صدا شده است.

شمارشی

"کاربر"
یک عمل ورودی کاربر، حالت بی‌صدا را تنظیم کرد.

"گرفتن"
ضبط برگه آغاز شد و باعث تغییر وضعیت بی‌صدا شد.

"امتداد"
یک افزونه که با فیلد extensionId شناسایی می‌شود، حالت بی‌صدا را تنظیم می‌کند.

Tab

خواص

  • فعال

    بولی

    اینکه آیا تب در پنجره‌اش فعال است یا خیر. لزوماً به این معنی نیست که پنجره در حالت فوکوس قرار دارد.

  • قابل شنیدن

    بولی اختیاری

    کروم ۴۵+

    اینکه آیا زبانه در چند ثانیه گذشته صدایی تولید کرده است یا خیر (اما اگر بی‌صدا نیز باشد، ممکن است شنیده نشود). معادل این است که آیا نشانگر «صدای بلندگو» نمایش داده می‌شود یا خیر.

  • خودکارقابل حذف

    بولی

    کروم ۵۴+

    اینکه آیا مرورگر می‌تواند در صورت کمبود منابع، تب را به‌طور خودکار حذف کند یا خیر.

  • دور انداخته شده

    بولی

    کروم ۵۴+

    اینکه آیا تب حذف شده است یا خیر. تب حذف شده، تبی است که محتوای آن از حافظه حذف شده است، اما هنوز در نوار تب‌ها قابل مشاهده است. محتوای آن دفعه بعد که فعال شود، دوباره بارگذاری می‌شود.

  • آدرس آیکون مورد علاقه

    رشته اختیاری

    آدرس اینترنتی (URL) فاوآیکون تب. این ویژگی فقط در صورتی وجود دارد که افزونه مجوز "tabs" یا مجوزهای میزبان برای صفحه را داشته باشد. همچنین اگر تب در حال بارگیری باشد، می‌تواند یک رشته خالی باشد.

  • یخ زده

    بولی

    کروم ۱۳۲+

    اینکه آیا تب قفل شده است یا خیر. یک تب قفل شده نمی‌تواند وظایفی از جمله کنترل‌کننده‌های رویداد یا تایمرها را اجرا کند. در نوار تب‌ها قابل مشاهده است و محتوای آن در حافظه بارگذاری می‌شود. هنگام فعال شدن، قفل آن باز می‌شود.

  • شناسه گروه

    شماره

    کروم ۸۸+

    شناسه گروهی که تب به آن تعلق دارد.

  • ارتفاع

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

    ارتفاع تب بر حسب پیکسل.

  • برجسته شده

    بولی

    اینکه آیا برگه برجسته شده است یا خیر.

  • شناسه

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

    شناسه‌ی تب. شناسه‌های تب در یک جلسه‌ی مرورگر منحصر به فرد هستند. تحت برخی شرایط، ممکن است به یک تب شناسه‌ای اختصاص داده نشود؛ برای مثال، هنگام جستجوی تب‌های خارجی با استفاده از API sessions ، در این صورت ممکن است شناسه‌ی جلسه وجود داشته باشد. شناسه‌ی تب همچنین می‌تواند برای برنامه‌ها و پنجره‌های devtools روی chrome.tabs.TAB_ID_NONE تنظیم شود.

  • ناشناس

    بولی

    اینکه آیا برگه در پنجره ناشناس است یا خیر.

  • شاخص

    شماره

    اندیس مبتنی بر صفرِ تبِ درون پنجره‌اش.

  • آخرین دسترسی

    شماره

    کروم ۱۲۱+

    آخرین باری که تب در پنجره خود فعال شده است، به عنوان تعداد میلی ثانیه از زمان epoch.

  • اطلاعات بی‌صدا

    اطلاعات خاموش اختیاری

    کروم ۴۶+

    وضعیت بی‌صدا بودن تب و دلیل آخرین تغییر وضعیت.

  • تب آی دی بازکننده

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

    شناسه‌ی برگه‌ای که این برگه را باز کرده است، در صورت وجود. این ویژگی فقط در صورتی وجود دارد که برگه‌ی بازکننده هنوز وجود داشته باشد.

  • در انتظارآدرس

    رشته اختیاری

    کروم ۷۹+

    آدرس اینترنتی (URL) که تب قبل از ثبت نهایی به آن هدایت می‌شود. این ویژگی فقط در صورتی وجود دارد که افزونه مجوز "tabs" را داشته باشد یا مجوزهای میزبان برای صفحه داشته باشد و یک پیمایش در حال انتظار وجود داشته باشد.

  • سنجاق شده

    بولی

    اینکه آیا برگه پین ​​شده است یا خیر.

  • انتخاب شده

    بولی

    منسوخ شده

    لطفا از tabs.Tab.highlighted استفاده کنید.

    اینکه آیا برگه انتخاب شده است یا خیر.

  • شناسه جلسه

    رشته اختیاری

    شناسه‌ی جلسه (session ID) که برای شناسایی منحصر به فرد یک برگه (tab) که از API sessions API) به دست آمده است، استفاده می‌شود.

  • splitViewId

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

    در حال بررسی

    شناسه نمای تقسیم‌شده‌ای که تب به آن تعلق دارد.

  • وضعیت

    وضعیت برگه ( اختیاری)

    وضعیت بارگذاری برگه.

  • عنوان

    رشته اختیاری

    عنوان برگه. این ویژگی فقط در صورتی وجود دارد که افزونه مجوز "tabs" را داشته باشد یا مجوزهای میزبان برای صفحه داشته باشد.

  • آدرس اینترنتی

    رشته اختیاری

    آخرین URL ثبت‌شده‌ی فریم اصلی تب. این ویژگی فقط در صورتی وجود دارد که افزونه مجوز "tabs" یا مجوزهای میزبان برای صفحه را داشته باشد. اگر تب هنوز ثبت نشده باشد، می‌تواند یک رشته‌ی خالی باشد. همچنین به Tab.pendingUrl مراجعه کنید.

  • عرض

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

    عرض تب بر حسب پیکسل.

  • شناسه پنجره

    شماره

    شناسه‌ی پنجره‌ای که حاوی تب است.

TabStatus

کروم ۴۴+

وضعیت بارگذاری برگه.

شمارشی

"تخلیه شده"

"در حال بارگذاری"

"کامل"

WindowType

کروم ۴۴+

نوع پنجره.

شمارشی

"عادی"

"پاپ‌آپ"

"پانل"

"برنامه"

"ابزارهای توسعه"

ZoomSettings

تعریف می‌کند که تغییرات بزرگنمایی در یک تب چگونه و در چه محدوده‌ای مدیریت شوند.

خواص

  • پیش فرضفاکتور بزرگنمایی

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

    کروم ۴۳+

    برای برگرداندن سطح بزرگنمایی پیش‌فرض برای تب فعلی در فراخوانی‌های tabs.getZoomSettings استفاده می‌شود.

  • حالت

    حالت تنظیمات زوم اختیاری است

    نحوه مدیریت تغییرات بزرگنمایی را تعریف می‌کند، یعنی کدام موجودیت مسئول مقیاس‌بندی واقعی صفحه است؛ پیش‌فرض روی automatic است.

  • محدوده

    تنظیمات زوم و محدوده اختیاری

    مشخص می‌کند که آیا تغییرات بزرگنمایی برای مبدأ صفحه باقی می‌مانند یا فقط در این برگه اعمال می‌شوند؛ در حالت automatic ، پیش‌فرض به per-origin و در غیر این صورت per-tab .

ZoomSettingsMode

کروم ۴۴+

نحوه مدیریت تغییرات بزرگنمایی را تعریف می‌کند، یعنی کدام موجودیت مسئول مقیاس‌بندی واقعی صفحه است؛ پیش‌فرض روی automatic است.

شمارشی

"خودکار"
تغییرات بزرگنمایی به طور خودکار توسط مرورگر انجام می‌شود.

"دستی"
مدیریت خودکار تغییرات زوم را لغو می‌کند. رویداد onZoomChange همچنان ارسال خواهد شد و این وظیفه افزونه است که به این رویداد گوش دهد و صفحه را به صورت دستی مقیاس‌بندی کند. این حالت از زوم per-origin پشتیبانی نمی‌کند و بنابراین تنظیمات زوم scope نادیده می‌گیرد و per-tab را در نظر می‌گیرد.

"معلول"
تمام بزرگنمایی‌های برگه را غیرفعال می‌کند. برگه به ​​سطح بزرگنمایی پیش‌فرض برمی‌گردد و تمام تغییرات بزرگنمایی انجام شده نادیده گرفته می‌شوند.

ZoomSettingsScope

کروم ۴۴+

مشخص می‌کند که آیا تغییرات بزرگنمایی برای مبدأ صفحه باقی می‌مانند یا فقط در این برگه اعمال می‌شوند؛ در حالت automatic ، پیش‌فرض به per-origin و در غیر این صورت per-tab .

شمارشی

"به ازای هر مبدا"
تغییرات بزرگنمایی در مبدأ صفحه بزرگنمایی شده باقی می‌مانند، یعنی تمام تب‌های دیگری که به همان مبدأ پیمایش می‌شوند نیز بزرگنمایی می‌شوند. علاوه بر این، تغییرات بزرگنمایی به ازای per-origin با مبدأ ذخیره می‌شوند، به این معنی که هنگام پیمایش به صفحات دیگر در همان مبدأ، همه آنها به همان ضریب بزرگنمایی بزرگنمایی می‌شوند. دامنه per-origin فقط در حالت automatic در دسترس است.

"به ازای هر برگه"
تغییرات بزرگنمایی فقط در این برگه اعمال می‌شوند و تغییرات بزرگنمایی در برگه‌های دیگر، تاثیری بر بزرگنمایی این برگه ندارد. همچنین، تغییرات بزرگنمایی per-tab در پیمایش بازنشانی می‌شوند؛ پیمایش یک برگه همیشه صفحات را با ضرایب بزرگنمایی per-origin بارگذاری می‌کند.

خواص

MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND

کروم ۹۲+

حداکثر تعداد دفعاتی که captureVisibleTab می‌تواند در هر ثانیه فراخوانی شود. captureVisibleTab گران است و نباید زیاد فراخوانی شود.

ارزش

۲

SPLIT_VIEW_ID_NONE

در حال بررسی

شناسه‌ای که نشان‌دهنده‌ی عدم وجود تب تقسیم‌شده است.

ارزش

-1

TAB_ID_NONE

کروم ۴۶+

شناسه‌ای که نشان‌دهنده‌ی عدم وجود تب مرورگر است.

ارزش

-1

TAB_INDEX_NONE

کروم ۱۲۳+

اندیسی که نشان‌دهنده‌ی عدم وجود اندیس تب در tab_strip است.

ارزش

-1

روش‌ها

captureVisibleTab()

chrome.tabs.captureVisibleTab(
  windowId?: number,
  options?: ImageDetails,
): Promise<string>

ناحیه قابل مشاهده تب فعال فعلی در پنجره مشخص شده را ضبط می‌کند. برای فراخوانی این روش، افزونه باید مجوز <all_urls> یا مجوز activeTab را داشته باشد. علاوه بر سایت‌هایی که افزونه‌ها معمولاً می‌توانند به آنها دسترسی داشته باشند، این روش به افزونه‌ها اجازه می‌دهد سایت‌های حساسی را که در غیر این صورت محدود شده‌اند، از جمله صفحات chrome:-scheme، صفحات سایر افزونه‌ها و URLهای data:، ضبط کنند. این سایت‌های حساس فقط با مجوز activeTab قابل ضبط هستند. URLهای فایل فقط در صورتی قابل ضبط هستند که افزونه به فایل دسترسی داشته باشد.

پارامترها

بازگشت‌ها

  • قول<string>

    کروم ۸۸+

connect()

chrome.tabs.connect(
  tabId: number,
  connectInfo?: object,
): runtime.Port

به اسکریپت(های) محتوا در تب مشخص شده متصل می‌شود. رویداد runtime.onConnect در هر اسکریپت محتوا که در تب مشخص شده برای افزونه فعلی اجرا می‌شود، اجرا می‌شود. برای جزئیات بیشتر، به پیام‌رسانی اسکریپت محتوا مراجعه کنید.

پارامترها

  • شناسه برگه

    شماره

  • اطلاعات اتصال

    شیء اختیاری

    • شناسه سند

      رشته اختیاری

      کروم ۱۰۶+

      به جای تمام فریم‌های موجود در برگه، یک پورت را به یک سند خاص که توسط documentId مشخص شده است، باز کنید.

    • شناسه قاب

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

      به جای تمام فریم‌های موجود در برگه، یک پورت را برای یک فریم خاص که توسط frameId مشخص شده است، باز کنید.

    • نام

      رشته اختیاری

      برای اسکریپت‌های محتوایی که منتظر رویداد اتصال هستند، به onConnect ارسال می‌شود.

بازگشت‌ها

  • پورتی که می‌تواند برای ارتباط با اسکریپت‌های محتوایی که در تب مشخص شده اجرا می‌شوند، استفاده شود. رویداد runtime.Port مربوط به پورت در صورتی اجرا می‌شود که تب بسته شود یا وجود نداشته باشد.

create()

chrome.tabs.create(
  createProperties: object,
): Promise<Tab>

یک برگه جدید ایجاد می‌کند.

پارامترها

  • ایجاد ویژگی‌ها

    شیء

    • فعال

      بولی اختیاری

      اینکه آیا تب باید به عنوان تب فعال در پنجره انتخاب شود یا خیر. تاثیری بر فوکوس بودن پنجره ندارد (به windows.update مراجعه کنید). مقدار پیش‌فرض true است.

    • شاخص

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

      موقعیتی که تب باید در پنجره بگیرد. مقدار ارائه شده بین صفر و تعداد تب‌های موجود در پنجره محدود می‌شود.

    • تب آی دی بازکننده

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

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

    • سنجاق شده

      بولی اختیاری

      اینکه آیا تب باید پین شود یا خیر. مقدار پیش‌فرض false است.

    • انتخاب شده

      بولی اختیاری

      منسوخ شده

      لطفا از فعال استفاده کنید.

      اینکه آیا تب مورد نظر باید به عنوان تب انتخاب شده در پنجره انتخاب شود یا خیر. مقدار پیش‌فرض true است.

    • آدرس اینترنتی

      رشته اختیاری

      نشانی اینترنتی (URL) که در ابتدا باید به آن بروید. نشانی‌های اینترنتی کاملاً معتبر باید شامل یک طرح باشند (مثلاً «http://www.google.com» نه «www.google.com»). نشانی‌های اینترنتی نسبی نسبت به صفحه فعلی در افزونه هستند. پیش‌فرض روی صفحه برگه جدید است.

    • شناسه پنجره

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

      پنجره‌ای که در آن تب جدید ایجاد می‌شود. پیش‌فرض پنجره فعلی است.

بازگشت‌ها

  • قول بده< تب >

    کروم ۸۸+

detectLanguage()

chrome.tabs.detectLanguage(
  tabId?: number,
): Promise<string>

زبان اصلی محتوای یک برگه را تشخیص می‌دهد.

پارامترها

  • شناسه برگه

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

    به طور پیش‌فرض روی برگه فعال پنجره فعلی قرار می‌گیرد.

بازگشت‌ها

  • قول<string>

    کروم ۸۸+

discard()

کروم ۵۴+
chrome.tabs.discard(
  tabId?: number,
): Promise<Tab | undefined>

یک تب را از حافظه حذف می‌کند. تب‌های حذف شده هنوز در نوار تب‌ها قابل مشاهده هستند و هنگام فعال شدن دوباره بارگذاری می‌شوند.

پارامترها

  • شناسه برگه

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

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

بازگشت‌ها

  • قول< تب | تعریف نشده>

    کروم ۸۸+

duplicate()

chrome.tabs.duplicate(
  tabId: number,
): Promise<Tab | undefined>

یک برگه را کپی می‌کند.

پارامترها

  • شناسه برگه

    شماره

    شناسه‌ی برگه‌ای که قرار است کپی شود.

بازگشت‌ها

  • قول< تب | تعریف نشده>

    کروم ۸۸+

get()

chrome.tabs.get(
  tabId: number,
): Promise<Tab>

جزئیات مربوط به تب مشخص شده را بازیابی می‌کند.

پارامترها

  • شناسه برگه

    شماره

بازگشت‌ها

  • قول بده< تب >

    کروم ۸۸+

getCurrent()

chrome.tabs.getCurrent(): Promise<Tab | undefined>

تبی را که این فراخوانی اسکریپت از آن انجام می‌شود، برمی‌گرداند. اگر از یک زمینه غیر از تب (مثلاً یک صفحه پس‌زمینه یا نمای پاپ‌آپ) فراخوانی شود، undefined برمی‌گرداند.

بازگشت‌ها

  • قول< تب | تعریف نشده>

    کروم ۸۸+

getZoom()

chrome.tabs.getZoom(
  tabId?: number,
): Promise<number>

ضریب بزرگنمایی فعلی یک تب مشخص شده را دریافت می‌کند.

پارامترها

  • شناسه برگه

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

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

بازگشت‌ها

  • قول<number>

    کروم ۸۸+

getZoomSettings()

chrome.tabs.getZoomSettings(
  tabId?: number,
): Promise<ZoomSettings>

تنظیمات بزرگنمایی فعلی یک تب مشخص شده را دریافت می‌کند.

پارامترها

  • شناسه برگه

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

    شناسه‌ی برگه‌ای که تنظیمات بزرگنمایی فعلی از آن دریافت می‌شود؛ به‌طور پیش‌فرض روی برگه‌ی فعال پنجره‌ی فعلی قرار دارد.

بازگشت‌ها

goBack()

کروم ۷۲+
chrome.tabs.goBack(
  tabId?: number,
): Promise<void>

اگر صفحه‌ای در دسترس بود، به صفحه قبل برگردید.

پارامترها

  • شناسه برگه

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

    شناسه‌ی برگه‌ای که قرار است به عقب برگردد؛ به‌طور پیش‌فرض روی برگه‌ی انتخاب‌شده‌ی پنجره‌ی فعلی قرار دارد.

بازگشت‌ها

  • قول<void>

    کروم ۸۸+

goForward()

کروم ۷۲+
chrome.tabs.goForward(
  tabId?: number,
): Promise<void>

اگر صفحه‌ای در دسترس بود، به صفحه بعد بروید.

پارامترها

  • شناسه برگه

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

    شناسه‌ی برگه‌ای که قرار است به جلو حرکت کند؛ به‌طور پیش‌فرض روی برگه‌ی انتخاب‌شده‌ی پنجره‌ی فعلی قرار دارد.

بازگشت‌ها

  • قول<void>

    کروم ۸۸+

group()

کروم ۸۸+
chrome.tabs.group(
  options: object,
): Promise<number>

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

پارامترها

  • گزینه‌ها

    شیء

    • ایجاد ویژگی‌ها

      شیء اختیاری

      پیکربندی‌هایی برای ایجاد یک گروه. اگر groupId از قبل مشخص شده باشد، نمی‌توان از آن استفاده کرد.

      • شناسه پنجره

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

        پنجره‌ی گروه جدید. پیش‌فرض پنجره‌ی فعلی است.

    • شناسه گروه

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

      شناسه‌ی گروهی که تب‌ها به آن اضافه می‌شوند. اگر مشخص نشود، یک گروه جدید ایجاد خواهد شد.

    • شناسه‌های برگه

      عدد | [عدد، ...عدد[]]

      شناسه‌ی برگه یا فهرست شناسه‌های برگه برای اضافه کردن به گروه مشخص‌شده.

بازگشت‌ها

  • قول<number>

highlight()

chrome.tabs.highlight(
  highlightInfo: object,
): Promise<windows.Window>

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

پارامترها

  • اطلاعات برجسته

    شیء

    • زبانه‌ها

      عدد | عدد[]

      یک یا چند شاخص تب برای برجسته کردن.

    • شناسه پنجره

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

      پنجره‌ای که شامل تب‌ها می‌شود.

بازگشت‌ها

move()

chrome.tabs.move(
  tabIds: number | number[],
  moveProperties: object,
): Promise<Tab | Tab[]>

یک یا چند تب را به موقعیت جدیدی در پنجره خود یا به یک پنجره جدید منتقل می‌کند. توجه داشته باشید که تب‌ها فقط می‌توانند به پنجره‌های معمولی (window.type === "normal") منتقل شوند.

پارامترها

  • شناسه‌های برگه

    عدد | عدد[]

    شناسه‌ی برگه یا فهرست شناسه‌های برگه‌هایی که باید جابه‌جا شوند.

  • ویژگی‌های حرکت

    شیء

    • شاخص

      شماره

      موقعیتی که پنجره به آن منتقل می‌شود. برای قرار دادن تب در انتهای پنجره -1 استفاده کنید.

    • شناسه پنجره

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

      پیش‌فرض روی پنجره‌ای است که برگه در حال حاضر در آن قرار دارد.

بازگشت‌ها

query()

chrome.tabs.query(
  queryInfo: object,
): Promise<Tab[]>

تمام تب‌هایی که ویژگی‌های مشخص‌شده را دارند، یا تمام تب‌ها را در صورتی که هیچ ویژگی مشخص نشده باشد، برمی‌گرداند.

پارامترها

  • اطلاعات پرس و جو

    شیء

    • فعال

      بولی اختیاری

      اینکه آیا تب‌ها در پنجره‌هایشان فعال هستند یا خیر.

    • قابل شنیدن

      بولی اختیاری

      کروم ۴۵+

      اینکه آیا زبانه‌ها قابل شنیدن هستند یا خیر.

    • خودکارقابل حذف

      بولی اختیاری

      کروم ۵۴+

      اینکه آیا مرورگر می‌تواند در صورت کمبود منابع، تب‌ها را به‌طور خودکار حذف کند یا خیر.

    • پنجره فعلی

      بولی اختیاری

      اینکه آیا تب‌ها در پنجره‌ی فعلی هستند یا خیر.

    • دور انداخته شده

      بولی اختیاری

      کروم ۵۴+

      اینکه آیا تب‌ها حذف شده‌اند یا خیر. تب حذف‌شده، تبی است که محتوای آن از حافظه حذف شده است، اما هنوز در نوار تب‌ها قابل مشاهده است. محتوای آن دفعه‌ی بعد که فعال شود، دوباره بارگذاری می‌شود.

    • یخ زده

      بولی اختیاری

      کروم ۱۳۲+

      اینکه آیا تب‌ها قفل شده‌اند یا خیر. یک تب قفل‌شده نمی‌تواند وظایفی از جمله کنترل‌کننده‌های رویداد یا تایمرها را اجرا کند. در نوار تب‌ها قابل مشاهده است و محتوای آن در حافظه بارگذاری می‌شود. هنگام فعال‌سازی قفل‌شده از حالت قفل‌شده خارج می‌شود.

    • شناسه گروه

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

      کروم ۸۸+

      شناسه گروهی که تب‌ها در آن قرار دارند، یا tabGroups.TAB_GROUP_ID_NONE برای تب‌های گروه‌بندی نشده.

    • برجسته شده

      بولی اختیاری

      اینکه آیا تب‌ها هایلایت شده‌اند یا خیر.

    • شاخص

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

      موقعیت تب‌ها در پنجره‌هایشان.

    • آخرین پنجره متمرکز

      بولی اختیاری

      اینکه آیا تب‌ها در آخرین پنجره‌ی فوکوس‌شده قرار دارند یا خیر.

    • خاموش

      بولی اختیاری

      کروم ۴۵+

      اینکه آیا زبانه‌ها بی‌صدا هستند یا خیر.

    • سنجاق شده

      بولی اختیاری

      اینکه آیا تب‌ها پین شده‌اند یا خیر.

    • splitViewId

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

      کروم ۱۴۰+

      شناسه‌ی نمای تقسیم‌شده‌ای که تب‌ها در آن قرار دارند، یا tabs.SPLIT_VIEW_ID_NONE برای تب‌هایی که در نمای تقسیم‌شده نیستند.

    • وضعیت

      وضعیت برگه ( اختیاری)

      وضعیت بارگذاری تب.

    • عنوان

      رشته اختیاری

      عناوین صفحات را با یک الگو مطابقت دهید. اگر افزونه مجوز "tabs" یا مجوزهای میزبان برای صفحه را نداشته باشد، این ویژگی نادیده گرفته می‌شود.

    • آدرس اینترنتی

      رشته | رشته[] اختیاری

      تب‌ها را با یک یا چند الگوی URL مطابقت دهید. شناسه‌های قطعه مطابقت ندارند. اگر افزونه مجوز "tabs" یا مجوزهای میزبان برای صفحه را نداشته باشد، این ویژگی نادیده گرفته می‌شود.

    • شناسه پنجره

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

      شناسه پنجره والد، یا windows.WINDOW_ID_CURRENT برای پنجره فعلی .

    • نوع پنجره

      نوع پنجره اختیاری

      نوع پنجره‌ای که تب‌ها در آن قرار دارند.

بازگشت‌ها

  • قول بده< تب []>

    کروم ۸۸+

reload()

chrome.tabs.reload(
  tabId?: number,
  reloadProperties?: object,
): Promise<void>

یک برگه را دوباره بارگذاری کنید.

پارامترها

  • شناسه برگه

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

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

  • بارگذاری مجدد ویژگی‌ها

    شیء اختیاری

    • بای‌پس‌کش

      بولی اختیاری

      اینکه آیا از ذخیره‌سازی محلی صرف‌نظر شود یا خیر. مقدار پیش‌فرض false است.

بازگشت‌ها

  • قول<void>

    کروم ۸۸+

remove()

chrome.tabs.remove(
  tabIds: number | number[],
): Promise<void>

یک یا چند تب را می‌بندد.

پارامترها

  • شناسه‌های برگه

    عدد | عدد[]

    شناسه‌ی برگه یا فهرست شناسه‌های برگه‌هایی که باید بسته شوند.

بازگشت‌ها

  • قول<void>

    کروم ۸۸+

sendMessage()

chrome.tabs.sendMessage(
  tabId: number,
  message: any,
  options?: object,
): Promise<any>

یک پیام واحد را به اسکریپت(های) محتوا در برگه مشخص شده ارسال می‌کند، به همراه یک فراخوانی اختیاری که هنگام ارسال پاسخ اجرا می‌شود. رویداد runtime.onMessage در هر اسکریپت محتوا که در برگه مشخص شده برای افزونه فعلی اجرا می‌شود، اجرا می‌شود.

پارامترها

  • شناسه برگه

    شماره

  • پیام

    هر

    پیامی که باید ارسال شود. این پیام باید یک شیء با قابلیت پشتیبانی از JSON باشد.

  • گزینه‌ها

    شیء اختیاری

    • شناسه سند

      رشته اختیاری

      کروم ۱۰۶+

      به جای تمام فریم‌های موجود در برگه، پیامی را به یک سند خاص که توسط documentId مشخص شده است ارسال کنید.

    • شناسه قاب

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

      به جای ارسال پیام به تمام فریم‌های موجود در تب، پیامی را به یک فریم خاص که با frameId مشخص شده است، ارسال کنید.

بازگشت‌ها

  • قول بده<any>

    کروم ۹۹+

setZoom()

chrome.tabs.setZoom(
  tabId?: number,
  zoomFactor: number,
): Promise<void>

یک تب مشخص شده را بزرگنمایی می‌کند.

پارامترها

  • شناسه برگه

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

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

  • زوم فاکتور

    شماره

    ضریب بزرگنمایی جدید. مقدار 0 ، ضریب بزرگنمایی پیش‌فرض فعلی تب را تنظیم می‌کند. مقادیر بزرگتر از 0 یک ضریب بزرگنمایی (احتمالاً غیر پیش‌فرض) برای تب مشخص می‌کنند.

بازگشت‌ها

  • قول<void>

    کروم ۸۸+

setZoomSettings()

chrome.tabs.setZoomSettings(
  tabId?: number,
  zoomSettings: ZoomSettings,
): Promise<void>

تنظیمات بزرگنمایی را برای یک برگه مشخص شده تنظیم می‌کند، که نحوه مدیریت تغییرات بزرگنمایی را تعریف می‌کند. این تنظیمات پس از پیمایش برگه به ​​مقادیر پیش‌فرض بازنشانی می‌شوند.

پارامترها

  • شناسه برگه

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

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

  • تنظیمات زوم

    تنظیمات زوم

    تعریف می‌کند که تغییرات بزرگنمایی چگونه و در چه محدوده‌ای مدیریت شوند.

بازگشت‌ها

  • قول<void>

    کروم ۸۸+

ungroup()

کروم ۸۸+
chrome.tabs.ungroup(
  tabIds: number | [number, ...number[]],
): Promise<void>

یک یا چند تب را از گروه‌های مربوطه حذف می‌کند. اگر هر گروهی خالی شود، حذف می‌شود.

پارامترها

  • شناسه‌های برگه

    عدد | [عدد، ...عدد[]]

    شناسه‌ی برگه یا فهرست شناسه‌های برگه برای حذف از گروه‌های مربوطه.

بازگشت‌ها

  • قول<void>

update()

chrome.tabs.update(
  tabId?: number,
  updateProperties: object,
): Promise<Tab | undefined>

ویژگی‌های یک تب را تغییر می‌دهد. ویژگی‌هایی که در updateProperties مشخص نشده‌اند، تغییر نمی‌کنند.

پارامترها

  • شناسه برگه

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

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

  • به‌روزرسانی‌ها

    شیء

    • فعال

      بولی اختیاری

      اینکه آیا تب باید فعال باشد یا خیر. تاثیری بر اینکه پنجره در حالت فوکوس باشد یا خیر ندارد (به windows.update مراجعه کنید).

    • خودکارقابل حذف

      بولی اختیاری

      کروم ۵۴+

      اینکه آیا مرورگر در صورت کمبود منابع، تب را به‌طور خودکار حذف کند یا خیر.

    • برجسته شده

      بولی اختیاری

      تب را از انتخاب فعلی اضافه یا حذف می‌کند.

    • خاموش

      بولی اختیاری

      کروم ۴۵+

      اینکه آیا تب باید بی‌صدا شود یا خیر.

    • تب آی دی بازکننده

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

      شناسه‌ی برگه‌ای که این برگه را باز کرده است. در صورت مشخص شدن، برگه‌ی بازکننده باید در همان پنجره‌ای باشد که این برگه در آن قرار دارد.

    • سنجاق شده

      بولی اختیاری

      اینکه آیا تب باید پین شود یا خیر.

    • انتخاب شده

      بولی اختیاری

      منسوخ شده

      لطفا از هایلایت شده استفاده کنید.

      اینکه آیا برگه باید انتخاب شود یا خیر.

    • آدرس اینترنتی

      رشته اختیاری

      یک URL برای پیمایش تب. URL های جاوا اسکریپت پشتیبانی نمی‌شوند؛ به جای آن scripting.executeScript استفاده کنید.

بازگشت‌ها

  • قول< تب | تعریف نشده>

    کروم ۸۸+

رویدادها

onActivated

chrome.tabs.onActivated.addListener(
  callback: function,
)

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

پارامترها

  • تماس برگشتی

    تابع

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

    (activeInfo: object) => void

    • اطلاعات فعال

      شیء

      • شناسه برگه

        شماره

        شناسه‌ی برگه‌ای که فعال شده است.

      • شناسه پنجره

        شماره

        شناسه‌ی پنجره‌ای که تب فعال درون آن تغییر کرده است.

onAttached

chrome.tabs.onAttached.addListener(
  callback: function,
)

زمانی اجرا می‌شود که یک تب به یک پنجره متصل شده باشد؛ برای مثال، به دلیل جابجایی بین پنجره‌ها.

پارامترها

  • تماس برگشتی

    تابع

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

    (tabId: number, attachInfo: object) => void

    • شناسه برگه

      شماره

    • اطلاعات پیوست

      شیء

      • موقعیت جدید

        شماره

      • شناسه پنجره جدید

        شماره

onCreated

chrome.tabs.onCreated.addListener(
  callback: function,
)

هنگام ایجاد یک تب، فعال می‌شود. توجه داشته باشید که ممکن است URL تب و عضویت در گروه تب در زمان فعال شدن این رویداد تنظیم نشده باشند، اما می‌توانید به رویدادهای onUpdated گوش دهید تا هنگام تنظیم URL یا اضافه شدن تب به یک گروه تب، مطلع شوید.

پارامترها

  • تماس برگشتی

    تابع

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

    (tab: Tab) => void

onDetached

chrome.tabs.onDetached.addListener(
  callback: function,
)

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

پارامترها

  • تماس برگشتی

    تابع

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

    (tabId: number, detachInfo: object) => void

    • شناسه برگه

      شماره

    • اطلاعات را جدا کنید

      شیء

      • موقعیت قدیمی

        شماره

      • شناسه پنجره قدیمی

        شماره

onHighlighted

chrome.tabs.onHighlighted.addListener(
  callback: function,
)

زمانی اجرا می‌شود که زبانه‌های برجسته‌شده یا انتخاب‌شده در یک پنجره تغییر کنند.

پارامترها

  • تماس برگشتی

    تابع

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

    (highlightInfo: object) => void

    • اطلاعات برجسته

      شیء

      • شناسه‌های برگه

        شماره[]

        تمام تب‌های هایلایت شده در پنجره.

      • شناسه پنجره

        شماره

        پنجره‌ای که زبانه‌هایش تغییر کرده است.

onMoved

chrome.tabs.onMoved.addListener(
  callback: function,
)

زمانی اجرا می‌شود که یک تب درون یک پنجره جابجا شود. فقط یک رویداد جابجایی اجرا می‌شود که نشان‌دهنده‌ی تبی است که کاربر مستقیماً جابجا کرده است. رویدادهای جابجایی برای سایر تب‌هایی که باید در پاسخ به تب جابجا شده دستی جابجا شوند، اجرا نمی‌شوند. این رویداد زمانی اجرا نمی‌شود که یک تب بین پنجره‌ها جابجا شود؛ برای جزئیات بیشتر، به tabs.onDetached مراجعه کنید.

پارامترها

  • تماس برگشتی

    تابع

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

    (tabId: number, moveInfo: object) => void

    • شناسه برگه

      شماره

    • اطلاعات حرکت

      شیء

      • از فهرست

        شماره

      • به فهرست

        شماره

      • شناسه پنجره

        شماره

onRemoved

chrome.tabs.onRemoved.addListener(
  callback: function,
)

وقتی یک تب بسته می‌شود، فعال می‌شود.

پارامترها

  • تماس برگشتی

    تابع

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

    (tabId: number, removeInfo: object) => void

    • شناسه برگه

      شماره

    • حذف اطلاعات

      شیء

      • بستن پنجره

        بولی

        زمانی که تب به دلیل بسته بودن پنجره والدش بسته شده باشد، صحیح است.

      • شناسه پنجره

        شماره

        پنجره‌ای که تب آن بسته است.

onReplaced

chrome.tabs.onReplaced.addListener(
  callback: function,
)

زمانی اجرا می‌شود که یک تب به دلیل پیش‌رندر یا آنی با تب دیگری جایگزین شود.

پارامترها

  • تماس برگشتی

    تابع

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

    (addedTabId: number, removedTabId: number) => void

    • تب اضافه شده

      شماره

    • TabId حذف شد

      شماره

onUpdated

chrome.tabs.onUpdated.addListener(
  callback: function,
)

هنگامی که یک برگه به‌روزرسانی می‌شود، اجرا می‌شود.

پارامترها

  • تماس برگشتی

    تابع

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

    (tabId: number, changeInfo: object, tab: Tab) => void

    • شناسه برگه

      شماره

    • تغییراطلاعات

      شیء

      • قابل شنیدن

        بولی اختیاری

        کروم ۴۵+

        وضعیت جدید قابل شنیدن تب.

      • خودکارقابل حذف

        بولی اختیاری

        کروم ۵۴+

        حالت جدید حذف خودکار تب.

      • دور انداخته شده

        بولی اختیاری

        کروم ۵۴+

        حالت جدید حذف‌شده‌ی تب.

      • آدرس آیکون مورد علاقه

        رشته اختیاری

        آدرس اینترنتی جدید فاوآیکن تب.

      • یخ زده

        بولی اختیاری

        کروم ۱۳۲+

        حالت جدید و ثابت تب.

      • شناسه گروه

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

        کروم ۸۸+

        گروه جدید تب.

      • اطلاعات بی‌صدا

        اطلاعات خاموش اختیاری

        کروم ۴۶+

        وضعیت بی‌صدا شدن جدید تب و دلیل این تغییر.

      • سنجاق شده

        بولی اختیاری

        وضعیت جدید پین‌شده‌ی تب.

      • splitViewId

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

        کروم ۱۴۰+

        نمای تقسیم‌شده‌ی جدید تب.

      • وضعیت

        وضعیت برگه ( اختیاری)

        وضعیت بارگذاری برگه.

      • عنوان

        رشته اختیاری

        کروم ۴۸+

        عنوان جدید برگه.

      • آدرس اینترنتی

        رشته اختیاری

        آدرس اینترنتی (URL) برگه، در صورت تغییر آن.

    • تب

      تب

onZoomChange

chrome.tabs.onZoomChange.addListener(
  callback: function,
)

هنگامی که یک تب بزرگنمایی می‌شود، اجرا می‌شود.

پارامترها

  • تماس برگشتی

    تابع

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

    (ZoomChangeInfo: object) => void

    • اطلاعات تغییر زوم

      شیء

      • فاکتور بزرگنمایی جدید

        شماره

      • فاکتور زوم قدیمی

        شماره

      • شناسه برگه

        شماره

      • تنظیمات زوم

        تنظیمات زوم