chrome.action

Açıklama

Kullanılabilirlik

Manifest

chrome.action API'yi kullanmak için "manifest_version" olarak 3 belirtin ve şunu ekleyin: manifest dosyanızdaki "action" anahtarını kullanın.

{
  "name": "Action Extension",
  ...
  "action": {
    "default_icon": {              // optional
      "16": "images/icon16.png",   // optional
      "24": "images/icon24.png",   // optional
      "32": "images/icon32.png"    // optional
    },
    "default_title": "Click Me",   // optional, shown in tooltip
    "default_popup": "popup.html"  // optional
  },
  ...
}

"action" anahtarı (alt öğeleriyle birlikte) isteğe bağlıdır. Dahil edilmediğinde, uzantınız uzantının menüsüne erişmek için araç çubuğunda gösterilmeye devam eder. Bu nedenle, her zaman en azından "action" ve "default_icon" anahtarlarını dahil etmenizi öneririz.

Kavramlar ve kullanım

Kullanıcı arayüzünün bölümleri

Simge

Simge, uzantınızın araç çubuğunda bulunan ana resimdir ve "default_icon" tuşuyla manifestonuzun "action" anahtarı. Simgeler, cihazdan bağımsız 16 piksel (DIP) genişliğinde ve uzun olmalıdır.

"default_icon" anahtarı, boyutların resim yollarına yönelik bir sözlüğüdür. Chrome bu simgeleri kullanır seçerek hangi resim ölçeğinin kullanılacağını seçebilirsiniz. Tam eşleme bulunamazsa Chrome, eşleşmeye en yakın olan kullanılabilir ve resmi sığacak şekilde ölçeklendirir. Bu durum, resim kalitesini etkileyebilir.

Çünkü 1,5x veya 1,2x gibi daha az yaygın ölçek faktörlerine sahip cihazlar simgeleriniz için birden fazla boyut sağlamanızı öneririz. Bu, uzantınızı olası simge görüntüleme boyutu değişikliklerine karşı da korur. Ancak, yalnızca tek bir boyut sağlıyorsanız "default_icon" anahtarı bir bir simgenin yolunu içeren bir dize olarak görünür.

Uzantınızın simgesini programatik olarak ayarlamak için action.setIcon() yöntemini de çağırabilirsiniz farklı bir resim yolu belirterek veya HTML tuvalini kullanarak dinamik olarak oluşturulmuş bir simge sağlayarak öğesi veya bir uzantı hizmet çalışanından ayarlanıyorsa ekran dışı Canvas API'sini kullanabilirsiniz.

const canvas = new OffscreenCanvas(16, 16);
const context = canvas.getContext('2d');
context.clearRect(0, 0, 16, 16);
context.fillStyle = '#00FF00';  // Green
context.fillRect(0, 0, 16, 16);
const imageData = context.getImageData(0, 0, 16, 16);
chrome.action.setIcon({imageData: imageData}, () => { /* ... */ });

Sıkıştırılmış uzantılar (.crx dosyasından yüklenen) için resimler, PNG, JPEG, BMP, ICO ve diğerleri dahil olmak üzere Blink oluşturma motorunun görüntüleyebileceği çoğu biçimde olabilir. SVG desteklenmiyor. Paketlenmemiş uzantılar PNG resimleri kullanmalıdır.

İpucu (başlık)

İpucu veya başlık, kullanıcı fare imlecini araç çubuğundaki uzantının simgesinin üzerinde tuttuğunda görünür. Ayrıca, düğme odağa alındığında ekran okuyucular tarafından okunan erişilebilir metne de dahil edilir.

Varsayılan ipucu, manifest.json öğesindeki "action" anahtarının "default_title" alanı kullanılarak ayarlanır. action.setTitle() öğesini çağırarak bu özelliği programatik olarak da ayarlayabilirsiniz.

Rozet

İşlemler isteğe bağlı olarak bir "rozet" gösterebilir Simgenin üzerine katman olarak yerleştirilmiş bir metin parçasıdır. Bu sayede, işlemi, uzantının durumuyla ilgili az miktarda bilgi (ör. sayaç) gösterecek şekilde güncelleyebilirsiniz. Rozetin bir metin bileşeni ve bir arka plan rengi vardır. Yer sınırlı olduğu için Rozet metninde en fazla dört karakter kullanılmasını öneririz.

Rozet oluşturmak için action.setBadgeBackgroundColor() ve action.setBadgeText(). Manifest dosyasında varsayılan bir rozet ayarı yoktur. Rozet rengi değerleri 0 ile 255 arasında, RGBA rengini oluşturan dört tam sayıdan oluşan bir dizi olabilir rozeti veya CSS rengi değeri olan bir dize.

chrome.action.setBadgeBackgroundColor(
  {color: [0, 255, 0, 0]},  // Green
  () => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
  {color: '#00FF00'},  // Also green
  () => { /* ... */ },
);

chrome.action.setBadgeBackgroundColor(
  {color: 'green'},  // Also, also green
  () => { /* ... */ },
);

Pop-up

Kullanıcı, araç çubuğundaki uzantının işlem düğmesini tıkladığında bir işlem pop-up'ı gösterilir. Pop-up istediğiniz herhangi bir HTML içeriğini içerebilir. Bu pop-up, sığacak şekilde otomatik olarak boyutlandırılır kontrol edebilirsiniz. Pop-up'ın boyutu 25x25 ile 800x600 piksel arasında olmalıdır.

Pop-up, başlangıçta manifest.json dosyasındaki "action" anahtarındaki "default_popup" mülkü tarafından ayarlanır. Varsa, bu özellik uzantı içindeki göreli bir yola işaret etmelidir dizin. Ayrıca action.setPopup() yöntemi kullanılarak dinamik olarak farklı bir göreli yola işaret edecek şekilde güncellenebilir.

