chrome.tabs

תיאור

משתמשים ב-API של chrome.tabs כדי לקיים אינטראקציה עם מערכת הכרטיסיות של הדפדפן. אפשר להשתמש ב-API הזה כדי ליצור, לשנות ולסדר מחדש כרטיסיות בדפדפן.

Tabs API לא רק מציע תכונות לצורך מניפולציה וניהול של כרטיסיות, אלא גם יכול לזהות את השפה של הכרטיסייה, לצלם צילום מסך ולבצע תקשורת עם סקריפטים של תוכן בכרטיסייה.

הרשאות

כדי להשתמש ברוב התכונות לא נדרשות הרשאות. לדוגמה: יצירה של כרטיסייה חדשה, טעינה מחדש של כרטיסייה, ניווט לכתובת URL אחרת וכו'.

יש שלוש הרשאות שמפתחים צריכים להכיר כשהם עובדים עם Tabs API.

ההרשאה 'כרטיסיות'

ההרשאה הזו לא מעניקה גישה למרחב השמות chrome.tabs. במקום זאת, הוא מעניק לתוסף את היכולת לבצע קריאה ל-tabs.query() לגבי ארבעה מאפיינים רגישים במופעים של tabs.Tab: url,‏ pendingUrl,‏ title ו-favIconUrl.

{
  "name": "My extension",
  ...
  "permissions": [
    "tabs"
  ],
  ...
}
הרשאות של המארחים

הרשאות מארח מאפשרות לתוסף לקרוא את ארבעת המאפיינים הרגישים tabs.Tab של הכרטיסייה התואמת ולהריץ עליהם שאילתות. הם יכולים גם לקיים אינטראקציה ישירה עם הכרטיסיות התואמות באמצעות שיטות כמו tabs.captureVisibleTab(),‏ tabs.executeScript(),‏ tabs.insertCSS() ו-tabs.removeCSS().

{
  "name": "My extension",
  ...
  "host_permissions": [
    "http://*/*",
    "https://*/*"
  ],
  ...
}
ההרשאה 'activeTab'

activeTab מעניקה לתוסף הרשאת מארח זמנית לכרטיסייה הנוכחית בתגובה להפעלה על ידי משתמש. בניגוד להרשאות המארח, activeTab לא מפעילה אזהרות.

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

תרחישים לדוגמה

בקטעים הבאים מפורטים כמה תרחישים נפוצים לדוגמה.

פתיחת דף של תוסף בכרטיסייה חדשה

דפוס נפוץ בתוספים הוא לפתוח דף קליטה בכרטיסייה חדשה כשמתקינים את התוסף. הדוגמה הבאה ממחישה איך עושים את זה.

background.js:

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

אחזור הכרטיסייה הנוכחית

הדוגמה הזו ממחישה איך ה-service worker של תוסף יכול לאחזר את הכרטיסייה הפעילה מהחלון שבו מופיע המיקוד כרגע (או מהחלון שבו היה המיקוד לאחרונה, אם אף חלון Chrome לא ממוקד). בדרך כלל אפשר להתייחס אליו ככרטיסייה הנוכחית של המשתמש.

  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.");
      }
    });
  }

העברת הודעה לסקריפט התוכן של הכרטיסייה שנבחרה

הדוגמה הזו מראה איך ה-service worker של תוסף יכול לתקשר עם סקריפטים של תוכן בכרטיסיות ספציפיות בדפדפן באמצעות 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

Chrome מגרסה 46 ואילך

מצב ההשתקה של הכרטיסייה והסיבה לשינוי המצב האחרון.

מאפיינים

  • extensionId

    מחרוזת אופציונלי

    המזהה של התוסף ששינה את מצב ההשתקה. לא מוגדר אם תוסף לא היה הסיבה לשינוי האחרון של מצב ההשתקה.

  • הושתק

    בוליאני

    אם הכרטיסייה מושתקת (לא ניתן להפעיל בה אודיו). הכרטיסייה עשויה להיות מושתקת גם אם לא הייתה בה הפעלה של אודיו או שאין בה הפעלה של אודיו כרגע. זהו ערך שווה ערך למצב שבו מופיע מחוון האודיו 'מושתק'.

  • סיבה

    MutedInfoReason אופציונלי

    הסיבה להשתקת הכרטיסייה או להסרת ההשתקה שלה. לא מוגדר אם מצב ההשתקה של הכרטיסייה מעולם לא השתנה.

MutedInfoReason

Chrome מגרסה 46 ואילך

אירוע שגרם לשינוי במצב ההשתקה.

Enum

'user'
פעולת קלט של משתמש מגדירה את מצב ההשתקה.

'צילום'
התחילה צילום של כרטיסייה, מה שגרם לשינוי הסטטוס של ההשתקה.

"extension"
תוסף, שמזוהה לפי השדה extensionId, הגדיר את מצב ההשתקה.

Tab

