chrome.windows

refresh date: 2026-09-25 robots: noindex

الوصف

استخدِم واجهة برمجة التطبيقات chrome.windows للتفاعل مع نوافذ المتصفّح. يمكنك استخدام واجهة برمجة التطبيقات هذه لإنشاء النوافذ وتعديلها وإعادة ترتيبها في المتصفّح.

البيان

عند طلب windows.Window، يحتوي على مصفوفة من عناصر tabs.Tab. يجب الإعلان عن إذن "tabs" في ملف البيان إذا كنت بحاجة إلى الوصول إلى سمات url أو pendingUrl أو title أو favIconUrl في tabs.Tab. على سبيل المثال:

{
  "name": "My extension",
  ...
  "permissions": ["tabs"],
  ...
}

النافذة الحالية

تتضمّن العديد من الدوال في نظام الإضافات وسيطة windowId اختيارية، يتم ضبطها تلقائيًا على النافذة الحالية.

النافذة الحالية هي النافذة التي تحتوي على الرمز الذي يتم تنفيذه حاليًا. من المهمّ معرفة أنّ هذه النافذة قد تختلف عن النافذة في أعلى الشاشة أو النافذة التي يتم التركيز عليها.

على سبيل المثال، لنفترض أنّ إحدى الإضافات تنشئ بضع علامات تبويب أو نوافذ من ملف HTML واحد، وأنّ ملف HTML يحتوي على طلب إلى tabs.query(). النافذة الحالية هي النافذة التي تحتوي على الصفحة التي أجرت المكالمة، بغض النظر عن النافذة العلوية.

في حال استخدام مشغّلي الخدمات، تعود قيمة النافذة الحالية إلى آخر نافذة نشطة. في بعض الحالات، قد لا تكون هناك نافذة حالية لصفحات الخلفية.

أمثلة

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

لتجربة واجهة برمجة التطبيقات هذه، ثبِّت مثال واجهة برمجة التطبيقات للنوافذ من مستودع chrome-extension-samples.

الأنواع

CreateType

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

يحدّد نوع نافذة المتصفّح المطلوب إنشاؤها. تم إيقاف "panel" نهائيًا، وهي متاحة فقط للإضافات الحالية المدرَجة في القائمة المسموح بها على ChromeOS.

Enum

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

‫"popup"
يحدّد النافذة على أنّها نافذة منبثقة.

"panel"
يحدّد النافذة كلوحة.

QueryOptions

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

الخصائص

  • تعبئة

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

    إذا كانت القيمة "صحيح"، يحتوي عنصر windows.Window على سمة tabs تتضمّن قائمة بعناصر tabs.Tab. لا تحتوي عناصر Tab إلا على السمات url وpendingUrl وtitle وfavIconUrl إذا كان ملف بيان الإضافة يتضمّن الإذن "tabs".

  • windowTypes

    WindowType[] اختيارية

    في حال ضبط هذه السمة، تتم فلترة windows.Window التي يتم عرضها استنادًا إلى نوعها. في حال ترك هذه السياسة بدون ضبط، يتم ضبط الفلتر التلقائي على ['normal', 'popup'].

Window

الخصائص

  • alwaysOnTop

    قيمة منطقية

    ما إذا تم ضبط النافذة لتكون دائمًا في المقدّمة

  • مركّز

    قيمة منطقية

    يشير إلى ما إذا كانت النافذة هي النافذة محل التركيز حاليًا.

  • الارتفاع

    number اختيارية

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

  • id

    number اختيارية

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

  • incognito

    قيمة منطقية

    ما إذا كانت النافذة في وضع التصفّح المتخفي أم لا

  • لليسار

    number اختيارية

    تمثّل هذه السمة إزاحة النافذة من الحافة اليسرى للشاشة بالبكسل. في بعض الحالات، قد لا يتم تخصيص السمة left للنافذة، مثلاً عند طلب النوافذ المغلقة من واجهة برمجة التطبيقات sessions.

  • sessionId

    string اختياري

    معرّف الجلسة المستخدَم لتحديد نافذة بشكل فريد، ويتم الحصول عليه من واجهة برمجة التطبيقات sessions.

  • الولاية

    WindowState اختياري

    حالة نافذة المتصفّح هذه

  • علامات التبويب

    Tab[] اختيارية

    مصفوفة من عناصر tabs.Tab تمثّل علامات التبويب الحالية في النافذة

  • العلوية

    number اختيارية

    تمثّل هذه السمة إزاحة النافذة من الحافة العلوية للشاشة بالبكسل. في بعض الحالات، قد لا يتم تخصيص السمة top للنافذة، مثلاً عند طلب النوافذ المغلقة من واجهة برمجة التطبيقات sessions.

  • النوع

    WindowType اختيارية

    نوع نافذة المتصفّح هذه

  • العرض

    number اختيارية

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

