דף זה תורגם על ידי Cloud Translation API.

chrome.tabs

תיאור

משתמשים ב-chrome.tabs API כדי ליצור אינטראקציה עם מערכת הכרטיסיות של הדפדפן. אתם יכולים להשתמש ב-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(),‏ scripting.executeScript(),‏ scripting.insertCSS() ו-scripting.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

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

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

בוליאני

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

‫MutedInfoReason אופציונלי

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

MutedInfoReason

‫Chrome 46 ואילך

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

ספירה

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

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

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

Tab

מאפיינים

פעיל

בוליאני

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

‫boolean אופציונלי

‫Chrome 45 ואילך

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

בוליאני

‫Chrome 54 ואילך

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

בוליאני

‫Chrome 54 ואילך

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

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

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

בוליאני

‫Chrome 132 ואילך

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

number

‫Chrome 88 ואילך

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

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

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

בוליאני

אם הכרטיסייה מודגשת.
id [מזהה]

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

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

בוליאני

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

number

האינדקס של הכרטיסייה בחלון שלה, כשהספירה מתחילה מ-0.
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 האחרונה שבוצעה לגביה פעולת commit של המסגרת הראשית בכרטיסייה. המאפיין הזה מופיע רק אם לתוסף יש הרשאה "tabs" או הרשאות מארח לדף. יכול להיות מחרוזת ריקה אם הכרטיסייה עדיין לא בוצעה. מידע נוסף מופיע במאמר Tab.pendingUrl.
רוחב

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

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

number

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

TabStatus

‫Chrome 44 ואילך

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

ספירה

‫"unloaded"

"loading"

‫'complete'

WindowType

‫Chrome 44 ואילך

סוג החלון.

ספירה

"normal"

‫"popup"

‫"panel"

‫"app"

"devtools"

ZoomSettings

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

מאפיינים

defaultZoomFactor

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

‫Chrome 43 ואילך

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

‫ZoomSettingsMode אופציונלי

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

‫ZoomSettingsScope אופציונלי

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

ZoomSettingsMode

‫Chrome 44 ואילך

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

ספירה

‫automatic
שינויי הזום מטופלים אוטומטית על ידי הדפדפן.

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

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

ZoomSettingsScope

‫Chrome 44 ואילך

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

ספירה

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

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

מאפיינים

MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND

‫Chrome 92 ואילך

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

ערך

TAB_ID_NONE

‫Chrome 46 ואילך

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

ערך

-1

TAB_INDEX_NONE

‫Chrome 123 ואילך

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

ערך

-1

Methods

captureVisibleTab()

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

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

פרמטרים

windowId

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

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

‫ImageDetails אופציונלי

החזרות

Promise<string>

‫Chrome 88 ואילך

connect()

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

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

פרמטרים

tabId

number
connectInfo

אובייקט אופציונלי
- documentId
  
  מחרוזת אופציונלי
  
  ‫Chrome 106 ואילך
  
  פתיחת יציאה למסמך ספציפי שמזוהה על ידי documentId במקום כל המסגרות בכרטיסייה.
- frameId
  
  מספר אופציונלי
  
  פתיחת יציאה למסגרת ספציפית שמזוהה על ידי frameId במקום לכל המסגרות בכרטיסייה.
- שם
  
  מחרוזת אופציונלי
  
  מועבר אל onConnect עבור סקריפטים של תוכן שמקשיבים לאירוע החיבור.

החזרות

runtime.Port

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

create()

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

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

פרמטרים

createProperties

אובייקט
- פעיל
  
  ‫boolean אופציונלי
  
  האם הכרטיסייה צריכה להפוך לכרטיסייה הפעילה בחלון. ההגדרה לא משפיעה על המיקוד בחלון (ראו windows.update). ברירת המחדל היא true.
- אינדקס
  
  מספר אופציונלי
  
  המיקום של הכרטיסייה בחלון. הערך שצוין מוגבל לטווח שבין אפס למספר הכרטיסיות בחלון.
- openerTabId
  
  מספר אופציונלי
  
  המזהה של הכרטיסייה שפתחה את הכרטיסייה הזו. אם מציינים כרטיסייה, היא צריכה להיות באותו חלון כמו הכרטיסייה החדשה שנוצרה.
- מוצמד
  
  ‫boolean אופציונלי
  
  האם להצמיד את הכרטיסייה. ברירת המחדל היא false
- נבחר
  
  ‫boolean אופציונלי
  
  הוצא משימוש
  
  צריך להשתמש בערך active.
  האם הכרטיסייה צריכה להפוך לכרטיסייה שנבחרה בחלון. ברירת המחדל היא true