מאפיינים

  • פעיל

    בוליאני

    האם הכרטיסייה פעילה בחלון שלה. לא בהכרח סימן שהחלון נמצא במצב מיקוד.

  • audible, אודיבל

    בוליאני אופציונלי

    Chrome מגרסה 45 ואילך

    אם נשמע צליל מהכרטיסייה בשניות האחרונות (אבל יכול להיות שלא תהיה אפשרות לשמוע אותו אם הוא גם מושתק). זהו ערך שווה ערך למצב שבו מופיע האינדיקטור 'אודיו של רמקול'.

  • autoDiscardable

    בוליאני

    Chrome מגרסה 54 ואילך

    האם הדפדפן יכול לסגור את הכרטיסייה באופן אוטומטי כשהמשאבים מצומצמים.

  • דחית את

    בוליאני

    Chrome מגרסה 54 ואילך

    האם הכרטיסייה תימחק. כרטיסייה שהתוכן שלה הוצא מהזיכרון, אבל עדיין מוצגת בסרגל הכרטיסיות. התוכן שלו נטען מחדש בפעם הבאה שהוא מופעל.

  • favIconUrl

    מחרוזת אופציונלי

    כתובת ה-URL של סמל האתר של הכרטיסייה. המאפיין הזה קיים רק אם המניפסט של התוסף כולל את ההרשאה "tabs". היא עשויה להיות גם מחרוזת ריקה אם הכרטיסייה נמצאת בתהליך טעינה.

  • קפוא

    בוליאני

    בהמתנה

    אם הכרטיסייה קפואה. כרטיסייה קפואה לא יכולה לבצע משימות, כולל טיפול באירועים או שעונים. היא מוצגת בסרגל הכרטיסיות והתוכן שלה נטען בזיכרון. הוא משוחרר מההקפאה בזמן ההפעלה.

  • groupId

    number

    גרסה 88 ואילך של Chrome

    המזהה של הקבוצה שאליה שייכת הכרטיסייה.

  • גובה

    מספר אופציונלי

    הגובה של הכרטיסייה בפיקסלים.

  • מודגש

    בוליאני

    אם הכרטיסייה מודגשת.

  • id [מזהה]

    מספר אופציונלי

    המזהה של הכרטיסייה. מזהי הכרטיסיות הם ייחודיים בסשן הדפדפן. בנסיבות מסוימות, יכול להיות שלא יוקצה מזהה לכרטיסייה. לדוגמה, כששולחים שאילתה לגבי כרטיסיות חיצוניות באמצעות ה-API של sessions. במקרה כזה, יכול להיות שיופיע מזהה סשן. אפשר גם להגדיר את מזהה הכרטיסייה כ-chrome.tabs.TAB_ID_NONE לאפליקציות ולחלונות של devtools.

  • מצב פרטי

    בוליאני

    האם הכרטיסייה נמצאת בחלון פרטי.

  • אינדקס

    number

    האינדקס שמתחיל בספרה אפס של הכרטיסייה בחלון שלה.

  • lastAccessed

    number

    Chrome מגרסה 121 ואילך

    הפעם האחרונה שבה הייתה גישה לכרטיסייה, כמספר אלפיות השנייה מאז תחילת המילניום.

  • mutedInfo

    MutedInfo אופציונלי

    Chrome מגרסה 46 ואילך

    מצב ההשתקה של הכרטיסייה והסיבה לשינוי המצב האחרון.

  • openerTabId

    מספר אופציונלי

    המזהה של הכרטיסייה שדרכה נפתחה הכרטיסייה הזו, אם יש כזו. המאפיין הזה קיים רק אם הכרטיסייה שפתחה את הדף עדיין קיימת.

  • pendingUrl

    מחרוזת אופציונלי

    Chrome מגרסה 79 ואילך

    כתובת ה-URL שאליה הכרטיסייה עוברת, לפני שהיא מתחייבת אליה. הנכס הזה קיים רק אם המניפסט של התוסף כולל את ההרשאה "tabs" ויש ניווט בהמתנה.

  • מוצמד

    בוליאני

    אם הכרטיסייה מוצמדת.

  • נבחר

    בוליאני

    הוצא משימוש

    יש להשתמש ב-tabs.Tab.highlighted.

    אם הכרטיסייה מסומנת.

  • sessionId

    מחרוזת אופציונלי

    מזהה הסשן שמשמש לזיהוי ייחודי של כרטיסייה שהתקבלה מ-API של sessions.

  • status

    TabStatus אופציונלי

    סטטוס הטעינה של הכרטיסייה.

  • title

    מחרוזת אופציונלי

    שם הכרטיסייה. המאפיין הזה קיים רק אם המניפסט של התוסף כולל את ההרשאה "tabs".

  • כתובת אתר

    מחרוזת אופציונלי

    כתובת ה-URL האחרונה שהתחייבו לה במסגרת הראשית של הכרטיסייה. המאפיין הזה קיים רק אם המניפסט של התוסף כולל את ההרשאה "tabs", ויכול להיות שהוא יהיה מחרוזת ריקה אם הכרטיסייה עדיין לא הושלמה. מידע נוסף זמין במאמר Tab.pendingUrl.

  • רוחב

    מספר אופציונלי

    רוחב הכרטיסייה בפיקסלים.

  • windowId

    number

    המזהה של החלון שמכיל את הכרטיסייה.

TabStatus

גרסה 44 ואילך של Chrome

סטטוס הטעינה של הכרטיסייה.

Enum

"unloaded"

"loading"

'complete'

WindowType

גרסה 44 ואילך של Chrome

סוג החלון.

Enum

"normal"

"popup"

"panel"

"app"

"devtools"

ZoomSettings

הגדרת האופן שבו מטפלים בשינויים ברמת הזום בכרטיסייה ובאיזה היקף.

מאפיינים

  • defaultZoomFactor

    מספר אופציונלי

    Chrome מגרסה 43 ואילך

    משמש להחזרת רמת הזום שמוגדרת כברירת מחדל בכרטיסייה הנוכחית בקריאות ל-tabs.getZoomSettings.

  • מצב

    ZoomSettingsMode אופציונלי

    מגדיר את אופן הטיפול בשינויים בהגדלת התצוגה, כלומר איזו ישות אחראית לשינוי בפועל של קנה המידה של הדף. ברירת המחדל היא automatic.

  • היקף

    ZoomSettingsScope אופציונלי

    ההגדרה קובעת אם שינויי הזום יישארו במקור של הדף או ייכנסו לתוקף רק בכרטיסייה הזו. ברירת המחדל היא per-origin במצב automatic, ו-per-tab במקרים אחרים.

ZoomSettingsMode

גרסה 44 ואילך של Chrome

מגדיר את אופן הטיפול בשינויים בהגדלת התצוגה, כלומר איזו ישות אחראית לשינוי בפועל של קנה המידה של הדף. ברירת המחדל היא automatic.

Enum

'אוטומטי'
הדפדפן מטפל בשינויי הזום באופן אוטומטי.

'manual'
מבטלת את הטיפול האוטומטי בשינויי זום. האירוע onZoomChange עדיין יישלח, והתוסף אחראי להאזין לאירוע הזה ולשנות את הגודל של הדף באופן ידני. במצב הזה אין תמיכה בהגדלת התצוגה per-origin, ולכן המערכת מתעלמת מהגדלת התצוגה scope ומניחה שהיא per-tab.

'disabled'
השבתה של כל פעולות הזום בכרטיסייה. הכרטיסייה חוזרת למרחק התצוגה שמוגדר כברירת מחדל, וכל הניסיונות לשינוי מרחק התצוגה מתעלמים.

