chrome.browserAction

Açıklama

Adres çubuğunun sağındaki ana Google Chrome araç çubuğuna simge yerleştirmek için tarayıcı işlemlerini kullanın. Tarayıcı işlemlerinin simgesine ek olarak ipucu, rozet ve pop-up olabilir.

Kullanılabilirlik

≤ MV2

Aşağıdaki resimde, adres çubuğunun sağındaki çok renkli kare bir tarayıcı işleminin simgesidir. Simgenin altında bir pop-up gösterilir.

Her zaman etkin olmayan bir simge oluşturmak istiyorsanız tarayıcı işlemi yerine sayfa işlemi kullanın.

Manifest

Tarayıcı işleminizi uzantı manifest dosyasına şu şekilde kaydedin:

{
  "name": "My extension",
  ...
  "browser_action": {
    "default_icon": {                // optional
      "16": "images/icon16.png",     // optional
      "24": "images/icon24.png",     // optional
      "32": "images/icon32.png"      // optional
    },
    "default_title": "Google Mail",  // optional, shown in tooltip
    "default_popup": "popup.html"    // optional
  },
  ...
}

Chrome'da kullanılacak herhangi bir boyuttaki simgeyi sağlayabilirsiniz. Chrome, en yakın simgeyi seçer ve 16 piksellik alanı dolduracak şekilde uygun boyuta ölçeklendirir. Ancak tam boyut sağlanmazsa bu ölçeklendirme, simgenin ayrıntılarını kaybetmesine veya bulanık görünmesine neden olabilir.

1,5x veya 1,2x gibi daha az yaygın ölçek faktörlerine sahip cihazlar yaygınlaşmaya başladığından, simgeleriniz için birden fazla boyut sağlamanız önerilir. Bu, simge görüntüleme boyutu değişirse farklı simgeler sağlamak için daha fazla çalışma yapmanız gerekmediğinden de emin olmanızı sağlar.

Varsayılan simgeyi kaydetmek için kullanılan eski söz dizimi hâlâ desteklenmektedir:

{
  "name": "My extension",
  ...
  "browser_action": {
    ...
    "default_icon": "images/icon32.png"  // optional
    // equivalent to "default_icon": { "32": "images/icon32.png" }
  },
  ...
}

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

Tarayıcı işlemlerinin simgesi, ipucu, rozeti ve pop-up'ı olabilir.

Simge

Chrome'daki tarayıcı işlem simgelerinin genişliği ve yüksekliği 16 dips'tir (cihazdan bağımsız piksel). Daha büyük simgeler sığacak şekilde yeniden boyutlandırılır ancak en iyi sonuçlar için 16 piksel kare simge kullanın.

Simgeyi iki şekilde ayarlayabilirsiniz: statik resim kullanarak veya HTML5 tuval öğesini kullanarak. Basit uygulamalarda statik resimler kullanmak daha kolaydır ancak kanvas öğesini kullanarak daha dinamik kullanıcı arayüzleri (ör. akıcı animasyon) oluşturabilirsiniz.

Statik resimler BMP, GIF, ICO, JPEG veya PNG dahil olmak üzere WebKit'in görüntüleyebileceği herhangi bir biçimde olabilir. Sıkıştırılmamış uzantılarda resimler PNG biçiminde olmalıdır.

Simgeyi ayarlamak için manifest dosyasında browser_action öğesinin default_icon alanını kullanın veya browserAction.setIcon yöntemini çağırın.

Ekran piksel yoğunluğu (size_in_pixel / size_in_dip oranı) 1'den farklı olduğunda simgenin düzgün şekilde görüntülenmesi için simge, farklı boyutlara sahip resimler grubu olarak tanımlanabilir. Gösterilecek gerçek resim, 16 dip piksel boyutuna en uygun şekilde gruptan seçilir. Simge grubu herhangi bir boyuttaki simge spesifikasyonunu içerebilir. Chrome en uygun olanı seçer.

İpucu

İpucu metnini ayarlamak için manifest dosyasında browser_action öğesinin default_title alanını kullanın veya browserAction.setTitle yöntemini çağırın. default_title alanı için yerel ayara özgü dizeler belirtebilirsiniz. Ayrıntılar için Uluslararası hale getirme konusuna bakın.

Rozet

Tarayıcı işlemleri isteğe bağlı olarak bir rozet (simgenin üzerine yerleştirilmiş bir metin parçası) gösterebilir. Rozetler, tarayıcı işlemini güncelleyerek uzantının durumuyla ilgili az miktarda bilgi görüntülemeyi kolaylaştırır.

Rozetin alanı sınırlı olduğundan rozetin uzunluğu en fazla 4 karakter olmalıdır.

Sırasıyla browserAction.setBadgeText ve browserAction.setBadgeBackgroundColor öğelerini kullanarak rozetin metnini ve rengini ayarlayın.