WindowState

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

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

Enum

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

"minimized"
حالة النافذة المصغّرة

"maximized"
حالة النافذة المكبَّرة

"fullscreen"
حالة النافذة في وضع ملء الشاشة

WindowType

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

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

Enum

"normal"
نافذة متصفّح عادية

‫"popup"
نافذة منبثقة في المتصفّح

"panel"
تم إيقاف هذه السمة نهائيًا في واجهة برمجة التطبيقات هذه. نافذة على شكل لوحة لتطبيق Chrome يمكن للإضافات الاطّلاع على نوافذ اللوحات الخاصة بها فقط.

"app"
تم إيقاف هذه السمة نهائيًا في واجهة برمجة التطبيقات هذه. نافذة تطبيق Chrome يمكن للإضافات الاطّلاع على نوافذ التطبيقات الخاصة بها فقط.

‫"devtools"
نافذة "أدوات المطوّرين"

الخصائص

WINDOW_ID_CURRENT

قيمة windowId التي تمثّل النافذة الحالية

القيمة

-2

WINDOW_ID_NONE

قيمة windowId التي تمثّل عدم توفّر نافذة في متصفّح Chrome

القيمة

-1

الطُرق

create()

Promise 
chrome.windows.create(
  createData?: object,
  callback?: function,
): Promise<Window | undefined>

تنشئ (تفتح) نافذة متصفّح جديدة مع أي حجم أو موضع أو عنوان URL تلقائي اختياري.

المعلمات

  • createData

    object اختياري

    • مركّز

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

      إذا كانت القيمة true، يتم فتح نافذة نشطة. إذا كانت القيمة false، يتم فتح نافذة غير نشطة.

    • الارتفاع

      number اختيارية

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

    • incognito

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

      يشير هذا الإعداد إلى ما إذا كان يجب أن تكون النافذة الجديدة نافذة تصفُّح متخفٍ.

    • لليسار

      number اختيارية

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

    • setSelfAsOpener

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

      الإصدار 64 من Chrome أو الإصدارات الأحدث

      إذا كانت القيمة true، يتم ضبط "window.opener" للنافذة التي تم إنشاؤها حديثًا على المتصل، وتكون في وحدة سياقات التصفّح ذات الصلة نفسها التي يتوفّر فيها المتصل.

    • الولاية

      WindowState اختياري

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

      الحالة الأولية للنافذة لا يمكن دمج الحالات minimized وmaximized وfullscreen مع left أو top أو width أو height.

    • tabId

      number اختيارية

      رقم تعريف علامة التبويب المطلوب إضافتها إلى النافذة الجديدة

    • العلوية

      number اختيارية

      عدد وحدات البكسل لتحديد موضع النافذة الجديدة من الحافة العلوية للشاشة. في حال عدم تحديد هذه السمة، يتم إزاحة النافذة الجديدة بشكل طبيعي عن آخر نافذة تم التركيز عليها. يتم تجاهل هذه القيمة في اللوحات.

    • النوع

      CreateType اختياري

      يحدّد نوع نافذة المتصفّح المطلوب إنشاؤها.

    • url

      string | string[] اختيارية

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

    • العرض

      number اختيارية

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

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    (window?: Window) => void

    • نافذة

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

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

المرتجعات

  • Promise<Window | undefined>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

get()