ZoomSettingsScope

גרסה 44 ואילך של Chrome

ההגדרה קובעת אם שינויי הזום יישארו במקור של הדף או ייכנסו לתוקף רק בכרטיסייה הזו. ברירת המחדל היא per-origin במצב automatic, ו-per-tab במקרים אחרים.

Enum

'לכל מקור'
שינויים בהגדלת התצוגה נשמרים במקור של הדף המוגדל, כלומר כל הכרטיסיות האחרות שמנווטות לאותו מקור מוגדלות גם הן. בנוסף, שינויי הזום של per-origin נשמרים עם המקור, כלומר כשמנווטים לדפים אחרים באותו מקור, הזום של כולם משתנה לאותו גורם זום. ההיקף per-origin זמין רק במצב automatic.

'לכל כרטיסייה'
שינויים במרחק התצוגה ייכנסו לתוקף רק בכרטיסייה הזו, ושינויים במרחק התצוגה בכרטיסיות אחרות לא ישפיעו על מרחק התצוגה בכרטיסייה הזו. בנוסף, שינויי מרחק התצוגה per-tab מתאפסים בזמן הניווט. כשעוברים לכרטיסייה אחרת, הדפים נטענים תמיד עם גורמי מרחק התצוגה per-origin שלהם.

מאפיינים

MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND

Chrome מגרסה 92 ואילך

מספר הפעמים המקסימלי שניתן להפעיל את captureVisibleTab בשנייה. captureVisibleTab הוא יקר ולא מומלץ להפעיל אותו לעיתים קרובות מדי.

ערך

2

TAB_ID_NONE

Chrome מגרסה 46 ואילך

מזהה שמייצג את היעדר מכרטיסיית הדפדפן.

ערך

-1

TAB_INDEX_NONE

Chrome מגרסה 123 ואילך

אינדקס שמייצג את היעדר אינדקס הכרטיסייה ב-tab_strip.

ערך

-1

Methods

captureVisibleTab()

Promise 
chrome.tabs.captureVisibleTab(
  windowId?: number,
  options?: ImageDetails,
  callback?: function,
)

צילום האזור הגלוי של הכרטיסייה הפעילה הנוכחית בחלון שצוין. כדי לקרוא ל-method הזה, לתוסף צריכה להיות ההרשאה <all_urls> או ההרשאה activeTab. בנוסף לאתרים שאליהם תוספים יכולים לגשת באופן רגיל, השיטה הזו מאפשרת לתוספים לתעד אתרים רגישים שהגישה אליהם מוגבלת בדרכים אחרות, כולל דפים עם תבנית chrome:‎, דפים של תוספים אחרים וכתובות URL מסוג data: ‎. אפשר לתעד אתרים רגישים כאלה רק עם ההרשאה activeTab. אפשר לתעד כתובות URL של קבצים רק אם הוקצו לתוסף הרשאות גישה לקובץ.

פרמטרים

  • windowId

    מספר אופציונלי

    חלון היעד. ברירת המחדל היא החלון הנוכחי.

  • אפשרויות

    ImageDetails אופציונלי

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (dataUrl: string) => void

    • dataUrl

      מחרוזת

      כתובת URL של נתונים שמקודדת תמונה של האזור הגלוי בכרטיסייה שצולמה. אפשר להקצות אותו למאפיין 'src' של רכיב HTML‏ img להצגה.

החזרות

  • Promise<string>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

connect()

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

מתחבר לסקריפטים של התוכן בכרטיסייה שצוינה. האירוע runtime.onConnect מופעל בכל סקריפט תוכן שפועל בכרטיסייה שצוינה של התוסף הנוכחי. מידע נוסף זמין במאמר הודעות ב-Content Script.

פרמטרים

  • tabId

    number

  • connectInfo

    אובייקט אופציונלי

    • documentId

      מחרוזת אופציונלי

      גרסה 106 ואילך של Chrome

      פתיחת יציאה למסמך ספציפי שמזוהה על ידי documentId במקום לכל המסגרות בכרטיסייה.

    • frameId

      מספר אופציונלי

      פתיחת יציאה לפריים ספציפי שמזוהה על ידי frameId במקום לכל הפריים בכרטיסייה.

    • שם

      מחרוזת אופציונלי

      מועבר ל-onConnect עבור סקריפטים של תוכן שמאזינים לאירוע החיבור.

החזרות

  • יציאה שאפשר להשתמש בה כדי לתקשר עם סקריפטים של תוכן שפועלים בכרטיסייה שצוינה. האירוע runtime.Port של השקע מופעל אם הכרטיסייה נסגרת או לא קיימת.

create()

Promise 
chrome.tabs.create(
  createProperties: object,
  callback?: function,
)

יצירת כרטיסייה חדשה.

פרמטרים

  • createProperties

    אובייקט

    • פעיל

      בוליאני אופציונלי

      אם הכרטיסייה תהיה הכרטיסייה הפעילה בחלון. לא משפיע על המיקוד בחלון (ראו windows.update). ברירת המחדל היא true.

    • אינדקס

      מספר אופציונלי

      המיקום שבו הכרטיסייה אמורה להופיע בחלון. הערך שצוין מוגבל לאפס ולמספר הכרטיסיות בחלון.

    • openerTabId

      מספר אופציונלי

      המזהה של הכרטיסייה שדרכה נפתחה הכרטיסייה הזו. אם צוין כרטיסייה פתוחה, היא צריכה להיות באותו חלון שבו נמצאת הכרטיסייה החדשה שנוצרה.

    • מוצמד

      בוליאני אופציונלי

      האם הכרטיסייה צריכה להיות מוצמדת. ברירת המחדל היא false

    • נבחר

      בוליאני אופציונלי

      הוצא משימוש

      צריך להשתמש באפשרות פעיל.

      אם הכרטיסייה תהיה הכרטיסייה שנבחרה בחלון. ברירת המחדל היא true

    • כתובת אתר

      מחרוזת אופציונלי

      כתובת ה-URL שאליה מובילת הכרטיסייה בהתחלה. כתובות URL מוגדרות במלואן חייבות לכלול סכימה (כלומר, 'http://www.google.com' ולא 'www.google.com'). כתובות URL יחסיות הן יחסיות לדף הנוכחי בתוסף. ברירת המחדל היא הדף 'כרטיסייה חדשה'.

    • windowId

      מספר אופציונלי

      החלון שבו יוצרים את הכרטיסייה החדשה. ברירת המחדל היא החלון הנוכחי.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (tab: Tab) => void

    • כרטיסייה

      מקש Tab

      הכרטיסייה שנוצרה.

