الوصف
استخدام واجهة برمجة التطبيقات chrome.windows
API للتفاعل مع نوافذ المتصفِّح يمكنك استخدام واجهة برمجة التطبيقات هذه لإنشاء النوافذ وتعديلها وإعادة ترتيبها في المتصفح.
الأذونات
عند طلب الوصول إلى العنصر، تحتوي windows.Window
على مصفوفة من عناصر tabs.Tab
. عليك الإفصاح عن إذن "tabs"
في البيان إذا كنت بحاجة إلى الوصول إلى سمات url
pendingUrl
أو title
أو favIconUrl
في tabs.Tab
. مثلاً:
{
"name": "My extension",
...
"permissions": ["tabs"],
...
}
المفاهيم والاستخدام
النافذة الحالية
تستخدم العديد من الوظائف في نظام الإضافة وسيطة windowId
اختيارية يتم ضبطها تلقائيًا على النافذة الحالية.
النافذة الحالية هي النافذة التي تحتوي على الرمز الذي يتم تنفيذه حاليًا. من المهم أن تدرك أن هذا يمكن أن يختلف عن النافذة العلوية أو المركزة.
على سبيل المثال، لنفترض أنّ إحدى الإضافات تنشئ بضع علامات تبويب أو نوافذ من ملف HTML واحد، وأنّ ملف HTML يحتوي على طلب الوصول إلى tabs.query()
. النافذة الحالية هي النافذة التي تحتوي على
الصفحة التي أجريت المكالمة، بغض النظر عن النافذة العلوية.
في حال مشغِّلي الخدمات، تعود قيمة النافذة الحالية إلى آخر نافذة نشطة. في بعض الحالات، قد لا تكون هناك نافذة حالية لصفحات الخلفية.
أمثلة
لتجربة واجهة برمجة التطبيقات هذه، يُرجى تثبيت مثال واجهة برمجة تطبيقات Windows من مستودع chrome-extension-pattern.
![نافذتان، لكل منهما علامة تبويب واحدة](https://developer.chrome.com/static/docs/extensions/reference/api/windows/images/windows.png?authuser=6&hl=ar)
الأنواع
CreateType
تحدِّد هذه السياسة نوع نافذة المتصفّح التي تريد إنشاءها. تم إيقاف " Panel" نهائيًا ولا يتوفّر إلا للإضافات الحالية المدرَجة في القائمة المسموح بها على نظام التشغيل ChromeOS.
التعداد
"عادي"
يحدد هذا الإعداد النافذة كنافذة عادية.
"نافذة منبثقة"
يحدد هذا الإعداد النافذة كنافذة منبثقة.
" Panel"
يحدد هذا الإعداد النافذة على أنّها لوحة.
QueryOptions
أماكن إقامة
-
تعبئة
منطقية اختيارية
إذا كانت القيمة "صحيح"، سيحتوي الكائن
windows.Window
على السمةtabs
التي تحتوي على قائمة بالعناصرtabs.Tab
. لا تحتوي كائناتTab
على السماتurl
وpendingUrl
وtitle
وfavIconUrl
إلا إذا كان ملف البيان الخاص بالإضافة يتضمّن الإذن"tabs"
. -
windowTypes
WindowType[] اختيارية
وفي حال ضبطها، تتم فلترة
windows.Window
التي يتم عرضها بناءً على نوعها. وفي حال ترك هذه السياسة بدون ضبط، يتم ضبط الفلتر التلقائي على['normal', 'popup']
.
Window
أماكن إقامة
-
alwaysOnTop
boolean
ما إذا تم ضبط النافذة لتكون دائمًا في أعلى الشاشة
-
تركيز
boolean
ما إذا كانت النافذة هي النافذة محل التركيز حاليًا أم لا.
-
الطول
الرقم اختياري
ارتفاع النافذة، بما في ذلك الإطار، بالبكسل. في بعض الحالات، قد لا يتم تخصيص سمة
height
لنافذة، على سبيل المثال، عند طلب البحث عن النوافذ المغلقة من واجهة برمجة تطبيقاتsessions
. -
id
الرقم اختياري
رقم تعريف النافذة. أرقام تعريف النوافذ فريدة ضمن جلسة متصفّح. في بعض الحالات، قد لا يتم تخصيص سمة
ID
لنافذة. على سبيل المثال، عند إجراء طلبات بحث عن النوافذ باستخدام واجهة برمجة التطبيقاتsessions
، قد يتوفّر رقم تعريف جلسة في هذه الحالة. -
وضع التصفّح المتخفي
boolean
ما إذا كانت النافذة في وضع التصفُّح المتخفي
-
في يمين الصورة
الرقم اختياري
إزاحة النافذة من الحافة اليسرى للشاشة بالبكسل. في بعض الحالات، قد لا يتم تخصيص سمة
left
لنافذة، على سبيل المثال، عند طلب البحث عن النوافذ المغلقة من واجهة برمجة تطبيقاتsessions
. -
sessionId
سلسلة اختيارية
رقم تعريف الجلسة المستخدَم لتحديد نافذة بشكلٍ فريد، والذي تم الحصول عليه من واجهة برمجة تطبيقات
sessions
-
state
WindowState اختيارية
حالة نافذة المتصفح هذه.
-
علامات التبويب
Tab[] اختيارية
مصفوفة من عناصر
tabs.Tab
تمثل علامات التبويب الحالية في النافذة. -
في أعلى الصورة
الرقم اختياري
إزاحة النافذة من الحافة العلوية من الشاشة بالبكسل. في بعض الحالات، قد لا يتم تخصيص سمة
top
لنافذة، على سبيل المثال، عند طلب البحث عن النوافذ المغلقة من واجهة برمجة تطبيقاتsessions
. -
كتابة
WindowType اختيارية
تمثّل هذه السمة نوع نافذة المتصفّح.
-
العرض
الرقم اختياري
عرض النافذة، بما في ذلك الإطار، بالبكسل في بعض الحالات، قد لا يتم تخصيص سمة
width
لنافذة، على سبيل المثال، عند طلب البحث عن النوافذ المغلقة من واجهة برمجة تطبيقاتsessions
.
WindowState
حالة نافذة المتصفح هذه. في بعض الحالات، قد لا يتم تخصيص سمة state
لنافذة، على سبيل المثال، عند طلب البحث عن النوافذ المغلقة من واجهة برمجة تطبيقات sessions
.
التعداد
"عادي"
حالة النافذة العادية (ليست مصغّرة أو مكبرة أو بملء الشاشة).
"تم تصغير الحجم"
حالة النافذة التي تم تصغيرها
"تكبير"
حالة النافذة التي تم تكبيرها
"ملء الشاشة"
حالة النافذة بملء الشاشة:
"قفل الشاشة بملء الشاشة"
حالة النافذة بملء الشاشة مقفلة. لا يمكن الخروج من حالة ملء الشاشة هذه من خلال إجراء المستخدم، وهي متاحة فقط للإضافات المُدرَجة في القائمة المسموح بها على نظام التشغيل Chrome.
WindowType
يشير ذلك إلى نوع نافذة المتصفّح. في بعض الحالات، قد لا يتم تخصيص السمة type
لنافذة، على سبيل المثال، عند طلب البحث عن النوافذ المغلقة من واجهة برمجة التطبيقات sessions
.
التعداد
"عادية"
نافذة متصفح عادية
"نافذة منبثقة"
نافذة منبثقة للمتصفح
" Panel"
تم إيقافها في واجهة برمجة التطبيقات هذه. نافذة بنمط لوحة تطبيقات Chrome ولا يمكن للإضافات الاطّلاع إلا على نوافذ اللوحة الخاصة بها فقط.
"app"
تم إيقافه في واجهة برمجة التطبيقات هذه. نافذة تطبيق Chrome ويمكن للإضافات الاطّلاع على نوافذ التطبيق فقط.
"devtools"
نافذة "أدوات المطوِّرين"
أماكن إقامة
WINDOW_ID_CURRENT
قيمة windowId التي تمثّل النافذة الحالية.
القيمة
-2
WINDOW_ID_NONE
قيمة windowId التي تُمثِّل عدم توفُّر نافذة متصفِّح Chrome.
القيمة
-1
الطُرق
create()
chrome.windows.create(
createData?: object,
callback?: function,
)
ينشئ (يفتح) نافذة متصفح جديدة مع توفير أي تغيير في الحجم أو موضع أو عنوان URL تلقائي اختياري.
المَعلمات
-
createData
الكائن اختياري
-
تركيز
منطقية اختيارية
إذا
true
، سيتم فتح نافذة نشطة. إذاfalse
، سيتم فتح نافذة غير نشطة. -
الطول
الرقم اختياري
الارتفاع بالبكسل للنافذة الجديدة، بما في ذلك الإطار. إذا لم يتم تحديده، سيتم ضبط القيمة التلقائية على الارتفاع الطبيعي.
-
وضع التصفّح المتخفي
منطقية اختيارية
ما إذا كانت النافذة الجديدة يجب أن تكون نافذة تصفّح متخفٍ.
-
في يمين الصورة
الرقم اختياري
عدد وحدات البكسل المراد وضع النافذة الجديدة عليها من الحافة اليسرى للشاشة. وفي حال عدم تحديد ذلك، تتم إزاحة النافذة الجديدة بشكل طبيعي من آخر نافذة محل التركيز. يتم تجاهل هذه القيمة بالنسبة إلى اللوحات.
-
setSelfAsOpener
منطقية اختيارية
الإصدار 64 من Chrome والإصدارات الأحدثفي حال
true
، يتم ضبط "window.opener" في النافذة التي تم إنشاؤها حديثًا على المتصل وتكون في وحدة سياقات التصفُّح ذات الصلة نفسها مثل المتصل. -
state
WindowState اختيارية
Chrome 44 والإصدارات الأحدثالحالة الأولية للنافذة. لا يمكن دمج الحالات
minimized
وmaximized
وfullscreen
معleft
أوtop
أوwidth
أوheight
. -
tabId
الرقم اختياري
رقم تعريف علامة التبويب المطلوب إضافتها إلى النافذة الجديدة.
-
في أعلى الصورة
الرقم اختياري
عدد وحدات البكسل المراد وضع النافذة الجديدة عليها من الحافة العلوية من الشاشة. وفي حال عدم تحديد ذلك، تتم إزاحة النافذة الجديدة بشكل طبيعي من آخر نافذة محل التركيز. يتم تجاهل هذه القيمة بالنسبة إلى اللوحات.
-
كتابة
CreateType اختيارية
تحدِّد هذه السياسة نوع نافذة المتصفّح التي تريد إنشاءها.
-
url
سلسلة | string[] اختيارية
عنوان URL أو مصفوفة من عناوين URL لفتحها كعلامات تبويب في النافذة يجب أن تتضمّن عناوين URL المؤهّلة بالكامل مخططًا، مثل "http://www.google.com" وليس "www.google.com". تُعتبر عناوين URL غير المؤهّلة بالكامل نسبية داخل الإضافة. يتم ضبط صفحة "علامة تبويب جديدة" تلقائيًا على صفحة "علامة تبويب جديدة".
-
العرض
الرقم اختياري
عرض النافذة الجديدة بالبكسل، بما في ذلك الإطار. وفي حال عدم تحديد قيمة، سيتم ضبط القيمة التلقائية على العرض الطبيعي.
-
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(window?: Window) => void
-
نافذة
النافذة اختيارية
يحتوي على تفاصيل حول النافذة التي تم إنشاؤها.
-
المرتجعات
-
Promise<Window | undefined>
Chrome 88 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
get()
chrome.windows.get(
windowId: number,
queryOptions?: QueryOptions,
callback?: function,
)
الحصول على تفاصيل حول نافذة.
المَعلمات
-
windowId
الرقم
-
queryOptions
QueryOptions اختيارية
Chrome 88 والإصدارات الأحدث -
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(window: Window) => void
-
نافذة
-
المرتجعات
-
الوعد<نافذة>
Chrome 88 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getAll()
chrome.windows.getAll(
queryOptions?: QueryOptions,
callback?: function,
)
الحصول على جميع النوافذ.
المَعلمات
-
queryOptions
QueryOptions اختيارية
Chrome 88 والإصدارات الأحدث -
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(windows: Window[]) => void
-
نوافذ
النافذة[]
-
المرتجعات
-
وعد<نافذة[]>
Chrome 88 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getCurrent()
chrome.windows.getCurrent(
queryOptions?: QueryOptions,
callback?: function,
)
لعرض النافذة الحالية.
المَعلمات
-
queryOptions
QueryOptions اختيارية
Chrome 88 والإصدارات الأحدث -
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(window: Window) => void
-
نافذة
-
المرتجعات
-
الوعد<نافذة>
Chrome 88 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
getLastFocused()
chrome.windows.getLastFocused(
queryOptions?: QueryOptions,
callback?: function,
)
إظهار النافذة التي كانت مركّزة مؤخرًا، وعادةً ما تظهر النافذة "في الأعلى".
المَعلمات
-
queryOptions
QueryOptions اختيارية
Chrome 88 والإصدارات الأحدث -
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(window: Window) => void
-
نافذة
-
المرتجعات
-
الوعد<نافذة>
Chrome 88 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
remove()
chrome.windows.remove(
windowId: number,
callback?: function,
)
إزالة (إغلاق) نافذة وجميع علامات التبويب الموجودة بداخلها.
المَعلمات
-
windowId
الرقم
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:() => void
المرتجعات
-
Promise<void>
Chrome 88 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
update()
chrome.windows.update(
windowId: number,
updateInfo: object,
callback?: function,
)
لتعديل خصائص النافذة حدِّد فقط الخصائص التي سيتم تغييرها، ولم تتغيّر الخصائص غير المحدّدة.
المَعلمات
-
windowId
الرقم
-
updateInfo
عنصر
-
drawAttention
منطقية اختيارية
إذا كان السبب
true
، يؤدي إلى عرض النافذة بطريقة تلفت انتباه المستخدم إلى النافذة، بدون تغيير النافذة محل التركيز. ويستمر التأثير إلى أن يغيِّر المستخدم التركيز إلى النافذة. ليس لهذا الخيار أي تأثير إذا كان التركيز على النافذة من قبل. اضبط السمة علىfalse
لإلغاء طلب "drawAttention
" سابق. -
تركيز
منطقية اختيارية
في حال استخدام
true
، يؤدي إلى عرض النافذة في الأمام، ولا يمكن دمج هذا الخيار مع الحالة "تصغير". في حال استخدامfalse
، يؤدي إلى نقل النافذة التالية بالترتيب z إلى الأمام، ولا يمكن دمج هذا الخيار مع الحالة "ملء الشاشة" أو "تكبير". -
الطول
الرقم اختياري
الارتفاع المراد تغيير حجم النافذة إليه بالبكسل. يتم تجاهل هذه القيمة بالنسبة إلى اللوحات.
-
في يمين الصورة
الرقم اختياري
الإزاحة من الحافة اليسرى للشاشة لنقل النافذة إليها بالبكسل يتم تجاهل هذه القيمة بالنسبة إلى اللوحات.
-
state
WindowState اختيارية
الحالة الجديدة للنافذة. لا يمكن دمج حالات "تصغير" و"تكبير" و"ملء الشاشة" مع "يسار" أو "أعلى" أو "عرض" أو "ارتفاع".
-
في أعلى الصورة
الرقم اختياري
الإزاحة من الحافة العلوية من الشاشة لنقل النافذة إليها بالبكسل. يتم تجاهل هذه القيمة بالنسبة إلى اللوحات.
-
العرض
الرقم اختياري
العرض المطلوب تغيير حجم النافذة إليه بالبكسل. يتم تجاهل هذه القيمة بالنسبة إلى اللوحات.
-
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(window: Window) => void
-
نافذة
-
المرتجعات
-
الوعد<نافذة>
Chrome 88 والإصدارات الأحدثتتوفّر الوعود في إصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير عمليات معاودة الاتصال من أجل التوافق مع الأنظمة القديمة. لا يمكنك استخدام كليهما في نفس استدعاء الدالة. يتم حل الوعد بنفس النوع الذي يتم تمريره إلى معاودة الاتصال.
فعاليات
onBoundsChanged
chrome.windows.onBoundsChanged.addListener(
callback: function,
)
يتم تنشيطها عند تغيير حجم نافذة، ويتم إرسال هذا الحدث فقط عند تطبيق الحدود الجديدة، وليس مع التغييرات الجارية.
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(window: Window) => void
-
نافذة
-
onCreated
chrome.windows.onCreated.addListener(
callback: function,
filters?: object,
)
يتم تنشيطها عند إنشاء نافذة.
المَعلمات
-
معاودة الاتصال
الوظيفة
Chrome 46 والإصدارات الأحدثتبدو معلَمة
callback
على النحو التالي:(window: Window) => void
-
نافذة
تفاصيل النافذة التي تم إنشاؤها
-
-
الفلاتر
الكائن اختياري
-
windowTypes
يجب أن يستوفي نوع النافذة التي يتم إنشاؤها الشروط التي يجب أن يستوفيها. وفقًا للإعدادات التلقائية، تتوافق مع
['normal', 'popup']
.
-
onFocusChanged
chrome.windows.onFocusChanged.addListener(
callback: function,
filters?: object,
)
يتم تنشيطها عندما تتغير النافذة محل التركيز حاليًا. تعرض chrome.windows.WINDOW_ID_NONE
إذا فقدت جميع نوافذ Chrome التركيز. ملاحظة: في بعض مدراء النوافذ في نظام التشغيل Linux، يتم دائمًا إرسال الحقل WINDOW_ID_NONE
مباشرةً قبل عملية التبديل من نافذة Chrome إلى نافذة أخرى.
المَعلمات
-
معاودة الاتصال
الوظيفة
Chrome 46 والإصدارات الأحدثتبدو معلَمة
callback
على النحو التالي:(windowId: number) => void
-
windowId
الرقم
رقم تعريف النافذة التي يتم التركيز عليها حديثًا.
-
-
الفلاتر
الكائن اختياري
-
windowTypes
يجب أن تستوفي الشروط التي يجب أن يستوفيها نوع النافذة التي تتم إزالتها. وفقًا للإعدادات التلقائية، تتوافق مع
['normal', 'popup']
.
-
onRemoved
chrome.windows.onRemoved.addListener(
callback: function,
filters?: object,
)
يتم تنشيطها عند إزالة نافذة (إغلاقها).
المَعلمات
-
معاودة الاتصال
الوظيفة
Chrome 46 والإصدارات الأحدثتبدو معلَمة
callback
على النحو التالي:(windowId: number) => void
-
windowId
الرقم
رقم تعريف النافذة التي تمت إزالتها.
-
-
الفلاتر
الكائن اختياري
-
windowTypes
يجب أن تستوفي الشروط التي يجب أن يستوفيها نوع النافذة التي تتم إزالتها. وفقًا للإعدادات التلقائية، تتوافق مع
['normal', 'popup']
.
-