- כתובת אתר
  
  מחרוזת אופציונלי
  
  כתובת ה-URL שאליה הכרטיסייה תנווט בהתחלה. כתובות URL שמוגדרות במלואן חייבות לכלול סכימה (כלומר, ‫'http://www.google.com', ולא 'www.google.com'). כתובות URL יחסיות הן יחסיות לדף הנוכחי בתוך התוסף. ברירת המחדל היא הדף 'כרטיסייה חדשה'.
- windowId
  
  מספר אופציונלי
  
  החלון שבו ליצור את הכרטיסייה החדשה. ברירת המחדל היא החלון הנוכחי.

החזרות

Promise<Tab>

‫Chrome 88 ואילך

detectLanguage()

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

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

פרמטרים

tabId

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

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

החזרות

Promise<string>

‫Chrome 88 ואילך

discard()

‫Chrome 54 ואילך

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

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

פרמטרים

tabId

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

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

החזרות

Promise<Tab | undefined>

‫Chrome 88 ואילך

duplicate()

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

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

פרמטרים

tabId

number

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

החזרות

Promise<Tab | undefined>

‫Chrome 88 ואילך

get()

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

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

פרמטרים

tabId

number

החזרות

Promise<Tab>

‫Chrome 88 ואילך

getCurrent()

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

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

החזרות

Promise<Tab | undefined>

‫Chrome 88 ואילך

getZoom()

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

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

פרמטרים

tabId

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

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

החזרות

Promise<number>

‫Chrome 88 ואילך

getZoomSettings()

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

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

פרמטרים

tabId

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

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

החזרות

Promise<ZoomSettings>

‫Chrome 88 ואילך

goBack()

‫Chrome 72 ואילך

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

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

פרמטרים

tabId

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

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

החזרות

Promise<void>

‫Chrome 88 ואילך

goForward()

‫Chrome 72 ואילך

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

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

פרמטרים

tabId

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

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

החזרות

Promise<void>

‫Chrome 88 ואילך

group()

‫Chrome 88 ואילך

chrome.tabs.group(
  options: object,
): Promise<number>

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

פרמטרים

options

אובייקט
- createProperties
  
  אובייקט אופציונלי
  
  הגדרות ליצירת קבוצה. אי אפשר להשתמש בפרמטר הזה אם כבר צוין groupId.
  - windowId
    
    מספר אופציונלי
    
    החלון של הקבוצה החדשה. ברירת המחדל היא החלון הנוכחי.
- groupId
  
  מספר אופציונלי
  
  המזהה של הקבוצה שאליה רוצים להוסיף את הכרטיסיות. אם לא מציינים קבוצה, המערכת תיצור קבוצה חדשה.
- tabIds
  
  number | [number, ...number[]]
  
  מזהה הכרטיסייה או רשימה של מזהי כרטיסיות שרוצים להוסיף לקבוצה שצוינה.

החזרות

Promise<number>

highlight()

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

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

פרמטרים

highlightInfo

אובייקט
- כרטיסיות
  
  number | number[]
  
  אינדקסים של כרטיסייה אחת או יותר להדגשה.
- windowId
  
  מספר אופציונלי
  
  החלון שמכיל את הכרטיסיות.

החזרות

Promise<windows.Window>

‫Chrome 88 ואילך

move()

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

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

פרמטרים

tabIds

number | number[]

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

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

החזרות

‫Promise<Tab | Tab[]>

‫Chrome 88 ואילך

query()

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

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

פרמטרים

queryInfo

אובייקט
- פעיל
  
  ‫boolean אופציונלי
  
  האם הכרטיסיות פעילות בחלונות שלהן.
- audible, אודיבל
  
  ‫boolean אופציונלי
  
  ‫Chrome 45 ואילך
  
  אם הכרטיסיות משמיעות צליל.
- autoDiscardable
  
  ‫boolean אופציונלי
  
  ‫Chrome 54 ואילך
  
  האם הדפדפן יכול לסגור את הכרטיסיות באופן אוטומטי כשאין מספיק משאבים.
- currentWindow
  
  ‫boolean אופציונלי
  
  אם הכרטיסיות נמצאות בחלון הנוכחי.
- דחית את
  
  ‫boolean אופציונלי
  
  ‫Chrome 54 ואילך
  
  אם הכרטיסיות נסגרות. כרטיסייה שהוצאה מהזיכרון היא כרטיסייה שהתוכן שלה לא נטען מהזיכרון, אבל היא עדיין מוצגת בשורת הכרטיסיות. התוכן שלו נטען מחדש בפעם הבאה שהוא מופעל.