החזרות

  • Promise<Tab>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

detectLanguage()

Promise 
chrome.tabs.detectLanguage(
  tabId?: number,
  callback?: function,
)

זיהוי השפה הראשית של התוכן בכרטיסייה.

פרמטרים

  • tabId

    מספר אופציונלי

    ברירת המחדל היא הכרטיסייה הפעילה בחלון הנוכחי.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (language: string) => void

    • language

      מחרוזת

      קוד שפה לפי תקן ISO, כמו en או fr. רשימה מלאה של השפות שנתמכות בשיטה הזו מופיעה במאמר kLanguageInfoTable. העמודות השנייה עד הרביעית נבדקות והערך הראשון שאינו NULL מוחזר, מלבד סינית פשוטה, שבה מוחזר הערך zh-CN. אם השפה לא מוגדרת או לא ידועה, המערכת מחזירה את הערך und.

החזרות

  • Promise<string>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

discard()

Promise Chrome מגרסה 54 ואילך 
chrome.tabs.discard(
  tabId?: number,
  callback?: function,
)

ביטול כרטיסייה מהזיכרון. כרטיסיות שהוצאו משימוש עדיין מוצגות בשורת הכרטיסיות ונטענות מחדש כשמפעילים אותן.

פרמטרים

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שרוצים להשליך. אם מצוין, הכרטיסייה תושלך אלא אם היא פעילה או שכבר הושלכה. אם השמטתם את הפרמטר, הדפדפן יטמיע את הכרטיסייה הפחות חשובה. הפעולה הזו עלולה להיכשל אם אין כרטיסיות שאפשר להשליך.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (tab?: Tab) => void

    • כרטיסייה

      Tab אופציונלי

      הכרטיסייה שהושמטה, אם היא הושמטה בהצלחה. אחרת, הערך לא מוגדר.

החזרות

  • Promise<Tab | undefined>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

duplicate()

Promise 
chrome.tabs.duplicate(
  tabId: number,
  callback?: function,
)

שכפול כרטיסייה.

פרמטרים

  • tabId

    number

    המזהה של הכרטיסייה שרוצים לשכפל.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (tab?: Tab) => void

    • כרטיסייה

      Tab אופציונלי

      פרטים על הכרטיסייה הכפולה. האובייקט tabs.Tab לא מכיל את הערכים url,‏ pendingUrl,‏ title ו-favIconUrl אם לא נשלחה בקשה להרשאה "tabs".

החזרות

  • Promise<Tab | undefined>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

executeScript()

Promise &leq; MV2 הווצא משימוש החל מ-Chrome 91
chrome.tabs.executeScript(
  tabId?: number,
  details: InjectDetails,
  callback?: function,
)

הוחלף על ידי scripting.executeScript ב-Manifest V3.

הוספה של קוד JavaScript לדף. פרטים נוספים זמינים בקטע הזרקה פרוגרמטית במסמך בנושא סקריפטים של תוכן.

פרמטרים

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שבה רוצים להריץ את הסקריפט. ברירת המחדל היא הכרטיסייה הפעילה בחלון הנוכחי.

  • פרטים

    InjectDetails

    פרטי הסקריפט שרוצים להריץ. צריך להגדיר את הקוד או את מאפיין הקובץ, אבל לא את שניהם בו-זמנית.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (result?: any[]) => void

    • תוצאה

      any[] אופציונלי

      התוצאה של הסקריפט בכל פריים שהוחדר.

החזרות

  • Promise<any[] | undefined>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

get()

Promise 
chrome.tabs.get(
  tabId: number,
  callback?: function,
)

אחזור פרטים על הכרטיסייה שצוינה.

פרמטרים

  • tabId

    number

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (tab: Tab) => void

החזרות

  • Promise<Tab>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getAllInWindow()

Promise &leq; MV2 Deprecated
chrome.tabs.getAllInWindow(
  windowId?: number,
  callback?: function,
)

יש להשתמש ב-tabs.query {windowId: windowId}.

הפונקציה מקבלת פרטים על כל הכרטיסיות בחלון שצוין.

פרמטרים

  • windowId

    מספר אופציונלי

    ברירת המחדל היא החלון הנוכחי.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (tabs: Tab[]) => void

    • כרטיסיות

      Tab[]

החזרות

  • Promise<Tab[]>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getCurrent()

Promise 
chrome.tabs.getCurrent(
  callback?: function,
)

הפונקציה מקבלת את הכרטיסייה שממנה מתבצעת הקריאה של הסקריפט. הפונקציה מחזירה את הערך undefined אם היא נקראת מהקשר שאינו כרטיסייה (לדוגמה, דף רקע או תצוגת חלון קופץ).

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (tab?: Tab) => void

    • כרטיסייה

      Tab אופציונלי

החזרות

  • Promise<Tab | undefined>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getSelected()

Promise &leq; MV2 Deprecated
chrome.tabs.getSelected(
  windowId?: number,
  callback?: function,
)

יש להשתמש ב-tabs.query {active: true}.

הפונקציה מקבלת את הכרטיסייה שנבחרה בחלון שצוין.

פרמטרים

  • windowId

    מספר אופציונלי

    ברירת המחדל היא החלון הנוכחי.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (tab: Tab) => void

החזרות

  • Promise<Tab>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getZoom()

Promise 
chrome.tabs.getZoom(
  tabId?: number,
  callback?: function,
)

הפונקציה מקבלת את גורם הזום הנוכחי של כרטיסייה ספציפית.

פרמטרים

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שממנה רוצים לקבל את גורם הזום הנוכחי. ברירת המחדל היא הכרטיסייה הפעילה בחלון הנוכחי.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (zoomFactor: number) => void

    • zoomFactor

      number

      גורם הזום הנוכחי של הכרטיסייה.

החזרות

  • Promise<number>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

