Açıklama
İçeriği, bir web sayfasının ana içeriğinin yanı sıra tarayıcının yan panelinde barındırmak için chrome.sidePanel
API'sini kullanın.
İzinler
sidePanel
Side Panel API'yi kullanmak için uzantı manifest dosyasına "sidePanel"
iznini ekleyin:
manifest.json:
{
"name": "My side panel extension",
...
"permissions": [
"sidePanel"
]
}
Kullanılabilirlik
Kavramlar ve kullanım
Side Panel API, uzantıların yan panelde kendi kullanıcı arayüzünü göstermesine olanak tanıyarak kullanıcının tarama yolculuğunu tamamlayan kalıcı deneyimler sunar.
Bazı özellikler:
- Sekmeler arasında gezinirken yan panel açık kalır (bu şekilde ayarlanırsa).
- Yalnızca belirli web sitelerinde kullanılabilir.
- Bir uzantı sayfası olarak yan paneller tüm Chrome API'lerine erişebilir.
- Kullanıcılar, Chrome'un ayarlarında panelin hangi tarafta gösterileceğini belirtebilir.
Kullanım alanları
Aşağıdaki bölümlerde, Side Panel API'ye ilişkin bazı yaygın kullanım alanları gösterilmektedir. Uzantı örneklerinin tamamı için Uzantı örnekleri bölümüne bakın.
Her sitede aynı yan paneli gösterin
Yan panel, her sitede aynı yan paneli görüntülemek için başlangıçta manifestin "side_panel"
anahtarındaki "default_path"
özelliğinden ayarlanabilir. Bu, uzantı dizini içindeki göreli bir yolu işaret etmelidir.
manifest.json:
{
"name": "My side panel extension",
...
"side_panel": {
"default_path": "sidepanel.html"
}
...
}
sidepanel.html:
<!DOCTYPE html>
<html>
<head>
<title>My Sidepanel</title>
</head>
<body>
<h1>All sites sidepanel extension</h1>
<p>This side panel is enabled on all sites</p>
</body>
</html>
Belirli bir sitede yan paneli etkinleştirme
Uzantılar, belirli bir sekmede yan paneli etkinleştirmek için sidepanel.setOptions()
simgesini kullanabilir. Bu örnekte, sekmede yapılan güncellemeleri dinlemek için chrome.tabs.onUpdated()
kullanılmaktadır. URL'nin www.google.com olup olmadığını kontrol eder ve yan paneli etkinleştirir. Aksi takdirde özellik devre dışı bırakılır.
service-worker.js:
const GOOGLE_ORIGIN = 'https://www.google.com';
chrome.tabs.onUpdated.addListener(async (tabId, info, tab) => {
if (!tab.url) return;
const url = new URL(tab.url);
// Enables the side panel on google.com
if (url.origin === GOOGLE_ORIGIN) {
await chrome.sidePanel.setOptions({
tabId,
path: 'sidepanel.html',
enabled: true
});
} else {
// Disables the side panel on all other sites
await chrome.sidePanel.setOptions({
tabId,
enabled: false
});
}
});
Bir kullanıcı, yan panelin etkin olmadığı bir sekmeye geçici olarak geçiş yaptığında yan panel gizlenir. Kullanıcı önceden açık olduğu bir sekmeye geçtiğinde bu sekme otomatik olarak tekrar gösterilir.
Kullanıcı, yan panelin etkinleştirilmediği bir siteye gittiğinde yan panel kapanır ve uzantı, yan panel açılır menüsünde gösterilmez.
Tam bir örnek için Sekmeye özel yan panel örneğine bakın.
Araç çubuğu simgesini tıklayarak yan paneli açın
Geliştiriciler, kullanıcıların sidePanel.setPanelBehavior()
içeren işlem araç çubuğu simgesini tıkladığında yan paneli açmasına izin verebilir. İlk olarak manifest dosyasında "action"
anahtarını tanımlayın:
manifest.json:
{
"name": "My side panel extension",
...
"action": {
"default_title": "Click to open panel"
},
...
}
Şimdi, bu kodu önceki örneğe ekleyin:
service-worker.js:
const GOOGLE_ORIGIN = 'https://www.google.com';
// Allows users to open the side panel by clicking on the action toolbar icon
chrome.sidePanel
.setPanelBehavior({ openPanelOnActionClick: true })
.catch((error) => console.error(error));
...
Kullanıcı etkileşiminde yan paneli programatik olarak aç
Chrome 116'da sidePanel.open()
kullanıma sunuldu. İşlem simgesini tıklama gibi bir uzantı kullanıcı hareketiyle uzantıların yan paneli açmasına olanak tanır. Ya da bir uzantı sayfasındaki veya içerik komut dosyasındaki kullanıcı etkileşimi (ör. bir düğmeyi tıklama). Tam demo için Open Side Panel örnek uzantısına bakın.
Aşağıdaki kod, kullanıcı bir içerik menüsünü tıkladığında geçerli pencerede genel bir yan panelin nasıl açılacağını gösterir. sidePanel.open()
kullanılırken, açılması gereken bağlamı seçmeniz gerekir. Genel yan paneli açmak için windowId
simgesini kullanın. Alternatif olarak, tabId
simgesini, yan paneli yalnızca belirli bir sekmede açacak şekilde ayarlayın.
service-worker.js:
chrome.runtime.onInstalled.addListener(() => {
chrome.contextMenus.create({
id: 'openSidePanel',
title: 'Open side panel',
contexts: ['all']
});
});
chrome.contextMenus.onClicked.addListener((info, tab) => {
if (info.menuItemId === 'openSidePanel') {
// This will open the panel in all the pages on the current window.
chrome.sidePanel.open({ windowId: tab.windowId });
}
});
Farklı bir panele geçme
Uzantılar, mevcut yan paneli almak için sidepanel.getOptions()
simgesini kullanabilir. Aşağıdaki örnekte, runtime.onInstalled()
için bir karşılama yan paneli ayarlanmaktadır. Ardından, kullanıcı farklı bir sekmeye gittiğinde bu sekmeyi ana yan panelle değiştirir.
service-worker.js:
const welcomePage = 'sidepanels/welcome-sp.html';
const mainPage = 'sidepanels/main-sp.html';
chrome.runtime.onInstalled.addListener(() => {
chrome.sidePanel.setOptions({ path: welcomePage });
chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
});
chrome.tabs.onActivated.addListener(async ({ tabId }) => {
const { path } = await chrome.sidePanel.getOptions({ tabId });
if (path === welcomePage) {
chrome.sidePanel.setOptions({ path: mainPage });
}
});
Kodun tamamı için Birden fazla yan panel örneğine bakın.
Yan panel kullanıcı deneyimi
Kullanıcılar ilk olarak Chrome'un yerleşik yan panellerini görür. Her bir yan panelde, yan panel menüsünde uzantının simgesi gösterilir. Herhangi bir simge eklenmezse uzantı adının ilk harfini içeren bir yer tutucu simgesi gösterilir.
Yan paneli aç
Kullanıcıların yan paneli açmasına izin vermek için birlikte bir işlem simgesi kullanın
sidePanel.setPanelBehavior()
ile. Alternatif olarak, aşağıdakiler gibi bir kullanıcı etkileşiminden sonra sidePanel.open()
numarasına çağrı yapabilirsiniz:
- İşlem tıklaması
- Klavye kısayolu
- Bağlam menüsü
- Uzantı sayfasında veya içerik komut dosyasında kullanıcı hareketi.
Yan paneli sabitleme
Yan panel araç çubuğu, yan paneliniz açıkken bir raptiye simgesi gösterir. Simgeyi tıkladığınızda uzantınızın işlem simgesi sabitlenir. İşlem simgesini sabitlendiğinde işlem simgeniz için varsayılan işlemi gerçekleştirir ve yalnızca açıkça yapılandırılmışsa yan paneli açın.
Örnekler
Daha fazla Yan Panel API uzantısı demosu için aşağıdaki uzantılardan herhangi birini keşfedin:
- Sözlük yan paneli.
- Global yan panel.
- Birden fazla yan panel.
- Yan paneli açın.
- Siteye özel yan panel.
Türler
GetPanelOptions
Özellikler
-
tabId
sayı isteğe bağlı
Belirtilirse belirtilen sekme için yan panel seçenekleri döndürülür. Aksi takdirde, varsayılan yan panel seçeneklerini döndürür (belirli ayarların olmadığı sekmeler için kullanılır).
OpenOptions
Özellikler
-
tabId
sayı isteğe bağlı
Yan panelin açılacağı sekme. İlgili sekmede sekmeye özel bir yan panel varsa panel yalnızca o sekme için açılır. Sekmeye özel bir panel yoksa genel panel, belirtilen sekmede ve sekmeye özel bir panel içermeyen diğer tüm sekmelerde açılır. Bu, ilgili sekmede o anda etkin olan tüm yan panelleri (genel veya sekmeye özgü) geçersiz kılar. Bundan veya
windowId
özelliklerinden en az biri sağlanmalıdır. -
windowId
sayı isteğe bağlı
Yan panelin açılacağı pencere. Bu yalnızca uzantıda genel (sekmeye özgü olmayan) bir yan panel varsa veya
tabId
belirtilmişse geçerlidir. Bu, kullanıcının belirtilen pencerede açık olan, şu anda etkin olan genel yan panelleri geçersiz kılar. Bundan veyatabId
özelliklerinden en az biri sağlanmalıdır.
PanelBehavior
Özellikler
-
openPanelOnActionClick
boole isteğe bağlı
Uzantının simgesini tıkladığınızda, uzantı girişinin yan panelde gösterilip gösterilmeyeceğini belirler. Varsayılan olarak yanlış değerine ayarlanır.
PanelOptions
Özellikler
-
etkin
boole isteğe bağlı
Yan panelin etkinleştirilip etkinleştirilmeyeceği. Bu işlem isteğe bağlıdır. Varsayılan değer, doğru değeridir.
-
yol
dize isteğe bağlı
Kullanılacak yan panel HTML dosyasının yolu. Bu, uzantı paketi içinde yer alan yerel bir kaynak olmalıdır.
-
tabId
sayı isteğe bağlı
Belirtilirse yan panel seçenekleri yalnızca bu kimliğe sahip sekme için geçerli olur. Atlanırsa bu seçenekler varsayılan davranışı belirler (belirli ayarları olmayan sekmeler için kullanılır). Not: Bu tabId ve varsayılan tabId için aynı yol ayarlanırsa bu tabId öğesine ait panel, varsayılan tabId parametresinden farklı bir örnek olacaktır.
SidePanel
Özellikler
-
default_path
dize
Yan panel ekranı için geliştirici tarafından belirtilen yol.
Yöntemler
getOptions()
chrome.sidePanel.getOptions(
options: GetPanelOptions,
callback?: function,
)
Etkin panel yapılandırmasını döndürür.
Parametreler
-
seçenekler
Yapılandırmanın döndürüleceği bağlamı belirtir.
-
geri çağırma
işlev isteğe bağlı
callback
parametresi şu şekilde görünür:(options: PanelOptions) => void
-
seçenekler
-
İadeler
-
Promise<PanelOptions>
Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.
getPanelBehavior()
chrome.sidePanel.getPanelBehavior(
callback?: function,
)
Uzantının mevcut yan panel davranışını döndürür.
Parametreler
-
geri çağırma
işlev isteğe bağlı
callback
parametresi şu şekilde görünür:(behavior: PanelBehavior) => void
-
ücretsiz,
-
İadeler
-
Promise<PanelBehavior>
Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.
open()
chrome.sidePanel.open(
options: OpenOptions,
callback?: function,
)
Uzantının yan panelini açar. Bu, yalnızca kullanıcı işlemine yanıt olarak çağrılabilir.
Parametreler
-
seçenekler
Yan panelin açılacağı bağlamı belirtir.
-
geri çağırma
işlev isteğe bağlı
callback
parametresi şu şekilde görünür:() => void
İadeler
-
Taahhüt<void>
Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.
setOptions()
chrome.sidePanel.setOptions(
options: PanelOptions,
callback?: function,
)
Yan paneli yapılandırır.
Parametreler
-
seçenekler
Panele uygulanacak yapılandırma seçenekleri.
-
geri çağırma
işlev isteğe bağlı
callback
parametresi şu şekilde görünür:() => void
İadeler
-
Taahhüt<void>
Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.
setPanelBehavior()
chrome.sidePanel.setPanelBehavior(
behavior: PanelBehavior,
callback?: function,
)
Uzantının yan panel davranışını yapılandırır. Bu bir düzeltme işlemidir.
Parametreler
-
ücretsiz,
Ayarlanacak yeni davranış.
-
geri çağırma
işlev isteğe bağlı
callback
parametresi şu şekilde görünür:() => void
İadeler
-
Taahhüt<void>
Manifest V3 ve sonraki sürümlerde vaatler desteklenir ancak geriye dönük uyumluluk Aynı işlev çağrısında ikisini birden kullanamazsınız. İlgili içeriği oluşturmak için kullanılan taahhüt, geri çağırmaya iletilen aynı türle çözümlenir.