- קפוא
  
  ‫boolean אופציונלי
  
  ‫Chrome 132 ואילך
  
  אם הכרטיסיות מוקפאות. כרטיסייה מוקפאת לא יכולה לבצע משימות, כולל גורמים שמטפלים באירועים או טיימרים. היא גלויה בסרגל הכרטיסיות והתוכן שלה נטען בזיכרון. הוא יבוטל בהפעלה.
- groupId
  
  מספר אופציונלי
  
  ‫Chrome 88 ואילך
  
  המזהה של הקבוצה שהכרטיסיות נמצאות בה, או tabGroups.TAB_GROUP_ID_NONE אם הכרטיסיות לא מקובצות.
- מודגש
  
  ‫boolean אופציונלי
  
  אם הכרטיסיות מודגשות.
- אינדקס
  
  מספר אופציונלי
  
  המיקום של הכרטיסיות בחלונות שלהן.
- lastFocusedWindow
  
  ‫boolean אופציונלי
  
  האם הכרטיסיות נמצאות בחלון האחרון שהיה ממוקד.
- הושתק
  
  ‫boolean אופציונלי
  
  ‫Chrome 45 ואילך
  
  אם הכרטיסיות מושתקות.
- מוצמד
  
  ‫boolean אופציונלי
  
  אם הכרטיסיות מוצמדות.
- splitViewId
  
  מספר אופציונלי
  
  ‫Chrome 140+‎
  
  ה-ID של התצוגה המפוצלת שבה הכרטיסיות נמצאות, או tabs.SPLIT_VIEW_ID_NONE אם הכרטיסיות לא נמצאות בתצוגה מפוצלת.
- status
  
  ‫TabStatus אופציונלי
  
  סטטוס הטעינה של הכרטיסייה.
- title
  
  מחרוזת אופציונלי
  
  התאמה של כותרות דפים לתבנית. המערכת מתעלמת מהמאפיין הזה אם לתוסף אין הרשאת "tabs" או הרשאות מארח לדף.
- כתובת אתר
  
  מחרוזת | מערך של מחרוזות אופציונלי
  
  התאמת כרטיסיות לאחת או יותר תבניות של כתובות URL. לא נמצאה התאמה למזהי קטעים. המערכת מתעלמת מהמאפיין הזה אם לתוסף אין הרשאת "tabs" או הרשאות מארח לדף.
- windowId
  
  מספר אופציונלי
  
  המזהה של חלון ההורה, או windows.WINDOW_ID_CURRENT בשביל החלון הנוכחי.
- windowType
  
  ‫WindowType אופציונלי
  
  סוג החלון שבו הכרטיסיות נמצאות.

החזרות

Promise<Tab[]>

‫Chrome 88 ואילך

reload()

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

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

פרמטרים

tabId

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

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

אובייקט אופציונלי
- bypassCache
  
  ‫boolean אופציונלי
  
  האם לעקוף את השמירה במטמון המקומי. ברירת המחדל היא false.

החזרות

Promise<void>

‫Chrome 88 ואילך

remove()

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

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

פרמטרים

tabIds

number | number[]

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

החזרות

Promise<void>

‫Chrome 88 ואילך

sendMessage()

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

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

פרמטרים

tabId

number
הודעה

כל

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

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

החזרות

Promise<any>

‫Chrome 99 ואילך

setZoom()

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

הגדלה של כרטיסייה ספציפית.

פרמטרים

tabId

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

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

number

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

החזרות

Promise<void>

‫Chrome 88 ואילך

setZoomSettings()

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

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

פרמטרים

tabId

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

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

ZoomSettings

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

החזרות

Promise<void>

‫Chrome 88 ואילך

ungroup()

‫Chrome 88 ואילך

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

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

פרמטרים

tabIds

number | [number, ...number[]]

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

החזרות

Promise<void>

update()

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

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

פרמטרים

tabId

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

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

אובייקט
- פעיל
  
  ‫boolean אופציונלי
  
  האם הכרטיסייה צריכה להיות פעילה. היא לא משפיעה על המיקוד בחלון (ראו windows.update).
- autoDiscardable
  
  ‫boolean אופציונלי
  
  ‫Chrome 54 ואילך
  
  ההגדרה קובעת אם הדפדפן צריך להשליך את הכרטיסייה באופן אוטומטי כשאין מספיק משאבים.
- מודגש
  
  ‫boolean אופציונלי
  
  הוספה או הסרה של הכרטיסייה מהבחירה הנוכחית.
- הושתק
  
  ‫boolean אופציונלי
  
  ‫Chrome 45 ואילך
  
  האם להשתיק את הכרטיסייה.