Bir tarayıcı işleminde pop-up varsa kullanıcı uzantının simgesini tıkladığında pop-up gösterilir. İstediğiniz HTML içeriklerini içerebilen pop-up, içeriğine sığacak şekilde otomatik olarak boyutlandırılır. Pop-up 25x25'ten küçük ve 800x600'tan büyük olamaz.

Tarayıcı işleminize pop-up eklemek için pop-up'ın içeriğini içeren bir HTML dosyası oluşturun. Manifest dosyasında default_popup öğesinin default_popup alanında HTML dosyasını belirtin veya browserAction.setPopup yöntemini çağırın.

İpuçları

En iyi görsel etki için aşağıdaki yönergeleri uygulayın:

  • Çoğu sayfada anlamlı olan özellikler için tarayıcı işlemlerini kullanın.
  • Yalnızca birkaç sayfa için anlamlı olan özelliklerde tarayıcı işlemlerini kullanmayın. Bunun yerine pageactions parametresini kullanın.
  • 16x16 piksellik alanı en iyi şekilde kullanan büyük ve renkli simgeler kullanın. Tarayıcı işlemi simgelerinin sayfa işlemi simgelerinden biraz daha büyük ve ağır görünmesi gerekir.
  • Google Chrome'un tek renkli menü simgesini taklit etmeyin. Bu, temalarla iyi çalışmaz ve zaten uzantılar biraz öne çıkmalıdır.
  • Simgenize yumuşak kenarlar eklemek için alfa şeffaflığını kullanın. Birçok kullanıcı tema kullandığından simgeniz çeşitli arka plan renklerinde güzel görünmelidir.
  • Simgenizi sürekli olarak animasyonlu yapmayın. Bu çok can sıkıcı.

Örnekler

Tarayıcı işlemlerinin kullanımına ilişkin basit örnekleri examples/api/browserAction dizininde bulabilirsiniz. Diğer örnekler ve kaynak kodu görüntülemeyle ilgili yardım için Örnekler bölümüne bakın.

Türler

TabDetails

Chrome 88 ve sonraki sürümler

Özellikler

  • tabId

    number isteğe bağlı

    Durumu sorgulanacak sekmenin kimliği. Sekme belirtilmezse sekmeye özgü olmayan durum döndürülür.

Yöntemler

disable()

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

Bir sekme için tarayıcı işlemini devre dışı bırakır.

Parametreler

  • tabId

    number isteğe bağlı

    Tarayıcı işleminin değiştirileceği sekmenin kimliği.

  • callback

    işlev isteğe bağlı

    Chrome 67 ve sonraki sürümler

    callback parametresi şu şekilde görünür: 

    () => void

İadeler

  • Promise<void>

    Chrome 88 ve sonraki sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

enable()

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

Bir sekme için tarayıcı işlemini etkinleştirir. Varsayılan olarak etkindir.

Parametreler

  • tabId

    number isteğe bağlı

    Tarayıcı işleminin değiştirileceği sekmenin kimliği.

  • callback

    işlev isteğe bağlı

    Chrome 67 ve sonraki sürümler

    callback parametresi şu şekilde görünür: 

    () => void

İadeler

  • Promise<void>

    Chrome 88 ve sonraki sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

getBadgeBackgroundColor()

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

Tarayıcı işleminin arka plan rengini alır.

Parametreler

  • ayrıntılar

    TabDetails

  • callback

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (result: ColorArray) => void

İadeler

  • Chrome 88 ve sonraki sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

getBadgeText()

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

Tarayıcı işleminin rozet metnini alır. Sekme belirtilmezse sekmeye özgü olmayan rozet metni döndürülür.

Parametreler

  • ayrıntılar

    TabDetails

  • callback

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (result: string) => void

    • sonuç

      dize

İadeler

  • Promise<string>

    Chrome 88 ve sonraki sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

getPopup()

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

Bu tarayıcı işlemi için pop-up olarak ayarlanan HTML dokümanı alır.

Parametreler

  • ayrıntılar

    TabDetails

  • callback

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (result: string) => void

    • sonuç

      dize

İadeler

  • Promise<string>

    Chrome 88 ve sonraki sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

getTitle()

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

Tarayıcı işleminin başlığını alır.

Parametreler

  • ayrıntılar

    TabDetails

  • callback

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    (result: string) => void

    • sonuç

      dize

İadeler

  • Promise<string>

    Chrome 88 ve sonraki sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

setBadgeBackgroundColor()

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

Rozetin arka plan rengini ayarlar.

Parametreler

  • ayrıntılar

    nesne

    • renk

      dize | ColorArray

      Rozetin RGBA rengini oluşturan 0-255 aralığında dört tam sayı dizisi. CSS onaltılık renk değeri içeren bir dize de olabilir. Örneğin, #FF0000 veya #F00 (kırmızı). Renkleri tam şeffaflıkta oluşturur.

    • tabId

      number isteğe bağlı

      Değişikliği belirli bir sekme seçildiğinde olacak şekilde sınırlar. Sekme kapatıldığında otomatik olarak sıfırlanır.

  • callback

    işlev isteğe bağlı

    Chrome 67 ve sonraki sürümler

    callback parametresi şu şekilde görünür: 

    () => void