getZoomSettings()

Promise 
chrome.tabs.getZoomSettings(
  tabId?: number,
  callback?: function,
)

הפונקציה מקבלת את הגדרות הזום הנוכחיות של כרטיסייה מסוימת.

פרמטרים

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שממנה רוצים לקבל את הגדרות הזום הנוכחיות. ברירת המחדל היא הכרטיסייה הפעילה בחלון הנוכחי.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (zoomSettings: ZoomSettings) => void

    • zoomSettings

      ZoomSettings

      הגדרות הזום הנוכחיות של הכרטיסייה.

החזרות

  • Promise<ZoomSettings>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

goBack()

Promise Chrome מגרסה 72 ואילך 
chrome.tabs.goBack(
  tabId?: number,
  callback?: function,
)

חוזרים לדף הקודם, אם יש כזה.

פרמטרים

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שאליה רוצים לנווט חזרה. כברירת מחדל, הכרטיסייה שנבחרה בחלון הנוכחי.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

goForward()

Promise Chrome מגרסה 72 ואילך 
chrome.tabs.goForward(
  tabId?: number,
  callback?: function,
)

עוברים לדף הבא, אם יש כזה.

פרמטרים

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שרוצים לנווט אליה קדימה. כברירת מחדל, הכרטיסייה שנבחרה בחלון הנוכחי.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

group()

Promise Chrome מגרסה 88 ואילך 
chrome.tabs.group(
  options: object,
  callback?: function,
)

הוספת כרטיסייה אחת או יותר לקבוצה שצוינה. אם לא צוינה קבוצה, הוספת הכרטיסיות הנתונות לקבוצה חדשה שנוצרה.

פרמטרים

  • אפשרויות

    אובייקט

    • createProperties

      אובייקט אופציונלי

      הגדרות ליצירת קבוצה. לא ניתן להשתמש בו אם כבר צוין groupId.

      • windowId

        מספר אופציונלי

        החלון של הקבוצה החדשה. ברירת המחדל היא החלון הנוכחי.

    • groupId

      מספר אופציונלי

      המזהה של הקבוצה שאליה רוצים להוסיף את הכרטיסיות. אם לא מציינים קבוצה, המערכת תיצור קבוצה חדשה.

    • tabIds

      מספר | [מספר, ...מספר[]]

      מזהה הכרטיסייה או רשימת מזהי הכרטיסיות שרוצים להוסיף לקבוצה שצוינה.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (groupId: number) => void

    • groupId

      number

      המזהה של הקבוצה שאליה נוספו הכרטיסיות.

החזרות

  • Promise<number>

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

highlight()

Promise 
chrome.tabs.highlight(
  highlightInfo: object,
  callback?: function,
)

הדגשת הכרטיסיות הנתונות והתמקדות בכרטיסייה הראשונה בקבוצה. אם הכרטיסייה שצוינה פעילה כרגע, לא תתבצע פעולה כלשהי.

פרמטרים

  • highlightInfo

    אובייקט

    • כרטיסיות

      number | number[]

      אינדקס של כרטיסייה אחת או יותר שרוצים להדגיש.

    • windowId

      מספר אופציונלי

      החלון שמכיל את הכרטיסיות.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (window: Window) => void

    • חלון

      חלון

      מכיל פרטים על החלון שהכרטיסיות שלו הוצגו בצבעים מודגשים.

החזרות

  • Promise<windows.Window>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

insertCSS()

Promise &leq; MV2 הווצא משימוש החל מ-Chrome 91
chrome.tabs.insertCSS(
  tabId?: number,
  details: InjectDetails,
  callback?: function,
)

הוחלף על ידי scripting.insertCSS ב-Manifest V3.

הוספה של CSS לדף. אפשר להסיר סגנונות שהוכנסו באמצעות השיטה הזו באמצעות scripting.removeCSS. פרטים נוספים זמינים בקטע הזרקה פרוגרמטית במסמך בנושא סקריפטים של תוכן.

פרמטרים

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שבה רוצים להוסיף את ה-CSS. ברירת המחדל היא הכרטיסייה הפעילה בחלון הנוכחי.

  • פרטים

    InjectDetails

    פרטים של טקסט ה-CSS שרוצים להוסיף. צריך להגדיר את הקוד או את מאפיין הקובץ, אבל לא את שניהם בו-זמנית.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

move()

Promise 
chrome.tabs.move(
  tabIds: number | number[],
  moveProperties: object,
  callback?: function,
)

העברת כרטיסייה אחת או יותר למיקום חדש בחלון שלה, או לחלון חדש. שימו לב שאפשר להעביר כרטיסיות רק אל חלונות רגילים (window.type === "normal") ומהם.

פרמטרים

  • tabIds

    number | number[]

    מזהה הכרטיסייה או רשימת מזהי הכרטיסיות שרוצים להעביר.

  • moveProperties

    אובייקט

    • אינדקס

      number

      המיקום שאליו רוצים להעביר את החלון. מקישים על -1 כדי להציב את הכרטיסייה בסוף החלון.

    • windowId

      מספר אופציונלי

      ברירת המחדל היא החלון שבו הכרטיסייה נמצאת כרגע.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (tabs: Tab | Tab[]) => void

    • כרטיסיות

      Tab | Tab[]

      פרטים על הכרטיסיות שהועברו.

החזרות

  • Promise<Tab | Tab[]>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

query()

Promise 
chrome.tabs.query(
  queryInfo: object,
  callback?: function,
)

הפונקציה מקבלת את כל הכרטיסיות שיש להן את המאפיינים שצוינו, או את כל הכרטיסיות אם לא צוינו מאפיינים.