Promise 
chrome.windows.get(
  windowId: number,
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

توفّر هذه الطريقة تفاصيل حول نافذة.

المعلمات

  • windowId

    الرقم

  • queryOptions

    QueryOptions اختياري

    الإصدار 88 من Chrome أو الإصدارات الأحدث
  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    (window: Window) => void

المرتجعات

  • Promise<Window>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

getAll()

Promise 
chrome.windows.getAll(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window[]>

للحصول على جميع النوافذ

المعلمات

  • queryOptions

    QueryOptions اختياري

    الإصدار 88 من Chrome أو الإصدارات الأحدث
  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    (windows: Window[]) => void

المرتجعات

  • Promise<Window[]>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

getCurrent()

Promise 
chrome.windows.getCurrent(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

تحصل على النافذة الحالية.

المعلمات

  • queryOptions

    QueryOptions اختياري

    الإصدار 88 من Chrome أو الإصدارات الأحدث
  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    (window: Window) => void

المرتجعات

  • Promise<Window>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

getLastFocused()

Promise 
chrome.windows.getLastFocused(
  queryOptions?: QueryOptions,
  callback?: function,
): Promise<Window>

تسترجع هذه الطريقة النافذة التي تم التركيز عليها مؤخرًا، وهي عادةً النافذة "في الأعلى".

المعلمات

  • queryOptions

    QueryOptions اختياري

    الإصدار 88 من Chrome أو الإصدارات الأحدث
  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    (window: Window) => void

المرتجعات

  • Promise<Window>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

remove()

Promise 
chrome.windows.remove(
  windowId: number,
  callback?: function,
): Promise<void>

لإزالة (إغلاق) نافذة وجميع علامات التبويب بداخلها

المعلمات

  • windowId

    الرقم

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعد<فراغ>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

update()

Promise 
chrome.windows.update(
  windowId: number,
  updateInfo: object,
  callback?: function,
): Promise<Window>

تعديل خصائص نافذة حدِّد فقط السمات التي تريد تغييرها، وستبقى السمات غير المحدّدة بدون تغيير.

المعلمات

  • windowId

    الرقم

  • updateInfo

    عنصر

    • drawAttention

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

      إذا تم ضبط السياسة على true، يتم عرض النافذة بطريقة تجذب انتباه المستخدم إليها، بدون تغيير النافذة التي يتم التركيز عليها. ويستمر التأثير إلى أن يغيّر المستخدم التركيز إلى النافذة. ولن يكون لهذا الخيار أي تأثير إذا كانت النافذة في المقدّمة. اضبط القيمة على false لإلغاء طلب drawAttention سابق.

    • مركّز

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

      إذا كانت القيمة true، يتم إحضار النافذة إلى المقدّمة، ولا يمكن دمجها مع الحالة "minimized" (تصغير). إذا كانت القيمة false، يتم إحضار النافذة التالية في ترتيب z إلى الأمام، ولا يمكن دمجها مع الحالة "ملء الشاشة" أو "مكبَّرة".

    • الارتفاع

      number اختيارية

      الارتفاع المطلوب لتغيير حجم النافذة بالبكسل يتم تجاهل هذه القيمة في اللوحات.

    • لليسار

      number اختيارية

      تمثّل هذه السمة الإزاحة من الحافة اليسرى للشاشة لنقل النافذة إليها بالبكسل. يتم تجاهل هذه القيمة في اللوحات.

    • الولاية

      WindowState اختياري

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

    • العلوية

      number اختيارية

      تمثّل هذه السمة الإزاحة من الحافة العلوية للشاشة لنقل النافذة إليها بالبكسل. يتم تجاهل هذه القيمة في اللوحات.

    • العرض

      number اختيارية

      العرض الذي سيتم تغيير حجم النافذة إليه بالبكسل يتم تجاهل هذه القيمة في اللوحات.

  • callback

    function اختياري

    تظهر المَعلمة callback على النحو التالي: 

    (window: Window) => void

المرتجعات

  • Promise<Window>

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

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، وتحتاج المنصات الأخرى إلى استخدام عمليات الاستدعاء.

الفعاليات

onBoundsChanged

الإصدار 86 من Chrome والإصدارات الأحدث 
chrome.windows.onBoundsChanged.addListener(
  callback: function,
)

يتم تشغيل هذا الحدث عند تغيير حجم نافذة، ولا يتم إرساله إلا عند تطبيق الحدود الجديدة، وليس عند إجراء تغييرات قيد التقدّم.

المعلمات

  • callback

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (window: Window) => void

onCreated

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

يتم تنشيط هذا الحدث عند إنشاء نافذة.

المعلمات

  • callback

    دالة

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

    تظهر المَعلمة callback على النحو التالي: 

    (window: Window) => void

    • نافذة

      Window

      تفاصيل النافذة التي تم إنشاؤها

  • الفلاتر

    object اختياري

    • windowTypes

      WindowType[]

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

onFocusChanged

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

يتم تنشيط هذا الحدث عند تغيير النافذة التي يتم التركيز عليها حاليًا. تعرض القيمة chrome.windows.WINDOW_ID_NONE إذا فقدت جميع نوافذ Chrome التركيز. ملاحظة: في بعض برامج إدارة النوافذ في Linux، يتم دائمًا إرسال WINDOW_ID_NONE قبل التبديل من نافذة Chrome إلى أخرى مباشرةً.

المعلمات

  • callback

    دالة

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

    تظهر المَعلمة callback على النحو التالي: 

    (windowId: number) => void

    • windowId

      الرقم

      رقم تعريف النافذة التي تم التركيز عليها حديثًا

  • الفلاتر

    object اختياري

    • windowTypes

      WindowType[]

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

onRemoved

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

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

المعلمات

  • callback

    دالة

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

    تظهر المَعلمة callback على النحو التالي: 

    (windowId: number) => void

    • windowId

      الرقم

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

  • الفلاتر

    object اختياري

    • windowTypes

      WindowType[]

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