תיאור
משתמשים ב-chrome.tabs API כדי ליצור אינטראקציה עם מערכת הכרטיסיות של הדפדפן. אתם יכולים להשתמש ב-API הזה כדי ליצור, לשנות ולסדר מחדש כרטיסיות בדפדפן.
Tabs API לא רק מציע תכונות לשינוי ולניהול של כרטיסיות, אלא גם יכול לזהות את השפה של הכרטיסייה, לצלם צילום מסך ולתקשר עם סקריפטים של תוכן בכרטיסייה.
הרשאות
כדי להשתמש ברוב התכונות לא נדרשות הרשאות. לדוגמה: יצירת כרטיסייה חדשה, טעינה מחדש של כרטיסייה, מעבר לכתובת URL אחרת וכו'.
יש שלוש הרשאות שמפתחים צריכים להכיר כשהם עובדים עם Tabs API.
- ההרשאה 'כרטיסיות'
ההרשאה הזו לא נותנת גישה למרחב השמות
browser.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:
browser.runtime.onInstalled.addListener(({reason}) => {
if (reason === 'install') {
browser.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 browser.tabs.query(queryOptions);
return tab;
}
function getCurrentTab(callback) {
let queryOptions = { active: true, lastFocusedWindow: true };
browser.tabs.query(queryOptions, ([tab]) => {
if (browser.runtime.lastError)
console.error(browser.runtime.lastError);
// `tab` will either be a `tabs.Tab` instance or `undefined`.
callback(tab);
});
}
השתקת הכרטיסייה שצוינה
בדוגמה הזו מוצג איך תוסף יכול להפעיל או להשבית את ההשתקה של כרטיסייה מסוימת.
async function toggleMuteState(tabId) {
const tab = await browser.tabs.get(tabId);
const muted = !tab.mutedInfo.muted;
await browser.tabs.update(tabId, {muted});
console.log(`Tab ${tab.id} is ${muted ? "muted" : "unmuted"}`);
}
function toggleMuteState(tabId) {
browser.tabs.get(tabId, async (tab) => {
let muted = !tab.mutedInfo.muted;
await browser.tabs.update(tabId, { muted });
console.log(`Tab ${tab.id} is ${ muted ? "muted" : "unmuted" }`);
});
}
העברת הכרטיסייה הנוכחית למיקום הראשון בלחיצה
בדוגמה הזו מוצג איך להעביר כרטיסייה בזמן שפעולת הגרירה מתבצעת או לא מתבצעת. בדוגמה הזו נעשה שימוש ב-browser.tabs.move, אבל אפשר להשתמש באותו דפוס המתנה גם לקריאות אחרות שמשנות כרטיסיות בזמן שמתבצע גרירה.
browser.tabs.onActivated.addListener(moveToFirstPosition);
async function moveToFirstPosition(activeInfo) {
try {
await browser.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);
}
}
}
browser.tabs.onActivated.addListener(moveToFirstPositionMV2);
function moveToFirstPositionMV2(activeInfo) {
browser.tabs.move(activeInfo.tabId, { index: 0 }, () => {
if (browser.runtime.lastError) {
const error = browser.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 browser.tabs.query({ active: true, lastFocusedWindow: true });
const response = await browser.tabs.sendMessage(tab.id, message);
// TODO: Do something with the response.
}
דוגמאות לתוספים
דוגמאות נוספות לתוספים של Tabs API זמינות במקורות הבאים:
סוגים
MutedInfo
האם הכרטיסייה מושתקת והסיבה לשינוי האחרון במצב שלה.
מאפיינים
-
extensionId
מחרוזת אופציונלי
המזהה של התוסף ששינה את מצב ההשתקה. הערך לא מוגדר אם התוסף לא היה הסיבה לשינוי האחרון של מצב ההשתקה.
-
מושתק
בוליאני
האם הכרטיסייה מושתקת (ההפעלה של הצליל נמנעת). יכול להיות שהכרטיסייה מושתקת גם אם לא הושמע בה צליל או אם לא מושמע בה צליל כרגע. מקביל לכך שמוצג אינדיקטור האודיו 'מושתק'.
-
reason
MutedInfoReason אופציונלי
הסיבה להשתקה או לביטול ההשתקה של הכרטיסייה. הערך לא מוגדר אם מצב ההשתקה של הכרטיסייה לא השתנה אף פעם.
MutedInfoReason
אירוע שגרם לשינוי במצב ההשתקה.
ספירה
user
פעולת קלט של משתמש הגדירה את מצב ההשתקה.
capture
התחיל צילום של הכרטיסייה, ולכן הופעל שינוי למצב מושתק.
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 ואילךהפעם האחרונה שהכרטיסייה הפכה לפעילה בחלון שלה, כמספר אלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch).
-
mutedInfo
MutedInfo אופציונלי
Chrome 46 ואילךהאם הכרטיסייה מושתקת והסיבה לשינוי האחרון במצב שלה.
-
openerTabId
מספר אופציונלי
המזהה של הכרטיסייה שפתחה את הכרטיסייה הזו, אם יש כזו. המאפיין הזה קיים רק אם הכרטיסייה שממנה נפתח החלון עדיין קיימת.
-
pendingUrl
מחרוזת אופציונלי
Chrome 79 ואילךכתובת ה-URL שאליה הכרטיסייה עוברת, לפני שהיא מאשרת את המעבר. המאפיין הזה מופיע רק אם לתוסף יש הרשאה
"tabs"או הרשאות מארח לדף, ויש ניווט בהמתנה. -
מוצמד
בוליאני
האם הכרטיסייה מוצמדת.
-
נבחר
בוליאני
הוצא משימושצריך להשתמש ב-
tabs.Tab.highlighted.האם הכרטיסייה נבחרה.
-
sessionId
מחרוזת אופציונלי
מזהה הסשן שמשמש לזיהוי ייחודי של כרטיסייה שהתקבלה מ-API
sessions. -
splitViewId
מספר אופציונלי
Chrome 140+המזהה של התצוגה המפוצלת שאליה שייכת הכרטיסייה.
-
status
TabStatus אופציונלי
סטטוס הטעינה של הכרטיסייה.
-
title
מחרוזת אופציונלי
השם של הכרטיסייה. המאפיין הזה מופיע רק אם לתוסף יש הרשאה
"tabs"או הרשאות מארח לדף. -
url
מחרוזת אופציונלי
כתובת ה-URL האחרונה שבוצעה לגביה פעולת commit בפריים הראשי של הכרטיסייה. המאפיין הזה מופיע רק אם לתוסף יש הרשאה
"tabs"או הרשאות מארח לדף. יכול להיות מחרוזת ריקה אם הכרטיסייה עדיין לא בוצעה. מידע נוסף מופיע במאמרTab.pendingUrl. -
רוחב
מספר אופציונלי
רוחב הכרטיסייה בפיקסלים.
-
windowId
number
המזהה של החלון שמכיל את הכרטיסייה.
TabStatus
סטטוס הטעינה של הכרטיסייה.
ספירה
"unloaded"
"loading"
'complete'
WindowType
סוג החלון.
ספירה
"normal"
"popup"
"panel"
"app"
"devtools"
ZoomSettings
ההגדרה קובעת איך שינויים בזום בכרטיסייה מטופלים ובאיזה היקף.
מאפיינים
-
defaultZoomFactor
מספר אופציונלי
Chrome 43 ואילךהמאפיין הזה משמש להחזרת רמת הזום שמוגדרת כברירת מחדל עבור הכרטיסייה הנוכחית בקריאות ל-tabs.getZoomSettings.
-
מצב
ZoomSettingsMode optional
המאפיין הזה מגדיר איך שינויים בזום מטופלים, כלומר איזו ישות אחראית על שינוי קנה המידה בפועל של הדף. ערך ברירת המחדל הוא
automatic. -
היקף
ZoomSettingsScope optional
ההגדרה קובעת אם שינויי הזום יישמרו עבור המקור של הדף, או רק בכרטיסייה הזו. ערך ברירת המחדל הוא
per-originבמצבautomatic, ו-per-tabבכל מצב אחר.
ZoomSettingsMode
המאפיין הזה מגדיר איך שינויים בזום מטופלים, כלומר איזו ישות אחראית על שינוי קנה המידה בפועל של הדף. ערך ברירת המחדל הוא automatic.
ספירה
automatic
שינויי הזום מטופלים אוטומטית על ידי הדפדפן.
manual
מבטל את הטיפול האוטומטי בשינויי זום. האירוע onZoomChange עדיין יישלח, והתוסף אחראי להאזין לאירוע הזה ולשנות את קנה המידה של הדף באופן ידני. במצב הזה אין תמיכה בהגדלת התצוגה per-origin, ולכן המערכת מתעלמת מהגדרת הזום scope ומניחה שהזום הוא per-tab.
disabled
משבית את כל אפשרויות הזום בכרטיסייה. הכרטיסייה חוזרת לרמת הזום שמוגדרת כברירת מחדל, וכל הניסיונות לשנות את רמת הזום מתעלמים.
ZoomSettingsScope
ההגדרה קובעת אם שינויי הזום יישמרו עבור המקור של הדף, או רק בכרטיסייה הזו. ערך ברירת המחדל הוא per-origin במצב automatic, ו-per-tab בכל מצב אחר.
ספירה
'לכל מקור'
שינויי הזום נשמרים במקור של הדף המוגדל, כלומר, גם כל הכרטיסיות האחרות שמובילות לאותו מקור מוגדלות. בנוסף, per-origin שינויים בהגדלה נשמרים עם המקור, כלומר כשמנווטים לדפים אחרים באותו מקור, כולם מוגדלים באותו גורם הגדלה. ההיקף per-origin זמין רק במצב automatic.
'לכל כרטיסייה'
שינויים בזום משפיעים רק על הכרטיסייה הזו, ושינויים בזום בכרטיסיות אחרות לא משפיעים על הזום בכרטיסייה הזו. בנוסף, per-tab שינויים בהגדלה מאופסים כשעוברים בין דפים. כשעוברים לכרטיסייה, הדפים תמיד נטענים עם per-origin גורמי ההגדלה שלהם.
מאפיינים
MAX_CAPTURE_VISIBLE_TAB_CALLS_PER_SECOND
המספר המקסימלי של פעמים שאפשר לקרוא ל-captureVisibleTab בשנייה. השימוש ב-captureVisibleTab יקר ולכן לא מומלץ להשתמש בו לעיתים קרובות מדי.
ערך
2
SPLIT_VIEW_ID_NONE
מזהה שמייצג את העובדה שלא מדובר בכרטיסייה מפוצלת.
ערך
-1
TAB_ID_NONE
מזהה שמייצג את העובדה שלא מוצגת כרטיסייה בדפדפן.
ערך
-1
TAB_INDEX_NONE
אינדקס שמייצג את היעדר האינדקס של כרטיסייה ברכיב tab_strip.
ערך
-1
Methods
captureVisibleTab()
chrome.tabs.captureVisibleTab(
windowId?: number,
options?: ImageDetails,
): Promise<string>
מצלם את האזור הגלוי של הכרטיסייה הפעילה כרגע בחלון שצוין. כדי להפעיל את השיטה הזו, לתוסף צריכה להיות ההרשאה <all_urls> או ההרשאה activeTab. בנוסף לאתרים שאליהם יש לתוספים בדרך כלל גישה, השיטה הזו מאפשרת לתוספים לצלם אתרים רגישים שמוגבלים בדרך אחרת, כולל דפים של סכימת chrome:, דפים של תוספים אחרים וכתובות URL של נתונים. אפשר לצלם אתרים רגישים רק באמצעות ההרשאה 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של היציאה מופעל אם הכרטיסייה נסגרת או לא קיימת.
פרמטרים
-
createProperties
אובייקט
-
פעיל
boolean אופציונלי
האם הכרטיסייה צריכה להפוך לכרטיסייה הפעילה בחלון. ההגדרה לא משפיעה על המיקוד בחלון (ראו
windows.update). ברירת המחדל היאtrue. -
אינדקס
מספר אופציונלי
המיקום של הכרטיסייה בחלון. הערך שצוין מוגבל לטווח שבין אפס למספר הכרטיסיות בחלון.
-
openerTabId
מספר אופציונלי
המזהה של הכרטיסייה שפתחה את הכרטיסייה הזו. אם מציינים כרטיסייה, היא צריכה להיות באותו חלון כמו הכרטיסייה החדשה שנוצרה.
-
מוצמד
boolean אופציונלי
האם להצמיד את הכרטיסייה. ברירת המחדל היא
false -
נבחר
boolean אופציונלי
הוצא משימושצריך להשתמש בערך active.
האם הכרטיסייה צריכה להפוך לכרטיסייה שנבחרה בחלון. ברירת המחדל היא
true -
splitWithTabId
מספר אופציונלי
בהמתנההמזהה של כרטיסייה קיימת שאיתה רוצים ליצור תצוגה מפוצלת. אם מציינים כרטיסייה לפיצול, היא צריכה לעמוד בתנאים הבאים:
- הוא לא יכול להיות כרטיסייה שכבר פוצלה.
- היא צריכה להיות באותו חלון שבו נמצאת הכרטיסייה החדשה שנוצרה.
- אם מציינים את
windowId, הוא צריך להיות זהה למזהה החלון של הכרטיסייה המפוצלת. - אם מציינים את
index, הוא חייב להיות אינדקס סמוך לכרטיסייה שרוצים לפצל, והוא ישפיע על המיקום היחסי של הכרטיסייה החדשה שנוצרה.
-
url
מחרוזת אופציונלי
כתובת ה-URL שאליה הכרטיסייה תנווט בהתחלה. כתובות URL מוגדרות במלואן חייבות לכלול סכימה (כלומר, http://www.google.com', not 'www.google.com'). כתובות URL יחסיות הן יחסיות לדף הנוכחי בתוך התוסף. ברירת המחדל היא דף הכרטיסייה החדשה.
-
windowId
מספר אופציונלי
החלון שבו יוצרים את הכרטיסייה החדשה. ברירת המחדל היא החלון הנוכחי.
-
החזרות
-
Promise<Tab>
Chrome 88 ואילך
createSplit()
chrome.tabs.createSplit(
tabIds: [number, number],
): Promise<number>
פיצול של שתי כרטיסיות קיימות לתצוגה מפוצלת.
פרמטרים
-
tabIds
[number, number]
מערך של שני מזהי כרטיסיות בדיוק, שאותם רוצים לשייך לתצוגה מפוצלת. כל הכרטיסיות צריכות לעמוד בתנאים הבאים:
הם צריכים להיות סמוכים. הם לא יכולים להיות כבר בתצוגה מפוצלת. הם צריכים להיות באותו מצב של
windowId,pinnedו-groupId.
החזרות
-
Promise<number>
detectLanguage()
chrome.tabs.detectLanguage(
tabId?: number,
): Promise<string>
מזהה את השפה העיקרית של התוכן בכרטיסייה.
פרמטרים
-
tabId
מספר אופציונלי
ברירת המחדל היא הכרטיסייה הפעילה של החלון הנוכחי.
החזרות
-
Promise<string>
Chrome 88 ואילך
discard()
chrome.tabs.discard(
tabId?: number,
): Promise<Tab | undefined>
הכרטיסייה נמחקת מהזיכרון. הכרטיסיות שהוצאו מהזיכרון עדיין מוצגות בשורת הכרטיסיות, והן נטענות מחדש כשמפעילים אותן.
פרמטרים
-
tabId
מספר אופציונלי
המזהה של הכרטיסייה שרוצים להסיר. אם מציינים את האפשרות הזו, הכרטיסייה מושבתת אלא אם היא פעילה או שכבר הושבתה. אם לא מציינים כרטיסייה, הדפדפן משליך את הכרטיסייה הכי פחות חשובה. הפעולה הזו תיכשל אם לא קיימות כרטיסיות שאפשר לסגור.
החזרות
-
Promise<Tab | undefined>
Chrome 88 ואילךההבטחה מתקיימת אחרי שהפעולה מסתיימת.
פרמטרים
-
tabId
number
המזהה של הכרטיסייה שרוצים לשכפל.
החזרות
-
Promise<Tab | undefined>
Chrome 88 ואילך
פרמטרים
-
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.tabs.goBack(
tabId?: number,
): Promise<void>
חזרה לדף הקודם, אם יש כזה.
פרמטרים
-
tabId
מספר אופציונלי
המזהה של הכרטיסייה שאליה רוצים לחזור. ברירת המחדל היא הכרטיסייה שנבחרה בחלון הנוכחי.
החזרות
-
Promise<void>
Chrome 88 ואילך
goForward()
chrome.tabs.goForward(
tabId?: number,
): Promise<void>
מעבר קדימה לדף הבא, אם יש כזה.
פרמטרים
-
tabId
מספר אופציונלי
המספר הסידורי של הכרטיסייה שאליה רוצים לעבור קדימה. ברירת המחדל היא הכרטיסייה שנבחרה בחלון הנוכחי.
החזרות
-
Promise<void>
Chrome 88 ואילך
group()
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
מספר אופציונלי
ברירת המחדל היא החלון שבו הכרטיסייה פתוחה כרגע.
-
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+המספר הסידורי של התצוגה המפוצלת שבה הכרטיסיות נמצאות, או
tabs.SPLIT_VIEW_ID_NONEאם הכרטיסיות לא נמצאות בתצוגה מפוצלת. -
status
TabStatus אופציונלי
סטטוס הטעינה של הכרטיסייה.
-
title
מחרוזת אופציונלי
התאמה של כותרות דפים לתבנית. המערכת מתעלמת מהמאפיין הזה אם לתוסף אין הרשאת
"tabs"או הרשאות מארח לדף. -
url
מחרוזת | מערך של מחרוזות אופציונלי
התאמת כרטיסיות לאחת או יותר תבניות 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
אובייקט אופציונלי
החזרות
-
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
ההגדרה קובעת איך שינויים בזום מטופלים ובאיזה היקף.
החזרות
-
Promise<void>
Chrome 88 ואילךהבעיה נפתרת אחרי שינוי הגדרות הזום.
ungroup()
chrome.tabs.ungroup(
tabIds: number | [number, ...number[]],
): Promise<void>
הסרת כרטיסייה אחת או יותר מהקבוצות שלהן. אם קבוצות מסוימות מתרוקנות, הן נמחקות.
פרמטרים
-
tabIds
number | [number, ...number[]]
מזהה הכרטיסייה או רשימת מזהי הכרטיסיות שרוצים להסיר מהקבוצות שלהן.
החזרות
-
Promise<void>
unsplit()
chrome.tabs.unsplit(
splitViewId: number,
): Promise<void>
הכרטיסיות בתצוגה המפוצלת יוצגו ככרטיסיות נפרדות.
פרמטרים
-
splitViewId
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 שאליה הכרטיסייה תנווט. אין תמיכה בכתובות 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 מוגדרת או כשהכרטיסייה מתווספת לקבוצת כרטיסיות.
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
מחרוזת אופציונלי
כתובת ה-URL של הכרטיסייה אם היא השתנתה.
-
-
Tab
-
onZoomChange
chrome.tabs.onZoomChange.addListener(
callback: function,
)
מופעל כשמבצעים זום בכרטיסייה.
פרמטרים
-
callback
פונקציה
הפרמטר
callbackנראה כך:(ZoomChangeInfo: object) => void
-
ZoomChangeInfo
אובייקט
-
newZoomFactor
number
-
oldZoomFactor
number
-
tabId
number
-
zoomSettings
-
-