פרמטרים

  • queryInfo

    אובייקט

    • פעיל

      בוליאני אופציונלי

      אם הכרטיסיות פעילות בחלונות שלהן.

    • audible, אודיבל

      בוליאני אופציונלי

      Chrome מגרסה 45 ואילך

      אם הכרטיסיות נשמעות.

    • autoDiscardable

      בוליאני אופציונלי

      Chrome מגרסה 54 ואילך

      האם הדפדפן יכול לסגור את הכרטיסיות באופן אוטומטי כשהמשאבים מצומצמים.

    • currentWindow

      בוליאני אופציונלי

      אם הכרטיסיות נמצאות בחלון הנוכחי.

    • דחית את

      בוליאני אופציונלי

      Chrome מגרסה 54 ואילך

      אם הכרטיסיות יושמדו. כרטיסייה שהתוכן שלה הוצא מהזיכרון, אבל עדיין מוצגת בסרגל הכרטיסיות. התוכן שלו נטען מחדש בפעם הבאה שהוא מופעל.

    • קפוא

      בוליאני אופציונלי

      בהמתנה

      אם הכרטיסיות קפואות. כרטיסייה קפואה לא יכולה לבצע משימות, כולל טיפול באירועים או שעונים. היא מוצגת בסרגל הכרטיסיות והתוכן שלה נטען בזיכרון. הוא משוחרר מההקפאה בזמן ההפעלה.

    • groupId

      מספר אופציונלי

      גרסה 88 ואילך של Chrome

      המזהה של הקבוצה שבה נמצאות הכרטיסיות, או tabGroups.TAB_GROUP_ID_NONE לכרטיסיות שלא מקובצות בקבוצה.

    • מודגש

      בוליאני אופציונלי

      אם הכרטיסיות מודגשות.

    • אינדקס

      מספר אופציונלי

      המיקום של הכרטיסיות בחלונות שלהן.

    • lastFocusedWindow

      בוליאני אופציונלי

      אם הכרטיסיות נמצאות בחלון האחרון שהיה ממוקד.

    • הושתק

      בוליאני אופציונלי

      Chrome מגרסה 45 ואילך

      אם הכרטיסיות מושתקות.

    • מוצמד

      בוליאני אופציונלי

      אם הכרטיסיות מוצמדות.

    • status

      TabStatus אופציונלי

      סטטוס הטעינה של הכרטיסייה.

    • title

      מחרוזת אופציונלי

      התאמת כותרות דפים לתבנית. המערכת מתעלמת מהנכס הזה אם לתוסף אין את ההרשאה "tabs".

    • כתובת אתר

      string | string[] אופציונלי

      התאמת כרטיסיות לתבניות URL אחת או יותר. לא נמצאה התאמה למזהי הקטעים. המערכת מתעלמת מהנכס הזה אם לתוסף אין את ההרשאה "tabs".

    • windowId

      מספר אופציונלי

      המזהה של חלון ההורה, או windows.WINDOW_ID_CURRENT לחלון הנוכחי.

    • windowType

      WindowType אופציונלי

      סוג החלון שבו נמצאות הכרטיסיות.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (result: Tab[]) => void

    • תוצאה

      Tab[]

החזרות

  • Promise<Tab[]>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

reload()

Promise 
chrome.tabs.reload(
  tabId?: number,
  reloadProperties?: object,
  callback?: function,
)

טוענים מחדש את הכרטיסייה.

פרמטרים

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שרוצים לטעון מחדש. ברירת המחדל היא הכרטיסייה שנבחרה בחלון הנוכחי.

  • reloadProperties

    אובייקט אופציונלי

    • bypassCache

      בוליאני אופציונלי

      אם לעקוף את האחסון במטמון המקומי. ברירת המחדל היא false.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

remove()

Promise 
chrome.tabs.remove(
  tabIds: number | number[],
  callback?: function,
)

סגירת כרטיסייה אחת או יותר.

פרמטרים

  • tabIds

    number | number[]

    מזהה הכרטיסייה או רשימת מזהי הכרטיסיות שרוצים לסגור.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

removeCSS()

Promise Chrome מגרסה 87 ואילך &leq; MV2 הווצא משימוש החל מגרסה Chrome 91
chrome.tabs.removeCSS(
  tabId?: number,
  details: DeleteInjectionDetails,
  callback?: function,
)

הוחלף על ידי scripting.removeCSS ב-Manifest V3.

הסרת CSS מדף שהוחדר בעבר באמצעות קריאה ל-scripting.insertCSS.

פרמטרים

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שממנה רוצים להסיר את קובץ ה-CSS. ברירת המחדל היא הכרטיסייה הפעילה בחלון הנוכחי.

  • פרטים של טקסט ה-CSS שרוצים להסיר. צריך להגדיר את הקוד או את מאפיין הקובץ, אבל לא את שניהם בו-זמנית.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

sendMessage()

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

שליחת הודעה אחת לסקריפטים של התוכן בכרטיסייה שצוינה, עם קריאה חוזרת אופציונלית שתופעל כשהתשובה תישלח חזרה. האירוע runtime.onMessage מופעל בכל סקריפט תוכן שפועל בכרטיסייה שצוינה של התוסף הנוכחי.

פרמטרים

  • tabId

    number

  • הודעה

    כל

    ההודעה שרוצים לשלוח. ההודעה הזו צריכה להיות אובייקט שניתן להמיר ל-JSON.

  • אפשרויות

    אובייקט אופציונלי

    • documentId

      מחרוזת אופציונלי

      גרסה 106 ואילך של Chrome

      שליחת הודעה למסמך ספציפי שמזוהה באמצעות documentId במקום לכל המסגרות בכרטיסייה.

    • frameId

      מספר אופציונלי

      שליחת הודעה למסגרת ספציפית שזוהתה באמצעות frameId במקום לכל המסגרות בכרטיסייה.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    גרסה 99 ואילך של Chrome

    הפרמטר callback נראה כך: 

    (response: any) => void

    • תשובה

      כל

      אובייקט התגובה בפורמט JSON שנשלח על ידי הטיפול בהודעה. אם מתרחשת שגיאה במהלך החיבור לכרטיסייה שצוינה, פונקציית ה-callback נקראת ללא ארגומנטים ו-runtime.lastError מוגדר להודעת השגיאה.

החזרות

  • Promise<any>

    גרסה 99 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

sendRequest()

Promise &leq; MV2 Deprecated
chrome.tabs.sendRequest(
  tabId: number,
  request: any,
  callback?: function,
)

יש להשתמש ב-runtime.sendMessage.

שליחת בקשה אחת לסקריפטים של התוכן בכרטיסייה שצוינה, עם קריאה חוזרת אופציונלית שתופעל כשהתגובה תישלח חזרה. האירוע extension.onRequest מופעל בכל סקריפט תוכן שפועל בכרטיסייה שצוינה של התוסף הנוכחי.