İadeler

  • Promise<void>

    Chrome 88 ve sonraki sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

setBadgeText()

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

Tarayıcı işleminin rozet metnini ayarlar. Rozet, simgenin üstünde gösterilir.

Parametreler

  • ayrıntılar

    nesne

    • tabId

      number isteğe bağlı

      Değişikliği belirli bir sekme seçildiğinde olacak şekilde sınırlar. Sekme kapatıldığında otomatik olarak sıfırlanır.

    • text (metin)

      dize isteğe bağlı

      İstediğiniz sayıda karakter iletebilirsiniz ancak alana yalnızca dört karakter sığabilir. Boş bir dize ('') iletilirse rozet metni temizlenir. tabId belirtilir ve text null ise belirtilen sekmenin metni temizlenir ve varsayılan olarak global rozet metni kullanılır.

  • callback

    işlev isteğe bağlı

    Chrome 67 ve sonraki sürümler

    callback parametresi şu şekilde görünür: 

    () => void

İadeler

  • Promise<void>

    Chrome 88 ve sonraki sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

setIcon()

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

Tarayıcı işleminin simgesini ayarlar. Simge, bir resim dosyasının yolu, kanvas öğesindeki piksel verileri veya 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 sözlük ({size -> ImageData}). Simge bir sözlük olarak belirtilirse kullanılan resim, ekranın piksel yoğunluğuna göre seçilir. Bir ekran alanı birimine sığabilecek resim piksellerinin sayısı scale ise scale * n boyutunda bir resim seçilir. Burada n, kullanıcı arayüzündeki simgenin boyutudur. En az bir resim belirtilmelidir. "details.imageData = foo" değerinin "details.imageData = {'16': foo}" ile eşdeğer olduğunu unutmayın.

    • yol

      dize | nesne isteğe bağlı

      Ayarlanacak bir simgeyi işaret eden göreli resim yolu veya sözlük ({size -> relative image path}). Simge bir sözlük olarak belirtilirse kullanılan resim, ekranın piksel yoğunluğuna göre seçilir. Bir ekran alanı birimine sığabilecek resim piksellerinin sayısı scale ise scale * n boyutunda bir 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}" ile eşdeğer olduğunu unutmayın.

    • tabId

      number isteğe bağlı

      Değişikliği belirli bir sekme seçildiğinde olacak şekilde sınırlar. Sekme kapatıldığında otomatik olarak sıfırlanır.

  • callback

    işlev isteğe bağlı

    callback parametresi şu şekilde görünür: 

    () => void

İadeler

  • Promise<void>

    Chrome 116 ve sonraki sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

setPopup()

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

HTML dokümanı, kullanıcı tarayıcı işlem simgesini tıkladığında pop-up olarak açılacak şekilde ayarlanır.

Parametreler

  • ayrıntılar

    nesne

    • pop-up

      dize

      Pop-up'ta gösterilecek HTML dosyasının göreli yolu. Boş dize ('') olarak ayarlanırsa pop-up gösterilmez.

    • tabId

      number isteğe bağlı

      Değişikliği belirli bir sekme seçildiğinde olacak şekilde sınırlar. Sekme kapatıldığında otomatik olarak sıfırlanır.

  • callback

    işlev isteğe bağlı

    Chrome 67 ve sonraki sürümler

    callback parametresi şu şekilde görünür: 

    () => void

İadeler

  • Promise<void>

    Chrome 88 ve sonraki sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

setTitle()

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

Tarayıcı işleminin başlığını ayarlar. Bu başlık, ipucu bölümünde görünür.

Parametreler

  • ayrıntılar

    nesne

    • tabId

      number isteğe bağlı

      Değişikliği belirli bir sekme seçildiğinde olacak şekilde sınırlar. Sekme kapatıldığında otomatik olarak sıfırlanır.

    • title

      dize

      Fareyle üzerine gelindiğinde tarayıcı işleminin göstermesi gereken dize.

  • callback

    işlev isteğe bağlı

    Chrome 67 ve sonraki sürümler

    callback parametresi şu şekilde görünür: 

    () => void

İadeler

  • Promise<void>

    Chrome 88 ve sonraki sürümler

    Sözler yalnızca Manifest V3 ve sonraki sürümlerde desteklenir. Diğer platformların geri çağırma işlevlerini kullanması gerekir.

Etkinlikler

onClicked

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

Bir tarayıcı işlemi simgesi tıklandığında tetiklenir. Tarayıcı işleminde pop-up varsa tetiklenmez.

Parametreler

  • callback

    işlev

    callback parametresi şu şekilde görünür: 

    (tab: tabs.Tab) => void