chrome.action

Açıklama

Kullanılabilirlik

Manifest

chrome.action API'yi kullanmak için "manifest_version" olarak 3 belirtin ve "action" anahtarını manifest dosyanıza ekleyin.

{
  "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 manifest dosyanızın "action" anahtarındaki "default_icon" anahtarıyla ayarlanır. 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, kullanılacak resim ölçeğini seçmek için bu simgeleri kullanır. Tam eşleşme bulunamazsa Chrome, mümkün olan en yakın bağlantıyı seçer ve bunu görsele sığacak şekilde ölçeklendirir. Bu durum, resim kalitesini etkileyebilir.

1,5x veya 1,2x gibi daha seyrek rastlanan ölçek faktörlerine sahip cihazlar daha yaygınlaştığından, simgeleriniz için birden fazla boyut sağlamanızı öneririz. Bu işlem, uzantınızı olası simge görüntüleme boyutu değişikliklerine karşı da gelecekte korur. Ancak yalnızca tek bir boyut sağlanırsa "default_icon" anahtarı, sözlük yerine tek bir simgeye giden yolu içeren bir dize olarak da ayarlanabilir.

Farklı bir resim yolu belirterek veya HTML tuval öğesini ya da bir uzantı hizmet çalışanından ayar yapıyorsanız ekran dışı kanvas API'yi kullanarak dinamik olarak oluşturulmuş bir simge sağlayarak uzantınızın simgesini programatik olarak ayarlamak için action.setIcon() öğesini de çağırabilirsiniz.

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}, () => { /* ... */ });

Paketlenmiş uzantılarda (.crx dosyasından yüklenen) resimler, Blink oluşturma motorunun görüntüleyebileceği birçok biçimde (PNG, JPEG, BMP, ICO vb.) olabilir. SVG desteklenmiyor. Paketlenmemiş uzantılar PNG resimleri kullanmalıdır.

İpucu (başlık)

Kullanıcı, fare imlecini araç çubuğundaki uzantı simgesinin üzerinde tuttuğunda ipucu veya başlık görünür. Ayrıca, düğme odaklanıldığında ekran okuyucular tarafından sesli okunan erişilebilir metinde de yer alır.

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" (rozet, simgenin üzerine yerleştirilmiş bir metin) görüntüleyebilir. Bu, işlemi uzantının durumuyla ilgili az miktarda bilgiyi (örneğin, sayaç) görüntüleyecek şekilde güncellemenize olanak tanır. 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() çağrılarını yaparak rozeti programatik olarak ayarlayın. Manifest dosyasında varsayılan bir rozet ayarı yoktur. Rozet rengi değerleri, rozetin RGBA rengini oluşturan 0 ile 255 arasında dört tam sayı dizisi veya CSS rengi değerine sahip bir dize olabilir.

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ğunda uzantının işlem düğmesini tıkladığında bir işlemin pop-up'ı gösterilir. Pop-up istediğiniz herhangi bir HTML içeriğini içerebilir ve içeriğine uyacak şekilde otomatik olarak boyutlandırılır. 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" özelliği tarafından ayarlanır. Varsa bu özellik, uzantı dizinindeki göreli bir yolu işaret etmelidir. Ayrıca, action.setPopup() yöntemi kullanılarak farklı bir göreli yola işaret edecek şekilde dinamik olarak güncellenebilir.

Kullanım alanları

Sekme başına durum

Uzantı işlemleri, her sekme için farklı durumlara sahip olabilir. Tek bir sekme için değer ayarlamak üzere 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 eklenmezse bu ayar genel ayar olarak değerlendirilir. Sekmeye özel ayarlar, genel ayarlara göre önceliklidir.

Etkin durumu

Varsayılan olarak, her sekmede araç çubuğu işlemleri etkindir (tıklanabilir). Bunu, action.enable() ve action.disable() yöntemlerini kullanarak kontrol edebilirsiniz. Bu yalnızca pop-up'ın (varsa) veya action.onClicked etkinliğinin uzantınıza gönderilip gönderilmeyeceğini etkiler; işlemin araç çubuğundaki varlığını etkilemez.

Örnekler

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

Pop-up göster

Kullanıcı uzantıyla ilgili işlemi tıkladığında uzantıların pop-up göstermesi yaygın bir durumdur. Bunu kendi uzantınızda uygulamak için manifest.json öğenizde pop-up'ı bildirin ve Chrome'un pop-up'ta görüntülemesi gereken içeriği belirtin.

// 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 için yaygın bir yöntem, uzantı işlemini kullanarak birincil özelliklerini göstermektir. Aşağıdaki örnekte bu kalıp gösterilmektedir. Kullanıcı işlemi tıkladığında, uzantı, geçerli sayfaya bir içerik komut dosyası ekler. Ardından içerik komut dosyası, her şeyin beklendiği gibi çalıştığını doğrulamak için bir uyarı görüntüler.

// 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 emüle 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) işlemi belirli sitelerde etkinleştirmek için declarativeContent'i nasıl kullanabileceği gösterilmektedir.

// 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,
)