Kullanım alanları

Sekme başına durum

Uzantı işlemlerinin her sekme için farklı durumları olabilir. Bir kullanıcı için değer belirlemek sekmesinde, action API'sinin ayar yöntemlerinde tabId özelliğini kullanın. Örneğin, belirli bir sekmenin rozet metnini ayarlamak için aşağıdaki gibi bir işlem yapın:

function getTabId() { /* ... */}
function getTabBadge() { /* ... */}

chrome.action.setBadgeText(
  {
    text: getTabBadge(tabId),
    tabId: getTabId(),
  },
  () => { ... }
);

tabId özelliği atlanırsa ayar, genel ayar olarak değerlendirilir. Sekmeye özel ayarları genel ayarlara göre önceliklidir.

Etkin durum

Araç çubuğu işlemleri varsayılan olarak her sekmede etkindir (tıklanabilir). Bunu action.enable() ve action.disable() yöntemlerini kullanarak kontrol edebilirsiniz. Bu yalnızca pop-up'ın (varsa) Uzantınıza action.onClicked etkinlik gönderildi; İşlemin varlığını etkilemez. tıklayın.

Örnekler

İşlemlerin uzantılarda kullanıldığı bazı yaygın durumlara örnekler aşağıda verilmiştir. Bu API'yi denemek için chrome-extension-samples deposundan Action API örneğini yükleyin.

Pop-up göster

Kullanıcı uzantının işlemini tıkladığında uzantının pop-up göstermesi yaygın bir durumdur. Alıcı: bunu kendi uzantınızda uygulayın, manifest.json sayfanızda pop-up'ı bildirin ve Chrome'un pop-up'ta görüntülemesi gereken içerik.

// manifest.json
{
  "name": "Action popup demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to view a popup",
    "default_popup": "popup.html"
  }
}

<!-- popup.html -->
<!DOCTYPE html>
<html>
<head>
  <style>
    html {
      min-height: 5em;
      min-width: 10em;
      background: salmon;
    }
  </style>
</head>
<body>
  <p>Hello, world!</p>
</body>
</html>

Tıklandığında içerik komut dosyası ekle

Uzantıların yaygın bir özelliği, uzantının işlemini kullanarak birincil özelliklerini göstermesidir. Aşağıdaki örnekte bu kalıp gösterilmektedir. Kullanıcı işlemi tıkladığında uzantı, mevcut sayfaya bir içerik komut dosyası ekler. Ardından içerik komut dosyası, her şeyin beklendiği gibi çalıştığından emin olmak için bir uyarı gösterir.

// manifest.json
{
  "name": "Action script injection demo",
  "version": "1.0",
  "manifest_version": 3,
  "action": {
    "default_title": "Click to show an alert"
  },
  "permissions": ["activeTab", "scripting"],
  "background": {
    "service_worker": "background.js"
  }
}

// background.js
chrome.action.onClicked.addListener((tab) => {
  chrome.scripting.executeScript({
    target: {tabId: tab.id},
    files: ['content.js']
  });
});

// content.js
alert('Hello, world!');

declarativeContent ile işlemleri taklit etme

Bu örnekte, bir uzantının arka plan mantığının (a) bir işlemi varsayılan olarak nasıl devre dışı bırakabileceği ve (b) İşlemi belirli sitelerde etkinleştirmek için declarativeContent öğesini kullanın.

// service-worker.js

// Wrap in an onInstalled callback to avoid unnecessary work
// every time the service worker is run
chrome.runtime.onInstalled.addListener(() => {
  // Page actions are disabled by default and enabled on select tabs
  chrome.action.disable();

  // Clear all rules to ensure only our expected rules are set
  chrome.declarativeContent.onPageChanged.removeRules(undefined, () => {
    // Declare a rule to enable the action on example.com pages
    let exampleRule = {
      conditions: [
        new chrome.declarativeContent.PageStateMatcher({
          pageUrl: {hostSuffix: '.example.com'},
        })
      ],
      actions: [new chrome.declarativeContent.ShowAction()],
    };

    // Finally, apply our new array of rules
    let rules = [exampleRule];
    chrome.declarativeContent.onPageChanged.addRules(rules);
  });
});

chrome.action.disable(
  tabId?: number,
  callback?: function,
)

chrome.action.enable(
  tabId?: number,
  callback?: function,
)

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
  callback?: function,
)

chrome.action.getBadgeText(
  details: TabDetails,
  callback?: function,
)

chrome.action.getBadgeTextColor(
  details: TabDetails,
  callback?: function,
)

chrome.action.getPopup(
  details: TabDetails,
  callback?: function,
)

chrome.action.getTitle(
  details: TabDetails,
  callback?: function,
)

chrome.action.getUserSettings(
  callback?: function,
)

chrome.action.isEnabled(
  tabId?: number,
  callback?: function,
)

chrome.action.openPopup(
  options?: OpenPopupOptions,
  callback?: function,
)

chrome.action.setBadgeBackgroundColor(
  details: object,
  callback?: function,
)

chrome.action.setBadgeText(
  details: object,
  callback?: function,
)

chrome.action.setBadgeTextColor(
  details: object,
  callback?: function,
)

chrome.action.setIcon(
  details: object,
  callback?: function,
)

chrome.action.setPopup(
  details: object,
  callback?: function,
)

chrome.action.setTitle(
  details: object,
  callback?: function,
)

chrome.action.onClicked.addListener(
  callback: function,
)

chrome.action.onUserSettingsChanged.addListener(
  callback: function,
)