browser.omnibox

الوصف

تتيح لك واجهة برمجة التطبيقات Omnibox API تسجيل كلمة رئيسية في شريط عناوين Google Chrome، والذي يُعرف أيضًا باسم المربّع المتعدّد الاستخدامات.

لقطة شاشة تعرض اقتراحات ذات صلة بعبارة البحث "بحث Chromium"

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

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

البيان

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

"omnibox"

يجب تضمين حقل "omnibox.keyword" في ملف البيان لاستخدام واجهة برمجة التطبيقات omnibox API. يجب أيضًا تحديد رمز بحجم 16 × 16 بكسل، والذي سيتم عرضه في شريط العناوين عند اقتراح دخول المستخدمين إلى وضع الكلمة الرئيسية.

على سبيل المثال:

{
  "name": "Aaron's omnibox extension",
  "version": "1.0",
  "omnibox": { "keyword" : "aaron" },
  "icons": {
    "16": "16-full-color.png"
  },
  "background": {
    "persistent": false,
    "scripts": ["background.js"]
  }
}

أمثلة

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

الأنواع

DefaultSuggestResult

نتيجة مقترَحة

الخصائص

  • الوصف

    سلسلة

    النص الذي يظهر في القائمة المنسدلة لعنوان URL يمكن أن يحتوي على ترميز بنمط XML للتنسيق. العلامات المتوافقة هي "url" (لعنوان URL حرفي) و"match" (لتمييز النص الذي يتطابق مع طلب بحث المستخدم) و"dim" (لنص المساعدة المعتم). يمكن دمج الأنماط، مثل مطابقة معتمة.

DescriptionStyleType

الإصدار 44 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

نوع النمط

Enum

"url"

"match"

"dim"

OnInputEnteredDisposition

الإصدار 44 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

تمثّل هذه السياسة ترتيب النافذة لطلب البحث في المربّع المتعدّد الاستخدامات. هذا هو السياق المقترَح لعرض النتائج. على سبيل المثال، إذا كان أمر المربّع المتعدّد الاستخدامات هو الانتقال إلى عنوان URL معيّن، يعني الإجراء "newForegroundTab" أنّه يجب الانتقال إلى علامة تبويب جديدة محدّدة.

Enum

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

نتيجة مقترَحة

الخصائص

  • المحتوى

    سلسلة

    النص الذي يتم وضعه في شريط عناوين URL، ويتم إرساله إلى الإضافة عندما يختار المستخدم هذا الإدخال.

  • deletable

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

    الإصدار 63 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

    ما إذا كان يمكن للمستخدم حذف نتيجة الاقتراح أم لا.

  • الوصف

    سلسلة

    النص الذي يظهر في القائمة المنسدلة لعنوان URL يمكن أن يحتوي على ترميز بنمط XML للتنسيق. العلامات المتوافقة هي "url" (لعنوان URL حرفي) و"match" (لتمييز النص الذي يتطابق مع طلب بحث المستخدم) و"dim" (لنص المساعدة المعتم). يمكن دمج الأنماط، مثل مطابقة معتمة. يجب إلغاء الكيانات الخمسة المحدّدة مسبقًا لعرضها كنص: stackoverflow.com/a/1091953/89484

الطُرق

setDefaultSuggestion()

browser.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
): Promise<void>

يضبط هذا الإجراء الوصف والنمط للاقتراح التلقائي. الاقتراح التلقائي هو النص الذي يظهر في صف الاقتراح الأول أسفل شريط عناوين URL.

المعلمات

  • اقتراح

    DefaultSuggestResult

    عنصر SuggestResult جزئي، بدون المَعلمة "content".

المرتجعات

  • وعد<فراغ>

    الإصدار 100 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الفعاليات

onDeleteSuggestion

الإصدار 63 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome 
browser.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

حذف المستخدم نتيجة مقترَحة.

المعلمات

  • callback

    دالة

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

    (text: string) => void

    • نصي

      سلسلة

onInputCancelled

browser.omnibox.onInputCancelled.addListener(
  callback: function,
)

أنهى المستخدم جلسة إدخال الكلمات الرئيسية بدون قبول الإدخال.

المعلمات

  • callback

    دالة

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

    () => void

onInputChanged

browser.omnibox.onInputChanged.addListener(
  callback: function,
)

غيّر المستخدم ما تم كتابته في المربّع المتعدّد الاستخدامات.

المعلمات

  • callback

    دالة

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

    (text: string, suggest: function) => void

    • نصي

      سلسلة

    • اقتراح

      دالة

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

      (suggestResults: SuggestResult[]) => void

      • suggestResults

        SuggestResult[]

        مصفوفة نتائج الاقتراحات

onInputEntered

browser.omnibox.onInputEntered.addListener(
  callback: function,
)

قبل المستخدم ما تمت كتابته في المربّع المتعدّد الاستخدامات.

المعلمات

onInputStarted

browser.omnibox.onInputStarted.addListener(
  callback: function,
)

بدأ المستخدم جلسة إدخال كلمة رئيسية من خلال كتابة الكلمة الرئيسية للإضافة. ويتم إرسال هذا الحدث مرة واحدة بالضبط لكل جلسة إدخال، وقبل أي أحداث onInputChanged.

المعلمات

  • callback

    دالة

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

    () => void