chrome.windows

الوصف

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

البيان

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

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

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

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

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

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

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

أمثلة

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

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

الأنواع

CreateType

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

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

Enum

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

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

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

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 اختيارية

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

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

    Tab[] اختياري

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

  • العلوية

    number اختياري

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

  • النوع

    ‫WindowType اختياري

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

  • العرض

    number اختياري

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

WindowState

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

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

Enum

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

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

"maximized"
حالة النافذة في وضع التكبير

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

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

WindowType

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

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

Enum

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

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

"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'].