跳到主要内容

Chrome.tabs API 详解

chrome.tabs API 是 Chrome 扩展开发中最常用的 API 之一,用于与浏览器标签页进行交互。以下是其主要功能和使用方法的详细说明。

一、权限配置​

首先需要在 manifest.json 中声明权限:

{
  "permissions": ["tabs"],
  "host_permissions": ["<all_urls>"]
}

二、核心方法​

1. 查询标签页 (chrome.tabs.query)​

查询符合条件的标签页,这是最常用的方法之一。

// 获取当前活动标签页
chrome.tabs.query({active: true, currentWindow: true}, (tabs) => {
  let currentTab = tabs[0];
  console.log(currentTab.url, currentTab.title);
});

// 获取所有标签页
chrome.tabs.query({}, (tabs) => {
  console.log(`总共有 ${tabs.length} 个标签页`);
});

// 查询特定URL的标签页
chrome.tabs.query({url: "https://*.google.com/*"}, (tabs) => {
  tabs.forEach(tab => console.log(tab.title));
});

// 其他查询条件
chrome.tabs.query({
  active: false,        // 非活动标签页
  pinned: true,         // 固定的标签页
  audible: true,        // 正在播放声音的标签页
  muted: false,         // 未静音的标签页
  highlighted: true,    // 高亮的标签页
  currentWindow: true   // 当前窗口的标签页
}, (tabs) => {
  // 处理结果
});

2. 创建标签页 (chrome.tabs.create)​

// 创建新标签页
chrome.tabs.create({
  url: 'https://www.example.com',
  active: true  // 是否激活新标签页
}, (tab) => {
  console.log('创建的标签页ID:', tab.id);
});

// 在特定位置创建标签页
chrome.tabs.create({
  url: 'https://www.example.com',
  index: 0,  // 放在第一个位置
  pinned: true,  // 固定标签页
  openerTabId: currentTabId  // 设置打开者标签页
});

3. 更新标签页 (chrome.tabs.update)​

// 更新当前标签页的URL
chrome.tabs.update(tabId, {
  url: 'https://www.newurl.com'
});

// 激活某个标签页
chrome.tabs.update(tabId, {
  active: true
});

// 静音/取消静音
chrome.tabs.update(tabId, {
  muted: true
});

// 固定/取消固定标签页
chrome.tabs.update(tabId, {
  pinned: true
});

// 如果不指定tabId,则更新当前标签页
chrome.tabs.update({
  url: 'https://www.example.com'
});

4. 移动标签页 (chrome.tabs.move)​

// 移动单个标签页
chrome.tabs.move(tabId, {
  index: 0,  // 移动到第一个位置
  windowId: windowId  // 可选:移动到其他窗口
});

// 移动多个标签页
chrome.tabs.move([tabId1, tabId2], {
  index: -1  // -1 表示移到最后
});

5. 重新加载标签页 (chrome.tabs.reload)​

// 重新加载指定标签页
chrome.tabs.reload(tabId);

// 强制重新加载(忽略缓存)
chrome.tabs.reload(tabId, {
  bypassCache: true
});

// 重新加载当前标签页
chrome.tabs.reload();

6. 关闭标签页 (chrome.tabs.remove)​

// 关闭单个标签页
chrome.tabs.remove(tabId);

// 关闭多个标签页
chrome.tabs.remove([tabId1, tabId2, tabId3]);

// 关闭当前标签页
chrome.tabs.query({active: true, currentWindow: true}, (tabs) => {
  chrome.tabs.remove(tabs[0].id);
});

7. 获取标签页信息 (chrome.tabs.get)​

chrome.tabs.get(tabId, (tab) => {
  console.log('标签页信息:', tab);
  console.log('URL:', tab.url);
  console.log('标题:', tab.title);
  console.log('是否活动:', tab.active);
});

8. 复制标签页 (chrome.tabs.duplicate)​

chrome.tabs.duplicate(tabId, (duplicatedTab) => {
  console.log('复制的新标签页ID:', duplicatedTab.id);
});

9. 执行脚本 (chrome.tabs.executeScript)​

注意: Manifest V3 中已废弃,改用 chrome.scripting.executeScript

// Manifest V2 写法
chrome.tabs.executeScript(tabId, {
  code: 'document.body.style.backgroundColor = "red"'
});

chrome.tabs.executeScript(tabId, {
  file: 'content.js'
});

// Manifest V3 新写法
chrome.scripting.executeScript({
  target: { tabId: tabId },
  func: () => {
    document.body.style.backgroundColor = "red";
  }
});

10. 向标签页发送消息 (chrome.tabs.sendMessage)​

// 发送消息到指定标签页
chrome.tabs.sendMessage(tabId, {
  action: "doSomething",
  data: "hello"
}, (response) => {
  console.log('收到回复:', response);
});