פרמטרים

  • tabId

    number

  • בקשה

    כל

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    גרסה 99 ואילך של Chrome

    הפרמטר callback נראה כך: 

    (response: any) => void

    • תשובה

      כל

      אובייקט התגובה בפורמט JSON שנשלח על ידי הטיפול בבקשה. אם מתרחשת שגיאה במהלך החיבור לכרטיסייה שצוינה, פונקציית ה-callback נקראת ללא ארגומנטים ו-runtime.lastError מוגדר להודעת השגיאה.

החזרות

  • Promise<any>

    גרסה 99 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

setZoom()

Promise 
chrome.tabs.setZoom(
  tabId?: number,
  zoomFactor: number,
  callback?: function,
)

שינוי מרחק התצוגה בכרטיסייה ספציפית.

פרמטרים

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שרוצים להגדיל. ברירת המחדל היא הכרטיסייה הפעילה בחלון הנוכחי.

  • zoomFactor

    number

    גורם הזום החדש. הערך 0 מגדיר את פקטור הזום הנוכחי של ברירת המחדל בכרטיסייה. ערכים גדולים מ-0 מציינים פקטור זום (שעשוי להיות שונה מברירת המחדל) לכרטיסייה.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

setZoomSettings()

Promise 
chrome.tabs.setZoomSettings(
  tabId?: number,
  zoomSettings: ZoomSettings,
  callback?: function,
)

הגדרת הגדרות הזום בכרטיסייה מסוימת, שמגדירות את אופן הטיפול בשינויי זום. ההגדרות האלה מתאפסות לברירת המחדל כשמנווטים בכרטיסייה.

פרמטרים

  • tabId

    מספר אופציונלי

    המזהה של הכרטיסייה שעבורה רוצים לשנות את הגדרות הזום. ברירת המחדל היא הכרטיסייה הפעילה בחלון הנוכחי.

  • zoomSettings

    ZoomSettings

    הגדרת האופן שבו מטפלים בשינויים בהגדלת התצוגה ובהיקף שלהם.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

ungroup()

Promise Chrome מגרסה 88 ואילך 
chrome.tabs.ungroup(
  tabIds: number | [number, ...number[]],
  callback?: function,
)

הסרת כרטיסייה אחת או יותר מהקבוצות הרלוונטיות. אם קבוצה מסוימת תהיה ריקה, היא תימחק.

פרמטרים

  • tabIds

    מספר | [מספר, ...מספר[]]

    מזהה הכרטיסייה או רשימת מזהי הכרטיסיות שרוצים להסיר מהקבוצות הרלוונטיות.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    () => void

החזרות

  • Promise<void>

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

update()

Promise 
chrome.tabs.update(
  tabId?: number,
  updateProperties: object,
  callback?: function,
)

שינוי המאפיינים של כרטיסייה. מאפיינים שלא צוינו ב-updateProperties לא ישתנו.

פרמטרים

  • tabId

    מספר אופציונלי

    ברירת המחדל היא הכרטיסייה שנבחרה בחלון הנוכחי.

  • updateProperties

    אובייקט

    • פעיל

      בוליאני אופציונלי

      האם הכרטיסייה צריכה להיות פעילה. לא משפיעה על המיקוד בחלון (ראו windows.update).

    • autoDiscardable

      בוליאני אופציונלי

      Chrome מגרסה 54 ואילך

      האם הדפדפן צריך לסגור את הכרטיסייה באופן אוטומטי כשהמשאבים מצומצמים.

    • מודגש

      בוליאני אופציונלי

      הוספה או הסרה של הכרטיסייה מהבחירה הנוכחית.

    • הושתק

      בוליאני אופציונלי

      Chrome מגרסה 45 ואילך

      האם להשתיק את הכרטיסייה.

    • openerTabId

      מספר אופציונלי

      המזהה של הכרטיסייה שדרכה נפתחה הכרטיסייה הזו. אם מצוין כרטיסייה פתיחה, היא חייבת להיות באותו חלון כמו הכרטיסייה הזו.

    • מוצמד

      בוליאני אופציונלי

      האם הכרטיסייה צריכה להיות מוצמדת.

    • נבחר

      בוליאני אופציונלי

      הוצא משימוש

      יש להשתמש בהקטעים המודגשים.

      האם הכרטיסייה צריכה להיות מסומנת.

    • כתובת אתר

      מחרוזת אופציונלי

      כתובת URL שאליה רוצים לנווט בכרטיסייה. אין תמיכה בכתובות URL של JavaScript. במקום זאת, צריך להשתמש ב-scripting.executeScript.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (tab?: Tab) => void

    • כרטיסייה

      Tab אופציונלי

      פרטים על הכרטיסייה המעודכנת. האובייקט tabs.Tab לא מכיל את הערכים url,‏ pendingUrl,‏ title ו-favIconUrl אם לא נשלחה בקשה להרשאה "tabs".

החזרות

  • Promise<Tab | undefined>

    גרסה 88 ואילך של Chrome

    יש תמיכה ב-Promises ב-Manifest V3 ואילך, אבל פונקציות קריאה חוזרת (callbacks) ניתנות לצורך תאימות לאחור. אי אפשר להשתמש בשניהם באותה קריאה לפונקציה. הפתרון של ההבטחה יהיה באותו סוג שהוענק ל-callback.

אירועים

onActivated

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

האירוע מופעל כשהכרטיסייה הפעילה בחלון משתנה. שימו לב: יכול להיות שכתובת ה-URL של הכרטיסייה לא תוגדר בזמן שהאירוע הזה יופעל, אבל אפשר להאזין לאירועים מסוג onUpdated כדי לקבל התראה כשכתובת URL מוגדרת.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

    (activeInfo: object) => void

    • activeInfo

      אובייקט

      • tabId

        number

        המזהה של הכרטיסייה שהפכה לפעילה.

      • windowId

        number

        המזהה של החלון שבו הכרטיסייה הפעילה השתנתה.

onActiveChanged

&leq; MV2 הווצא משימוש
chrome.tabs.onActiveChanged.addListener(
  callback: function,
)

יש להשתמש ב-tabs.onActivated.

