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(). النافذة الحالية هي النافذة التي تحتوي على الصفحة التي أجرت الطلب، بغض النظر عن النافذة الأعلى.

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

أمثلة

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

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

الأنواع

CreateType

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

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

تعداد

"normal"
تحدّد هذه السمة النافذة كنافذة عادية.

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

"panel"
تحدّد هذه السمة النافذة على أنّها لوحة.

QueryOptions

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

الخصائص

  • تعبئة

    boolean اختياري

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

    سلسلة اختيارية

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

  • الولاية

    WindowState اختيارية

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

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

    علامة التبويب[] اختيارية

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

  • العلوية

    number اختياري

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

  • النوع

    ‫WindowType اختيارية

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

  • العرض

    number اختياري

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

WindowState

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

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

تعداد

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

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

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

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

WindowType

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

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

تعداد

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

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

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

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

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

الخصائص

WINDOW_ID_CURRENT

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

القيمة

-2

WINDOW_ID_NONE

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

القيمة

-1

الطُرق

create()

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

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

المعلمات

  • createData

    كائن اختياري

    • التركيز

      boolean اختياري

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

    • الارتفاع

      number اختياري

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

    • incognito

      boolean اختياري

      تحديد ما إذا كان يجب أن تكون النافذة الجديدة نافذة تصفّح متخفٍ

    • لليسار

      number اختياري

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

    • setSelfAsOpener

      boolean اختياري

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

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

    • الولاية

      WindowState اختيارية

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

      تمثّل هذه السمة الحالة الأولية للنافذة. لا يمكن الجمع بين الحالات 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

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

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

    (window?: Window) => void

    • نافذة

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

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

المرتجعات

  • Promise<Window | undefined>

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

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

get()

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

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

المعلمات

  • windowId

    الرقم

  • queryOptions

    QueryOptions اختيارية

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

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

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

    (window: Window) => void

المرتجعات

  • Promise<Window>

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

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

getAll()

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

تعرض هذه السمة جميع النوافذ.

المعلمات

  • queryOptions

    QueryOptions اختيارية

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

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

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

    (windows: Window[]) => void

المرتجعات

  • Promise<Window[]>

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

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

getCurrent()

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

تعرض هذه السمة النافذة الحالية.

المعلمات

  • queryOptions

    QueryOptions اختيارية

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

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

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

    (window: Window) => void

المرتجعات

  • Promise<Window>

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

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

getLastFocused()

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

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

المعلمات

  • queryOptions

    QueryOptions اختيارية

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

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

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

    (window: Window) => void

المرتجعات

  • Promise<Window>

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

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

remove()

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

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

المعلمات

  • windowId

    الرقم

  • callback

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

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

    () => void

المرتجعات

  • Promise<void>

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

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

update()

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

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

المعلمات

  • windowId

    الرقم

  • updateInfo

    عنصر

    • drawAttention

      boolean اختياري

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

    • التركيز

      boolean اختياري

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

    • الارتفاع

      number اختياري

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

    • لليسار

      number اختياري

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

    • الولاية

      WindowState اختيارية

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

    • العلوية

      number اختياري

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

    • العرض

      number اختياري

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

  • callback

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

    تظهر المَعلمة 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

    دالة

    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 إلى أخرى.

المعلمات

  • callback

    دالة

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

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

    (windowId: number) => void

    • windowId

      الرقم

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

  • الفلاتر

    كائن اختياري

    • windowTypes

      WindowType[]

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

onRemoved

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

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

المعلمات

  • callback

    دالة

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

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

    (windowId: number) => void

    • windowId

      الرقم

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

  • الفلاتر

    كائن اختياري

    • windowTypes

      WindowType[]

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