// 在content script中接收消息
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
  if (request.action === "doSomething") {
    console.log(request.data);
    sendResponse({result: "success"});
  }
});

11. 捕获标签页截图 (chrome.tabs.captureVisibleTab)​

chrome.tabs.captureVisibleTab(windowId, {
  format: 'png',  // 或 'jpeg'
  quality: 90     // JPEG质量 (0-100)
}, (dataUrl) => {
  // dataUrl 是 base64 编码的图片
  console.log(dataUrl);
});

12. 分组相关 (Chrome 88+)​

// 将标签页添加到组
chrome.tabs.group({
  tabIds: [tabId1, tabId2],
  groupId: groupId  // 可选,不指定则创建新组
});

// 取消标签页分组
chrome.tabs.ungroup(tabId);

13. 其他实用方法​

// 获取当前标签页
chrome.tabs.getCurrent((tab) => {
  console.log('当前标签页:', tab);
});

// 检测标签页语言
chrome.tabs.detectLanguage(tabId, (language) => {
  console.log('检测到的语言:', language);
});

// 设置缩放
chrome.tabs.setZoom(tabId, 1.5);  // 150%

// 获取缩放
chrome.tabs.getZoom(tabId, (zoomFactor) => {
  console.log('缩放比例:', zoomFactor);
});

三、事件监听​

1. 标签页创建事件​

chrome.tabs.onCreated.addListener((tab) => {
  console.log('新标签页已创建:', tab.id);
});

2. 标签页更新事件​

chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
  // changeInfo 包含变化的属性
  if (changeInfo.status === 'complete') {
    console.log('页面加载完成:', tab.url);
  }
  if (changeInfo.url) {
    console.log('URL已改变:', changeInfo.url);
  }
});

3. 标签页激活事件​

chrome.tabs.onActivated.addListener((activeInfo) => {
  console.log('激活的标签页ID:', activeInfo.tabId);
  console.log('所在窗口ID:', activeInfo.windowId);
});

4. 标签页移除事件​

chrome.tabs.onRemoved.addListener((tabId, removeInfo) => {
  console.log('标签页已关闭:', tabId);
  console.log('窗口是否关闭:', removeInfo.isWindowClosing);
});

5. 标签页移动事件​

chrome.tabs.onMoved.addListener((tabId, moveInfo) => {
  console.log('标签页已移动:', tabId);
  console.log('从位置', moveInfo.fromIndex, '到位置', moveInfo.toIndex);
});

6. 标签页替换事件​

chrome.tabs.onReplaced.addListener((addedTabId, removedTabId) => {
  console.log('标签页被替换');
});

7. 标签页分离/附加事件​

chrome.tabs.onDetached.addListener((tabId, detachInfo) => {
  console.log('标签页从窗口分离');
});

chrome.tabs.onAttached.addListener((tabId, attachInfo) => {
  console.log('标签页附加到窗口');
});

四、实用示例​

示例1: 关闭重复的标签页​

chrome.tabs.query({}, (tabs) => {
  let urlMap = {};
  tabs.forEach(tab => {
    if (urlMap[tab.url]) {
      chrome.tabs.remove(tab.id);
    } else {
      urlMap[tab.url] = true;
    }
  });
});

示例2: 在所有标签页中执行操作​

chrome.tabs.query({}, async (tabs) => {
  for (let tab of tabs) {
    if (tab.url.startsWith('http')) {
      await chrome.scripting.executeScript({
        target: { tabId: tab.id },
        func: () => {
          console.log('在标签页中执行');
        }
      });
    }
  }
});

示例3: 标签页管理器​

// 获取所有标签页并分组显示
chrome.tabs.query({}, (tabs) => {
  let windows = {};
  tabs.forEach(tab => {
    if (!windows[tab.windowId]) {
      windows[tab.windowId] = [];
    }
    windows[tab.windowId].push({
      id: tab.id,
      title: tab.title,
      url: tab.url,
      active: tab.active
    });
  });
  console.log('按窗口分组的标签页:', windows);
});

示例4: 自动刷新标签页​

// 每30秒刷新一次特定URL的标签页
setInterval(() => {
  chrome.tabs.query({url: "https://example.com/*"}, (tabs) => {
    tabs.forEach(tab => {
      chrome.tabs.reload(tab.id);
    });
  });
}, 30000);

五、注意事项​

  1. 权限要求: 访问 tab.url 和 tab.title 需要 tabs 权限或相应的 host_permissions
  2. 异步操作: 大多数方法都是异步的,使用回调函数或 Promise
  3. Manifest V3: 某些 API 已被替换或废弃,注意版本兼容性
  4. 性能考虑: 批量操作标签页时注意性能影响
  5. 安全限制: 无法操作 chrome:// 等特殊页面

这些是 chrome.tabs API 的主要用法,可以满足大部分标签页操作需求。根据具体场景选择合适的方法即可。