- openerTabId
  
  מספר אופציונלי
  
  המזהה של הכרטיסייה שפתחה את הכרטיסייה הזו. אם מציינים את זה, כרטיסיית הפתיחה צריכה להיות באותו חלון כמו הכרטיסייה הזו.
- מוצמד
  
  ‫boolean אופציונלי
  
  האם להצמיד את הכרטיסייה.
- נבחר
  
  ‫boolean אופציונלי
  
  הוצא משימוש
  
  צריך להשתמש בהדגשה.
  האם הכרטיסייה צריכה להיות מסומנת.
- כתובת אתר
  
  מחרוזת אופציונלי
  
  כתובת URL שאליה הכרטיסייה תנווט. אין תמיכה בכתובות URL של JavaScript. במקום זאת, צריך להשתמש ב-scripting.executeScript.

החזרות

Promise<Tab | undefined>

‫Chrome 88 ואילך

אירועים

onActivated

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

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

פרמטרים

callback

פונקציה

הפרמטר callback נראה כך:
```
(activeInfo: object) => void
```
- activeInfo
  
  אובייקט
  - tabId
    
    number
    
    המזהה של הכרטיסייה שהפכה לפעילה.
  - 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,
)

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

פרמטרים

callback

פונקציה

הפרמטר callback נראה כך:
```
(tab: Tab) => void
```
- כרטיסייה
  
  Tab

onDetached

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

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

פרמטרים

callback

פונקציה

הפרמטר callback נראה כך:
```
(tabId: number, detachInfo: object) => void
```
- tabId
  
  number
- detachInfo
  
  אובייקט
  - oldPosition
    
    number
  - oldWindowId
    
    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

onUpdated

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

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

פרמטרים

callback

פונקציה

הפרמטר callback נראה כך:
```
(tabId: number, changeInfo: object, tab: Tab) => void
```
- tabId
  
  number
- changeInfo
  
  אובייקט
  - audible, אודיבל
    
    ‫boolean אופציונלי
    
    ‫Chrome 45 ואילך
    
    המצב החדש של האודיו בכרטיסייה.
  - autoDiscardable
    
    ‫boolean אופציונלי
    
    ‫Chrome 54 ואילך
    
    המצב החדש של הכרטיסייה שניתן להסרה אוטומטית.
  - דחית את
    
    ‫boolean אופציונלי
    
    ‫Chrome 54 ואילך
    
    המצב החדש של הכרטיסייה אחרי ההסרה.
  - favIconUrl
    
    מחרוזת אופציונלי
    
    כתובת ה-URL החדשה של סמל האתר בכרטיסייה.
  - קפוא
    
    ‫boolean אופציונלי
    
    ‫Chrome 132 ואילך
    
    הסטטוס החדש של הכרטיסייה שהוקפאה.
  - groupId
    
    מספר אופציונלי
    
    ‫Chrome 88 ואילך
    
    הקבוצה החדשה של הכרטיסייה.
  - mutedInfo
    
    MutedInfo אופציונלי
    
    ‫Chrome 46 ואילך
    
    הסטטוס החדש של הכרטיסייה (השתקה) והסיבה לשינוי.
  - מוצמד
    
    ‫boolean אופציונלי
    
    המצב החדש של הכרטיסייה המוצמדת.
  - splitViewId
    
    מספר אופציונלי
    
    ‫Chrome 140+‎
    
    התצוגה המפוצלת החדשה של הכרטיסייה.
  - 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

chrome.tabs קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

תיאור

הרשאות

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

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

קבלת הכרטיסייה הנוכחית

השתקת הכרטיסייה שצוינה

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

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

דוגמאות לתוספים

סוגים

MutedInfo

מאפיינים

MutedInfoReason

ספירה

Tab

מאפיינים

TabStatus

ספירה

WindowType

ספירה

ZoomSettings

מאפיינים

ZoomSettingsMode

ספירה

ZoomSettingsScope

ספירה

מאפיינים

MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND

ערך

TAB_ID_NONE

ערך

TAB_INDEX_NONE

ערך

Methods

captureVisibleTab()

פרמטרים

החזרות

connect()

פרמטרים

החזרות

create()

פרמטרים

החזרות

detectLanguage()

פרמטרים

החזרות

discard()

פרמטרים

החזרות

duplicate()

פרמטרים

החזרות

get()

פרמטרים

החזרות

getCurrent()

החזרות

getZoom()

פרמטרים

החזרות

getZoomSettings()

פרמטרים

החזרות

goBack()

פרמטרים

החזרות

goForward()

פרמטרים

החזרות

group()

פרמטרים

החזרות

highlight()

פרמטרים

החזרות

move()

פרמטרים

החזרות

query()

chrome.tabs