browser.omnibox

شرح

omnibox API به شما امکان می‌دهد کلیدواژه‌ای را در نوار نشانی Google Chrome (که omnibox نیز نامیده می‌شود) ثبت کنید.

وقتی کاربر کلیدواژه افزونه شما را وارد می‌کند، کاربر شروع به تعامل صرفاً با افزونه شما می‌کند. هر کلیدزنی به افزونه شما ارسال می‌شود و می‌توانید در پاسخ پیشنهاد ارائه دهید.

پیشنهادها را می‌توان به روش‌های مختلفی با قالب‌بندی غنی ارائه کرد. وقتی کاربر پیشنهادی را می‌پذیرد، افزونه شما مطلع می‌شود و می‌تواند اقدام کند.

مانیفست

برای استفاده از این میانای برنامه‌سازی کاربردی، کلیدهای زیر باید در مانیفست اعلام شوند.

"omnibox"

برای استفاده از میانای برنامه‌سازی کاربردی omnibox، باید فیلد "omnibox.keyword" را در مانیفست اضافه کنید. همچنین باید نمادی ۱۶ در ۱۶ پیکسلی مشخص کنید که هنگام پیشنهاد دادن به کاربران برای ورود به حالت کلیدواژه در نوار نشانی نمایش داده می‌شود.

برای مثال:

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

توجه: Chrome به‌طور خودکار نسخه خاکستری نماد ۱۶×۱۶ پیکسلی شما را ایجاد می‌کند. باید نسخه تمام‌رنگی ارائه دهید تا بتوان از آن در موقعیت‌های دیگری که به رنگ نیاز دارند نیز استفاده کرد. برای مثال، میانای برنامه‌سازی کاربردی منوهای زمینه‌ای نیز از نماد ۱۶×۱۶ پیکسلی استفاده می‌کند، اما به‌صورت رنگی نمایش داده می‌شود.

مثال‌ها

برای امتحان کردن این API، نمونه omnibox API را از مخزن chrome-extension-samples نصب کنید.

انواع

DefaultSuggestResult

نتیجه پیشنهادی.

مشخصات

• description

  رشته

  نوشتاری که در منو کرکره‌ای نشانی وب نمایش داده می‌شود. می‌تواند حاوی نشانه‌گذاری XML-style برای سبک‌بندی باشد. برچسب‌های پشتیبانی‌شده عبارت‌اند از: «url» (برای نشانی وب تحت‌اللفظی)، «match» (برای برجسته کردن نوشتاری که با پُرسمان کاربر مطابقت دارد)، و «dim» (برای نوشتار راهنمای کم‌نور). سبک‌ها می‌توانند تودرتو باشند، مثلاً مطابقت کم‌نور.

DescriptionStyleType

Chrome نسخه ۴۴ و بالاتر browser.* از Chrome نسخه ۱۴۸

نوع سبک.

شمارشی

«url»

«مطابقت»

«dim»

OnInputEnteredDisposition

Chrome نسخه ۴۴ و بالاتر browser.* از Chrome نسخه ۱۴۸

وضعیت پنجره برای پُرسمان omnibox. این بافت توصیه‌شده برای نمایش نتایج است. برای مثال، اگر فرمان کادر چندمنظوره پیمایش به نشانی وب خاصی باشد، ترتیب «newForegroundTab» به این معنی است که پیمایش باید در برگه انتخاب‌شده جدیدی انجام شود.

شمارشی

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

نتیجه پیشنهادی.

مشخصات

• محتوا

  رشته

  نوشتاری که در نوار نشانی وب قرار داده می‌شود و وقتی کاربر این ورودی را انتخاب می‌کند به افزونه ارسال می‌شود.

• قابل‌حذف

  بولی اختیاری

  Chrome نسخه ۶۳ به بالا browser.* از Chrome نسخه ۱۴۸

  آیا نتیجه پیشنهادی می‌تواند توسط کاربر حذف شود.

• description

  رشته

  نوشتاری که در منو کرکره‌ای نشانی وب نمایش داده می‌شود. می‌تواند حاوی نشانه‌گذاری XML-style برای سبک‌بندی باشد. برچسب‌های پشتیبانی‌شده عبارت‌اند از: «url» (برای نشانی وب تحت‌اللفظی)، «match» (برای برجسته کردن نوشتاری که با پُرسمان کاربر مطابقت دارد)، و «dim» (برای نوشتار راهنمای کم‌نور). سبک‌ها می‌توانند تودرتو باشند، مثلاً مطابقت کم‌نور. برای نمایش پنج موجودیت ازپیش تعریف‌شده به‌عنوان نوشتار، باید از آن‌ها بگریزید: stackoverflow.com/a/1091953/89484

روش‌ها

setDefaultSuggestion()

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

توضیحات و سبک‌بندی را برای پیشنهاد پیش‌فرض تنظیم می‌کند. پیشنهاد پیش‌فرض نوشتاری است که در اولین ردیف پیشنهاد در زیر نوار نشانی وب نمایش داده می‌شود.

پارامترها

• پیشنهاد

  DefaultSuggestResult

  یک شیء SuggestResult جزئی، بدون پارامتر «محتوا».

بازگشتی‌ها

• Promise<void>

  Chrome نسخه ۱۰۰ و بالاتر browser.* از Chrome نسخه ۱۴۸

رویدادها

onDeleteSuggestion

Chrome نسخه ۶۳ به بالا browser.* از Chrome نسخه ۱۴۸

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

کاربر نتیجه پیشنهادی را حذف کرده است.

پارامترها

• تماس برگشتی

  عملکرد

  پارامتر callback به‌صورت زیر است:

  (text: string) => void

  • نوشتار

    رشته

onInputCancelled

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

کاربر جلسه ورودی کلیدواژه را بدون پذیرفتن ورودی پایان داده است.

پارامترها

• تماس برگشتی

  عملکرد

  پارامتر callback به‌صورت زیر است:

  () => void

onInputChanged

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

کاربر آنچه را در همه‌جانبه‌باکس تایپ شده است تغییر داده است.

پارامترها

• تماس برگشتی

  عملکرد

  پارامتر callback به‌صورت زیر است:

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

  • نوشتار

    رشته

  • پیشنهاد

    عملکرد

    پارامتر suggest به‌صورت زیر است:

    (suggestResults: SuggestResult[]) => void

    • suggestResults

      SuggestResult[]

      آرایه نتایج پیشنهاد

onInputEntered

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

کاربر آنچه را در همه‌جانبه‌باکس تایپ شده است پذیرفته است.

پارامترها

• تماس برگشتی

  عملکرد

  پارامتر callback به‌صورت زیر است:

  (text: string, disposition: OnInputEnteredDisposition) => void

  • نوشتار

    رشته

  • disposition

    OnInputEnteredDisposition

onInputStarted

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

کاربر با تایپ کردن کلیدواژه افزونه، جلسه ورودی کلیدواژه را شروع کرده است. تضمین می‌شود که این رویداد دقیقاً یک‌بار در هر جلسه ورودی و قبل‌از هر رویداد onInputChanged ارسال شود.

پارامترها

• تماس برگشتی

  عملکرد

  پارامتر callback به‌صورت زیر است:

  () => void