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.

تعداد

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

تعداد

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

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

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

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

WindowType

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

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

تعداد

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