האירוע מופעל כשהכרטיסייה שנבחרה בחלון משתנה. שימו לב: יכול להיות שכתובת ה-URL של הכרטיסייה לא תוגדר בזמן שהאירוע הזה יופעל, אבל אפשר להאזין לאירועים מסוג tabs.onUpdated כדי לקבל התראה כשכתובת URL מוגדרת.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

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

    • tabId

      number

    • selectInfo

      אובייקט

      • windowId

        number

        המזהה של החלון שבו הכרטיסייה שנבחרה השתנתה.

onAttached

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

האירוע מופעל כשכרטיסייה מצורפת לחלון, למשל כי היא הועברה בין חלונות.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

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

    • tabId

      number

    • attachInfo

      אובייקט

      • newPosition

        number

      • newWindowId

        number

onCreated

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

האירוע מופעל כשיוצרים כרטיסייה. שימו לב: יכול להיות שהכתובת של הכרטיסייה וההשתייכות לקבוצת הכרטיסיות לא יוגדרו בזמן שהאירוע הזה יופעל, אבל תוכלו להאזין לאירועים מסוג onUpdated כדי לקבל התראה כשכתובת URL מוגדרת או שהכרטיסייה נוספת לקבוצת כרטיסיות.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

    (tab: Tab) => void

onDetached

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

האירוע מופעל כשכרטיסייה מנותקת מחלון, למשל כי היא הועברה בין חלונות.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

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

    • tabId

      number

    • detachInfo

      אובייקט

      • oldPosition

        number

      • oldWindowId

        number

onHighlightChanged

&leq; MV2 הווצא משימוש
chrome.tabs.onHighlightChanged.addListener(
  callback: function,
)

יש להשתמש ב-tabs.onHighlighted.

האירוע מופעל כשהכרטיסיות המודגשות או שנבחרו בחלון משתנות.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

    (selectInfo: object) => void

    • selectInfo

      אובייקט

      • tabIds

        number[]

        כל הכרטיסיות המודגשות בחלון.

      • windowId

        number

        החלון שהכרטיסיות שלו השתנו.

onHighlighted

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

האירוע מופעל כשהכרטיסיות המודגשות או שנבחרו בחלון משתנות.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

    (highlightInfo: object) => void

    • highlightInfo

      אובייקט

      • tabIds

        number[]

        כל הכרטיסיות המודגשות בחלון.

      • windowId

        number

        החלון שהכרטיסיות שלו השתנו.

onMoved

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

האירוע מופעל כשכרטיסייה מועברת בתוך חלון. מתבצע רק אירוע תנועה אחד, שמייצג את הכרטיסייה שהמשתמש העביר ישירות. אירועי ההעברה לא מופעלים בכרטיסיות האחרות שצריכות לזוז בתגובה לכרטיסייה שהועברה באופן ידני. האירוע הזה לא מופעל כשכרטיסייה מועברת בין חלונות. פרטים נוספים זמינים בקטע tabs.onDetached.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

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

    • tabId

      number

    • moveInfo

      אובייקט

      • fromIndex

        number

      • toIndex

        number

      • windowId

        number

onRemoved

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

האירוע מופעל כשכרטיסייה נסגרת.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

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

    • tabId

      number

    • removeInfo

      אובייקט

      • isWindowClosing

        בוליאני

        הערך True מופיע כשהכרטיסייה נסגרה כי החלון ההורה שלה נסגר.

      • windowId

        number

        החלון שהכרטיסייה שלו סגורה.

onReplaced

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

האירוע הזה מופעל כשכרטיסייה מוחלפת בכרטיסייה אחרת בגלל עיבוד מראש או טעינה מיידית.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

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

    • addedTabId

      number

    • removedTabId

      number

onSelectionChanged

&leq; MV2 הווצא משימוש
chrome.tabs.onSelectionChanged.addListener(
  callback: function,
)

יש להשתמש ב-tabs.onActivated.

האירוע מופעל כשהכרטיסייה שנבחרה בחלון משתנה.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

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

    • tabId

      number

    • selectInfo

      אובייקט

      • windowId

        number

        המזהה של החלון שבו הכרטיסייה שנבחרה השתנתה.

onUpdated

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

האירוע מופעל כשכרטיסייה מתעדכנת.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

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

    • tabId

      number

    • changeInfo

      אובייקט

      • audible, אודיבל

        בוליאני אופציונלי

        Chrome מגרסה 45 ואילך

        מצב האודיו החדש של הכרטיסייה.

      • autoDiscardable

        בוליאני אופציונלי

        Chrome מגרסה 54 ואילך

        המצב החדש של הכרטיסייה שאפשר להשליך באופן אוטומטי.

      • דחית את

        בוליאני אופציונלי

        Chrome מגרסה 54 ואילך

        המצב החדש של הכרטיסייה שהושמטה.

      • favIconUrl

        מחרוזת אופציונלי

        כתובת ה-URL החדשה של סמל האתר בכרטיסייה.

      • קפוא

        בוליאני אופציונלי

        בהמתנה

        המצב החדש של הכרטיסייה המושהית.

      • groupId

        מספר אופציונלי

        גרסה 88 ואילך של Chrome

        הקבוצה החדשה של הכרטיסייה.

      • mutedInfo

        MutedInfo אופציונלי

        Chrome מגרסה 46 ואילך

        מצב ההשתקה החדש של הכרטיסייה והסיבה לשינוי.

      • מוצמד

        בוליאני אופציונלי

        המצב החדש של הכרטיסייה המוצמדת.

      • status

        TabStatus אופציונלי

        סטטוס הטעינה של הכרטיסייה.

      • title

        מחרוזת אופציונלי

        Chrome מגרסה 48 ואילך

        השם החדש של הכרטיסייה.

      • כתובת אתר

        מחרוזת אופציונלי

        כתובת ה-URL של הכרטיסייה, אם היא השתנתה.

    • כרטיסייה

      מקש Tab

onZoomChange

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

האירוע מופעל כשמתבצעת הגדלה של כרטיסייה.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

    (ZoomChangeInfo: object) => void

    • ZoomChangeInfo

      אובייקט

      • newZoomFactor

        number

      • oldZoomFactor

        number

      • tabId

        number

      • zoomSettings

        ZoomSettings