chrome.action

Açıklama

Kullanılabilirlik

Manifest

chrome.action API'sini kullanmak için 3 "manifest_version" değerini belirtin ve manifest dosyanıza "action" anahtarını 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. Bu simge dahil edilmediğinde, uzantı menüsüne erişim sağlamak için uzantınız araç çubuğunda gösterilmeye devam eder. Bu nedenle, her zaman en azından "action" ve "default_icon" anahtarlarını eklemenizi öneririz.

Kavramlar ve kullanım

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

Simge

Simge, uzantınızın araç çubuğundaki ana resimdir ve manifest dosyanızın "action" anahtarındaki "default_icon" anahtarıyla ayarlanır. Simgeler 16 cihazdan bağımsız piksel (DIP) genişliğinde ve yüksekliğinde olmalıdır.

"default_icon" anahtarı, resim yollarının boyutlarının sözlüğüdür. Chrome, hangi resim ölçeğinin kullanılacağını seçmek için bu simgeleri kullanır. Tam eşleşme bulunamazsa Chrome, mevcut en yakın eşleşmeyi seçer ve resmi bu eşleşmeye uyacak şekilde ölçeklendirir. Bu durum, resim kalitesini etkileyebilir.

1,5x veya 1,2x gibi daha az yaygın ölçek faktörlerine sahip cihazlar daha yaygın hale geldiğinden simgeleriniz için birden fazla boyut sağlamanızı öneririz. Bu, uzantınızın gelecekteki olası simge görüntüleme boyutu değişikliklerine karşı da korunmasını sağlar. Ancak yalnızca tek bir boyut sağlanıyorsa "default_icon" anahtarı, sözlük yerine tek bir simgenin yolunu içeren bir dize olarak da ayarlanabilir.

Farklı bir resim yolu belirterek veya HTML canvas öğesini kullanarak dinamik olarak oluşturulmuş bir simge sağlayarak ya da uzantı hizmeti çalışanı üzerinden ayarlıyorsanız offscreen canvas API'sini kullanarak uzantınızın simgesini programatik olarak ayarlamak için action.setIcon() işlevini 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ılar (bir .crx dosyasından yüklenenler) için resimler, PNG, JPEG, BMP, ICO ve diğerleri dahil olmak üzere Blink oluşturma motorunun gösterebileceği çoğu biçimde olabilir. SVG desteklenmez. Paketi açılmış uzantılar PNG resimlerini kullanmalıdır.

İpucu (başlık)

İpucu veya başlık, kullanıcı fare işaretçisini araç çubuğundaki uzantı simgesinin üzerine getirdiğinde görünür. Bu metin, düğme odaklandığında ekran okuyucular tarafından okunan erişilebilir metne de dahil edilir.

Varsayılan ipucu, manifest.json içindeki "action" anahtarının "default_title" alanı kullanılarak ayarlanır. action.setTitle() işlevini çağırarak da programatik olarak ayarlayabilirsiniz.

Rozet

İşlemler isteğe bağlı olarak "rozet" gösterebilir. Rozet, simgenin üzerine yerleştirilmiş bir metin parçasıdır. Bu sayede, uzantının durumuyla ilgili az miktarda bilgi (ör. sayaç) gösterecek şekilde işlemi güncelleyebilirsiniz. Rozette bir metin bileşeni ve arka plan rengi bulunur. Alan sınırlı olduğundan rozet metninde en fazla dört karakter kullanmanızı öneririz.

Rozet oluşturmak için action.setBadgeBackgroundColor() ve action.setBadgeText() işlevlerini çağırarak rozeti programatik olarak ayarlayın. Manifest dosyasında varsayılan rozet ayarı yoktur. Rozet rengi değerleri, rozetin RGBA rengini oluşturan 0 ile 255 arasında dört tam sayıdan oluşan bir dizi veya CSS renk 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ğundaki uzantının işlem düğmesini tıkladığında işlemin pop-up'ı gösterilir. Pop-up, istediğiniz HTML içeriklerini barındırabilir 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ında bulunan "default_popup" özelliğiyle ayarlanır. Bu özellik varsa uzantı dizinindeki göreli bir yolu göstermelidir. Ayrıca, action.setPopup() yöntemi kullanılarak farklı bir göreli yolu işaret edecek şekilde dinamik olarak da 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ğıdakine benzer 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 özgü ayarlar, genel ayarlara göre önceliklidir.

Etkinleştirme durumu

Varsayılan olarak, araç çubuğu işlemleri her sekmede etkindir (tıklanabilir). Bu varsayılan ayarı, manifest dosyasının action anahtarında default_state özelliğini ayarlayarak değiştirebilirsiniz. default_state "disabled" olarak ayarlanırsa işlem varsayılan olarak devre dışıdır ve tıklanabilir olması için programatik olarak etkinleştirilmesi gerekir. default_state, "enabled" (varsayılan) olarak ayarlanırsa işlem varsayılan olarak etkinleştirilir ve tıklanabilir.

Durumu action.enable() ve action.disable() yöntemlerini kullanarak programatik olarak kontrol edebilirsiniz. Bu yalnızca pop-up'ın (varsa) veya action.onClicked etkinliğinin uzantınıza gönderilip gönderilmeyeceğini etkiler. İşlemin araç çubuğundaki varlığını etkilemez.

Örnekler

Aşağıdaki örneklerde, işlemlerin uzantılarda yaygın olarak kullanılan bazı yöntemleri gösterilmektedir. Bu API'yi denemek için chrome-extension-samples deposundan Action API örneğini yükleyin.

Pop-up gösterme

Kullanıcı, uzantının işlem düğmesini tıkladığında uzantının pop-up göstermesi yaygın bir durumdur. Bunu kendi uzantınızda uygulamak için manifest.json dosyanızda pop-up'ı bildirin ve Chrome'un pop-up'ta göstermesi 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ıklama üzerine içerik komut dosyası yerleştirme

Uzantılar için yaygın bir model, birincil özelliklerini uzantının işlemiyle kullanıma sunmaktır. Aşağıdaki örnekte bu kalıp gösterilmektedir. Kullanıcı işlemi tıkladığında uzantı, mevcut sayfaya bir içerik komut dosyası yerleştirir. Ardından içerik komut dosyası, her şeyin beklendiği gibi çalıştığını doğrulamak 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) belirli sitelerde işlemi etkinleştirmek için declarativeContent'in nasıl kullanılabileceğ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,
): Promise<void>

chrome.action.enable(
  tabId?: number,
): Promise<void>

chrome.action.getBadgeBackgroundColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getBadgeText(
  details: TabDetails,
): Promise<string>

chrome.action.getBadgeTextColor(
  details: TabDetails,
): Promise<extensionTypes.ColorArray>

chrome.action.getPopup(
  details: TabDetails,
): Promise<string>

chrome.action.getTitle(
  details: TabDetails,
): Promise<string>

chrome.action.getUserSettings(): Promise<UserSettings>

chrome.action.isEnabled(
  tabId?: number,
): Promise<boolean>

chrome.action.openPopup(
  options?: OpenPopupOptions,
): Promise<void>

chrome.action.setBadgeBackgroundColor(
  details: object,
): Promise<void>

chrome.action.setBadgeText(
  details: object,
): Promise<void>

chrome.action.setBadgeTextColor(
  details: object,
): Promise<void>

chrome.action.setIcon(
  details: object,
): Promise<void>

chrome.action.setPopup(
  details: object,
): Promise<void>

chrome.action.setTitle(
  details: object,
): Promise<void>

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

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