chrome.windows

الوصف

استخدام واجهة برمجة التطبيقات 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.

نافذتان، لكل منهما علامة تبويب واحدة
نافذتان، تحتوي كل منهما على علامة تبويب واحدة.

الأنواع

CreateType

Chrome 44 والإصدارات الأحدث

تحدِّد هذه السياسة نوع نافذة المتصفّح التي تريد إنشاءها. تم إيقاف " Panel" نهائيًا ولا يتوفّر إلا للإضافات الحالية المدرَجة في القائمة المسموح بها على نظام التشغيل ChromeOS.

التعداد

"عادي"
يحدد هذا الإعداد النافذة كنافذة عادية.

"نافذة منبثقة"
يحدد هذا الإعداد النافذة كنافذة منبثقة.

" Panel"
يحدد هذا الإعداد النافذة على أنّها لوحة.

QueryOptions

Chrome 88 والإصدارات الأحدث

أماكن إقامة

  • تعبئة

    منطقية اختيارية

    إذا كانت القيمة "صحيح"، سيحتوي الكائن 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

Chrome 44 والإصدارات الأحدث

حالة نافذة المتصفح هذه. في بعض الحالات، قد لا يتم تخصيص سمة state لنافذة، على سبيل المثال، عند طلب البحث عن النوافذ المغلقة من واجهة برمجة تطبيقات sessions.

التعداد

"عادي"
حالة النافذة العادية (ليست مصغّرة أو مكبرة أو بملء الشاشة).

"تم تصغير الحجم"
حالة النافذة التي تم تصغيرها

"تكبير"
حالة النافذة التي تم تكبيرها

"ملء الشاشة"
حالة النافذة بملء الشاشة:

"قفل الشاشة بملء الشاشة"
حالة النافذة بملء الشاشة مقفلة. لا يمكن الخروج من حالة ملء الشاشة هذه من خلال إجراء المستخدم، وهي متاحة فقط للإضافات المُدرَجة في القائمة المسموح بها على نظام التشغيل Chrome.

WindowType

Chrome 44 والإصدارات الأحدث

يشير ذلك إلى نوع نافذة المتصفّح. في بعض الحالات، قد لا يتم تخصيص السمة 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|string[] optional

      عنوان URL أو مصفوفة من عناوين URL لفتحها كعلامات تبويب في النافذة يجب أن تتضمّن عناوين URL المؤهّلة بالكامل مخططًا، مثل "http://www.google.com" وليس "www.google.com". تُعتبر عناوين URL غير المؤهّلة بالكامل نسبية داخل الإضافة. يتم ضبط صفحة "علامة تبويب جديدة" تلقائيًا على صفحة "علامة تبويب جديدة".

    • العرض

      الرقم اختياري

      عرض النافذة الجديدة بالبكسل، بما في ذلك الإطار. وفي حال عدم تحديد قيمة، سيتم ضبط القيمة التلقائية على العرض الطبيعي.

  • معاودة الاتصال

    الدالة اختيارية

    تبدو معلَمة callback على النحو التالي: 

    (window?: Window)=>void

    • نافذة

      النافذة اختيارية

      يحتوي على تفاصيل حول النافذة التي تم إنشاؤها.

المرتجعات

  • الوعد<نافذة|غير محدّدة>

    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 86 والإصدارات الأحدث 
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

      WindowType[]

      يجب أن يستوفي نوع النافذة التي يتم إنشاؤها الشروط التي يجب أن يستوفيها. وفقًا للإعدادات التلقائية، تتوافق مع ['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

      WindowType[]

      يجب أن تستوفي الشروط التي يجب أن يستوفيها نوع النافذة التي تتم إزالتها. وفقًا للإعدادات التلقائية، تتوافق مع ['normal', 'popup'].

onRemoved

chrome.windows.onRemoved.addListener(
  callback: function,
  filters?: object,
)

يتم تنشيطها عند إزالة نافذة (إغلاقها).

المَعلمات

  • معاودة الاتصال

    الوظيفة

    Chrome 46 والإصدارات الأحدث

    تبدو معلَمة callback على النحو التالي: 

    (windowId: number)=>void

    • windowId

      الرقم

      رقم تعريف النافذة التي تمت إزالتها.

  • الفلاتر

    الكائن اختياري

    • windowTypes

      WindowType[]

      يجب أن تستوفي الشروط التي يجب أن يستوفيها نوع النافذة التي تتم إزالتها. وفقًا للإعدادات التلقائية، تتوافق مع ['normal', 'popup'].