Açıklama
Google Chrome araç çubuğundaki uzantı simgesini kontrol etmek için chrome.action API'sini kullanın.
Kullanılabilirlik
Manifest
browser.action API'yi kullanmak için "manifest_version" değerini 3 olarak 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. Dahil edilmediğinde uzantınız, uzantının menüsüne erişim sağlamak için 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ı tarafından ayarlanır. Simgeler 16 cihazdan bağımsız piksel (DIP) genişliğinde ve yüksekliğinde olmalıdır.
"default_icon" anahtarı, boyutların resim yollarına eşlendiği bir sözlüktü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 boyutu seçer ve resmi sığacak şekilde ölçeklendirir. Bu durum, resim kalitesini etkileyebilir.
1,5x veya 1,2x gibi daha az yaygın ölçeklendirme faktörlerine sahip cihazlar daha yaygın hale geldiğinden simgeleriniz için birden fazla boyut sağlamanızı öneririz. Bu sayede, uzantınız simge görüntüleme boyutunda gelecekte yapılabilecek değişikliklere de hazır olur. Ancak yalnızca tek bir boyut sağlanıyorsa "default_icon" anahtarı, sözlük yerine tek bir simgenin yolunu içeren bir dizeye de ayarlanabilir.
Ayrıca, farklı bir resim yolu belirterek veya HTML canvas öğesini kullanarak dinamik olarak oluşturulmuş bir simge sağlayarak ya da bir uzantı hizmet çalışanından ayarlıyorsanız ekran dışı canvas API'sini kullanarak uzantınızın simgesini programatik olarak ayarlamak için action.setIcon() yöntemini ç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);
browser.action.setIcon({imageData: imageData}, () => { /* ... */ });
Paketlenmiş uzantılar (.crx dosyasından yüklenen) için resimler, Blink oluşturma motorunun görüntüleyebileceği çoğu biçimde (PNG, JPEG, BMP, ICO vb.) olabilir. SVG desteklenmez. Paketlenmemiş uzantılarda PNG resimler kullanılmalı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 seslendirilen 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() yöntemini çağırarak da programatik olarak ayarlayabilirsiniz.
Rozet
İşlemler isteğe bağlı olarak bir "rozet" (simgenin üzerine yerleştirilmiş bir metin parçası) gösterebilir. Bu sayede, uzantının durumuyla ilgili az miktarda bilgi (ör. sayaç) gösterecek şekilde işlemi güncelleyebilirsiniz. Rozetin bir metin bileşeni ve arka plan rengi vardır. 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() çağrısı yaparak rozeti programatik olarak ayarlayın. Manifest dosyasında varsayılan rozet ayarı yok. 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 rengi değerine sahip bir dize olabilir.
browser.action.setBadgeBackgroundColor(
{color: [0, 255, 0, 0]}, // Green
() => { /* ... */ },
);
browser.action.setBadgeBackgroundColor(
{color: '#00FF00'}, // Also green
() => { /* ... */ },
);
browser.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 HTML içeriğini barındırabilir ve içeriğine sığacak ş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ği tarafından ayarlanır. Bu özellik varsa uzantı dizinindeki göreli bir yolu işaret etmelidir. Ayrıca action.setPopup() yöntemi kullanılarak farklı bir göreli yolu işaret edecek şekilde dinamik olarak güncellenebilir.
Kullanım alanları
Sekme başına durum
Uzantı işlemlerinin her sekme için farklı durumları olabilir. Tek bir sekme için değer ayarlamak istiyorsanız 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() { /* ... */}
browser.action.setBadgeText(
{
text: getTabBadge(tabId),
tabId: getTabId(),
},
() => { ... }
);
tabId özelliği belirtilmezse ayar, genel ayar olarak değerlendirilir. Sekmeye özel ayarlar, genel ayarlara göre önceliklidir.
Etkin durumda
Varsayılan olarak, araç çubuğu işlemleri her sekmede etkindir (tıklanabilir). Manifest'in action anahtarında default_state özelliğini ayarlayarak bu varsayılanı değiştirebilirsiniz. default_state, "disabled" olarak ayarlanırsa işlem varsayılan olarak devre dışı bırakılı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.
action.enable() ve action.disable() yöntemlerini kullanarak durumu programatik olarak kontrol edebilirsiniz. Bu ayar 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
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şlemini tıkladığında uzantının bir pop-up göstermesi yaygın bir durumdur. Bu özelliği kendi uzantınızda uygulamak için manifest.json dosyanızda pop-up'ı tanımlayın 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ıklandığında içerik komut dosyası yerleştirme
Uzantılar için yaygın bir kalıp, uzantının işlemini kullanarak birincil özelliklerini göstermektir. 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ığı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
browser.action.onClicked.addListener((tab) => {
browser.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'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
browser.runtime.onInstalled.addListener(() => {
// Page actions are disabled by default and enabled on select tabs
browser.action.disable();
// Clear all rules to ensure only our expected rules are set
browser.declarativeContent.onPageChanged.removeRules(undefined, () => {
// Declare a rule to enable the action on example.com pages
let exampleRule = {
conditions: [
new browser.declarativeContent.PageStateMatcher({
pageUrl: {hostSuffix: '.example.com'},
})
],
actions: [new browser.declarativeContent.ShowAction()],
};
// Finally, apply our new array of rules
let rules = [exampleRule];
browser.declarativeContent.onPageChanged.addRules(rules);
});
});
Türler
OpenPopupOptions
Özellikler
-
windowId
number isteğe bağlı
İşlem pop-up'ının açılacağı pencerenin kimliği. Belirtilmezse varsayılan olarak o anda etkin olan pencere kullanılır.
TabDetails
Özellikler
-
tabId
number isteğe bağlı
Durumu sorgulanacak sekmenin kimliği. Sekme belirtilmezse sekmeye özgü olmayan durum döndürülür.
UserSettings
Bir uzantının işlemiyle ilgili kullanıcı tarafından belirtilen ayarların koleksiyonu.
Özellikler
-
isOnToolbar
boole
Uzantının işlem simgesinin tarayıcı pencerelerinin üst düzey araç çubuğunda görünür olup olmadığı (yani uzantının kullanıcı tarafından "sabitlenip sabitlenmediği").
UserSettingsChange
Özellikler
-
isOnToolbar
boole isteğe bağlı
Uzantının işlem simgesinin tarayıcı pencerelerinin üst düzey araç çubuğunda görünür olup olmadığı (yani uzantının kullanıcı tarafından "sabitlenip sabitlenmediği").
Yöntemler
disable()
browser.action.disable(
tabId?: number,
): Promise<void>
Bir sekme için işlemi devre dışı bırakır.
Parametreler
-
tabId
number isteğe bağlı
İşlemini değiştirmek istediğiniz sekmenin kimliği.
İadeler
-
Promise<void>
enable()
browser.action.enable(
tabId?: number,
): Promise<void>
Bir sekme için işlemi etkinleştirir. İşlemler varsayılan olarak etkindir.
Parametreler
-
tabId
number isteğe bağlı
İşlemini değiştirmek istediğiniz sekmenin kimliği.
İadeler
-
Promise<void>
getBadgeBackgroundColor()
browser.action.getBadgeBackgroundColor(
details: TabDetails,
): Promise<extensionTypes.ColorArray>
İşlemin arka plan rengini alır.
Parametreler
-
ayrıntılar
İadeler
-
Promise<extensionTypes.ColorArray>
getBadgeText()
browser.action.getBadgeText(
details: TabDetails,
): Promise<string>
İşlemin rozet metnini alır. Sekme belirtilmezse sekmeye özel olmayan rozet metni döndürülür. displayActionCountAsBadgeText etkinleştirilirse declarativeNetRequestFeedback izni mevcut olmadığı veya sekmeye özel rozet metni sağlanmadığı sürece yer tutucu metin döndürülür.
Parametreler
-
ayrıntılar
İadeler
-
Promise<string>
getBadgeTextColor()
browser.action.getBadgeTextColor(
details: TabDetails,
): Promise<extensionTypes.ColorArray>
İşlemin metin rengini alır.
Parametreler
-
ayrıntılar
İadeler
-
Promise<extensionTypes.ColorArray>
getPopup()
browser.action.getPopup(
details: TabDetails,
): Promise<string>
Bu işlem için pop-up olarak ayarlanan HTML belgesini alır.
Parametreler
-
ayrıntılar
İadeler
-
Promise<string>
Parametreler
-
ayrıntılar
İadeler
-
Promise<string>
getUserSettings()
browser.action.getUserSettings(): Promise<UserSettings>
Bir uzantının işlemiyle ilgili kullanıcı tarafından belirtilen ayarları döndürür.
İadeler
-
Promise<UserSettings>
isEnabled()
browser.action.isEnabled(
tabId?: number,
): Promise<boolean>
Uzantı işleminin bir sekme için (veya tabId sağlanmamışsa genel olarak) etkinleştirilip etkinleştirilmediğini belirtir. Yalnızca declarativeContent kullanılarak etkinleştirilen işlemler her zaman yanlış değerini döndürür.
Parametreler
-
tabId
number isteğe bağlı
Etkin durumunu kontrol etmek istediğiniz sekmenin kimliği.
İadeler
-
Promise<boolean>
openPopup()
browser.action.openPopup(
options?: OpenPopupOptions,
): Promise<void>
Uzantının pop-up'ını açar. Chrome 118 ve Chrome 126 arasında bu özellik yalnızca politika tarafından yüklenen uzantılarda kullanılabilir.
Parametreler
-
seçenekler
OpenPopupOptions isteğe bağlı
Pop-up'ı açma seçeneklerini belirtir.
İadeler
-
Promise<void>
setBadgeBackgroundColor()
browser.action.setBadgeBackgroundColor(
details: object,
): Promise<void>
Rozetin arka plan rengini ayarlar.
Parametreler
-
ayrıntılar
nesne
-
renk
string | ColorArray
Rozetin RGBA rengini oluşturan [0,255] aralığında dört tam sayıdan oluşan bir dizi. Örneğin, opak kırmızı
[255, 0, 0, 255]şeklindedir. CSS değeri içeren bir dize de olabilir. Opak kırmızı#FF0000veya#F00olur. -
tabId
number isteğe bağlı
Değişikliği, belirli bir sekme seçildiğinde geçerli olacak şekilde sınırlandırır. Sekme kapatıldığında otomatik olarak sıfırlanır.
-
İadeler
-
Promise<void>
setBadgeText()
browser.action.setBadgeText(
details: object,
): Promise<void>
İşlem için rozet metnini ayarlar. Rozet, simgenin üst kısmında gösterilir.
Parametreler
-
ayrıntılar
nesne
-
tabId
number isteğe bağlı
Değişikliği, belirli bir sekme seçildiğinde geçerli olacak şekilde sınırlandırır. Sekme kapatıldığında otomatik olarak sıfırlanır.
-
text (metin)
string isteğe bağlı
İstediğiniz sayıda karakter girebilirsiniz ancak alana yalnızca yaklaşık dört karakter sığar. Boş bir dize (
'') iletilirse rozet metni temizlenir.tabIdbelirtilir vetextboş bırakılırsa belirtilen sekmenin metni temizlenir ve varsayılan olarak genel rozet metni kullanılır.
-
İadeler
-
Promise<void>
setBadgeTextColor()
browser.action.setBadgeTextColor(
details: object,
): Promise<void>
Rozetin metin rengini ayarlar.
Parametreler
-
ayrıntılar
nesne
-
renk
string | ColorArray
Rozetin RGBA rengini oluşturan [0,255] aralığında dört tam sayıdan oluşan bir dizi. Örneğin, opak kırmızı
[255, 0, 0, 255]şeklindedir. CSS değeri içeren bir dize de olabilir. Opak kırmızı#FF0000veya#F00olur. Bu değer ayarlanmazsa rozetin arka plan rengiyle kontrast oluşturacak bir renk otomatik olarak seçilir ve metin görünür hale gelir. Alfa değerleri 0'a eşit olan renkler ayarlanmaz ve hata döndürür. -
tabId
number isteğe bağlı
Değişikliği, belirli bir sekme seçildiğinde geçerli olacak şekilde sınırlandırır. Sekme kapatıldığında otomatik olarak sıfırlanır.
-
İadeler
-
Promise<void>
setIcon()
browser.action.setIcon(
details: object,
): Promise<void>
İşlemin simgesini ayarlar. Simge, bir resim dosyasının yolu veya bir tuval öğesindeki piksel verileri ya da bunlardan birinin sözlüğü olarak belirtilebilir. path veya imageData özelliği belirtilmelidir.
Parametreler
-
ayrıntılar
nesne
-
imageData
ImageData | nesne isteğe bağlı
Ayarlanacak simgeyi temsil eden bir ImageData nesnesi veya {size -> ImageData} sözlüğü. Simge bir sözlük olarak belirtilirse kullanılacak gerçek resim, ekranın piksel yoğunluğuna göre seçilir. Bir ekran alanı birimine sığan resim piksellerinin sayısı
scaleisescale* n boyutunda resim seçilir. Burada n, kullanıcı arayüzündeki simgenin boyutudur. En az bir resim belirtilmelidir. 'details.imageData = foo' ifadesinin 'details.imageData = {'16': foo}' ifadesine eşdeğer olduğunu unutmayın. -
yol
string | object isteğe bağlı
Ayarlanacak simgeyi işaret eden göreli bir resim yolu veya {size -> relative image path} sözlüğü. Simge bir sözlük olarak belirtilirse kullanılacak gerçek resim, ekranın piksel yoğunluğuna göre seçilir. Bir ekran alanı birimine sığan resim piksellerinin sayısı
scaleisescale* n boyutunda resim seçilir. Burada n, kullanıcı arayüzündeki simgenin boyutudur. En az bir resim belirtilmelidir. "details.path = foo" ifadesinin "details.path = {'16': foo}" ifadesine eşdeğer olduğunu unutmayın. -
tabId
number isteğe bağlı
Değişikliği, belirli bir sekme seçildiğinde geçerli olacak şekilde sınırlandırır. Sekme kapatıldığında otomatik olarak sıfırlanır.
-
İadeler
-
Promise<void>
Chrome 96 ve sonraki sürümler Chrome 148'den itibaren browser.*
setPopup()
browser.action.setPopup(
details: object,
): Promise<void>
Kullanıcı, işlemin simgesini tıkladığında açılacak HTML belgesini pop-up olarak ayarlar.
Parametreler
-
ayrıntılar
nesne
-
pop-up
dize
Pop-up'ta gösterilecek HTML dosyasının göreli yolu. Boş dizeye (
'') ayarlanırsa pop-up gösterilmez. -
tabId
number isteğe bağlı
Değişikliği, belirli bir sekme seçildiğinde geçerli olacak şekilde sınırlandırır. Sekme kapatıldığında otomatik olarak sıfırlanır.
-
İadeler
-
Promise<void>
setTitle()
browser.action.setTitle(
details: object,
): Promise<void>
İşlemin başlığını ayarlar. Bu, ipucunda gösterilir.
Parametreler
-
ayrıntılar
nesne
-
tabId
number isteğe bağlı
Değişikliği, belirli bir sekme seçildiğinde geçerli olacak şekilde sınırlandırır. Sekme kapatıldığında otomatik olarak sıfırlanır.
-
title
dize
Fareyle üzerine gelindiğinde işlemin göstermesi gereken dize.
-
İadeler
-
Promise<void>
Etkinlikler
onClicked
browser.action.onClicked.addListener(
callback: function,
)
Bir işlem simgesi tıklandığında tetiklenir. İşlemde pop-up varsa bu etkinlik tetiklenmez.
Parametreler
-
callback
işlev
callbackparametresi şu şekilde görünür:(tab: tabs.Tab) => void
-
sekme
-
onUserSettingsChanged
browser.action.onUserSettingsChanged.addListener(
callback: function,
)
Bir uzantının işlemiyle ilgili kullanıcı tarafından belirtilen ayarlar değiştiğinde tetiklenir.
Parametreler
-
callback
işlev
callbackparametresi şu şekilde görünür:(change: UserSettingsChange) => void
-
değiştir
-