chrome.omnibox

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

Omnibox API ช่วยให้คุณลงทะเบียนคีย์เวิร์ดกับแถบที่อยู่ของ Google Chrome ซึ่งเรียกอีกอย่างว่า Omnibox ได้

ภาพหน้าจอที่แสดงคำแนะนำที่เกี่ยวข้องกับคีย์เวิร์ด "Chromium Search"

เมื่อผู้ใช้ป้อนคีย์เวิร์ดของส่วนขยาย ผู้ใช้จะเริ่มโต้ตอบกับส่วนขยายของคุณเท่านั้น ระบบจะส่งการกดแป้นแต่ละครั้งไปยังส่วนขยาย และคุณสามารถให้คำแนะนำเพื่อตอบกลับได้

คำแนะนำสามารถจัดรูปแบบได้อย่างหลากหลาย เมื่อผู้ใช้ยอมรับคำแนะนำ ส่วนขยายของคุณจะได้รับการแจ้งเตือนและดำเนินการได้

ไฟล์ Manifest

คุณต้องใส่ฟิลด์ omnibox keyword ในไฟล์ Manifest เพื่อใช้ Omnibox API นอกจากนี้ คุณควรระบุไอคอนขนาด 16x16 พิกเซล ซึ่งจะแสดงในแถบที่อยู่เมื่อแนะนำให้ผู้ใช้เข้าสู่โหมดคีย์เวิร์ด

เช่น

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

ตัวอย่าง

หากต้องการลองใช้ API นี้ ให้ติดตั้งตัวอย่าง API ของแถบอเนกประสงค์จากที่เก็บchrome-extension-samples

ประเภท

DefaultSuggestResult

ผลลัพธ์การแนะนำ

พร็อพเพอร์ตี้

  • คำอธิบาย

    สตริง

    ข้อความที่แสดงในเมนูแบบเลื่อนลงของ URL มีมาร์กอัปสไตล์ XML สำหรับการจัดรูปแบบได้ แท็กที่รองรับคือ "url" (สำหรับ URL ที่แท้จริง), "match" (สำหรับการไฮไลต์ข้อความที่ตรงกับคำค้นหาของผู้ใช้) และ "dim" (สำหรับข้อความช่วยเหลือที่จาง) โดยสามารถซ้อนสไตล์ได้ เช่น การจับคู่ที่หรี่แสง

DescriptionStyleType

Chrome 44 ขึ้นไป

ประเภทสไตล์

ค่าแจกแจง

"url"

"ตรงกัน"

"dim"

OnInputEnteredDisposition

Chrome 44 ขึ้นไป

การจัดวางหน้าต่างสำหรับการค้นหาในแถบอเนกประสงค์ นี่คือบริบทที่แนะนำในการแสดงผลลัพธ์ ตัวอย่างเช่น หากคำสั่งในแถบอเนกประสงค์คือการไปยัง URL หนึ่งๆ สถานะ "newForegroundTab" หมายความว่าการไปยังส่วนต่างๆ ควรเกิดขึ้นในแท็บใหม่ที่เลือก

ค่าแจกแจง

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

ผลลัพธ์การแนะนำ

พร็อพเพอร์ตี้

  • เนื้อหา

    สตริง

    ข้อความที่ป้อนในแถบ URL และข้อความที่จะส่งไปยังส่วนขยายเมื่อผู้ใช้เลือกรายการนี้

  • ลบได้

    บูลีน ไม่บังคับ

    Chrome 63 ขึ้นไป

    ผู้ใช้ลบผลการแนะนำได้หรือไม่

  • คำอธิบาย

    สตริง

    ข้อความที่แสดงในเมนูแบบเลื่อนลงของ URL มีมาร์กอัปสไตล์ XML สำหรับการจัดรูปแบบได้ แท็กที่รองรับคือ "url" (สำหรับ URL ที่แท้จริง), "match" (สำหรับการไฮไลต์ข้อความที่ตรงกับคำค้นหาของผู้ใช้) และ "dim" (สำหรับข้อความช่วยเหลือที่จาง) โดยสามารถซ้อนสไตล์ได้ เช่น การจับคู่ที่หรี่แสง คุณต้องหลีกเลี่ยงเอนทิตีที่กำหนดไว้ล่วงหน้า 5 รายการเพื่อแสดงเป็นข้อความ stackoverflow.com/a/1091953/89484

เมธอด

setDefaultSuggestion()

Promise 
chrome.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
  callback?: function,
): Promise<void>

กำหนดคำอธิบายและการจัดรูปแบบสำหรับคำแนะนำเริ่มต้น คำแนะนำเริ่มต้นคือข้อความที่แสดงในแถวคำแนะนำแรกใต้แถบ URL

พารามิเตอร์

  • คำแนะนำ

    DefaultSuggestResult

    ออบเจ็กต์ SuggestResult บางส่วนที่ไม่มีพารามิเตอร์ "content"

  • callback

    ฟังก์ชัน ไม่บังคับ

    Chrome 100 ขึ้นไป

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    () => void

การคืนสินค้า

  • Promise<void>

    Chrome 100 ขึ้นไป

    ระบบรองรับเฉพาะ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

กิจกรรม

onDeleteSuggestion

Chrome 63 ขึ้นไป 
chrome.omnibox.onDeleteSuggestion.addListener(
  callback: function,
)

ผู้ใช้ได้ลบผลการค้นหาที่แนะนำ

พารามิเตอร์

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    (text: string) => void

    • ข้อความ

      สตริง

onInputCancelled

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

ผู้ใช้สิ้นสุดเซสชันการป้อนคีย์เวิร์ดโดยไม่ยอมรับอินพุต

พารามิเตอร์

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    () => void

onInputChanged

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

ผู้ใช้ได้เปลี่ยนสิ่งที่พิมพ์ลงในแถบอเนกประสงค์

พารามิเตอร์

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

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

    • ข้อความ

      สตริง

    • แนะนำ

      ฟังก์ชัน

      พารามิเตอร์ suggest มีลักษณะดังนี้ 

      (suggestResults: SuggestResult[]) => void

      • suggestResults

        SuggestResult[]

        อาร์เรย์ของผลลัพธ์การแนะนำ

onInputEntered

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

ผู้ใช้ยอมรับสิ่งที่พิมพ์ลงในแถบออมนิบ็อกซ์

พารามิเตอร์

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

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

onInputStarted

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

ผู้ใช้เริ่มเซสชันการป้อนคีย์เวิร์ดโดยพิมพ์คีย์เวิร์ดของส่วนขยาย ระบบรับประกันว่าจะส่งเหตุการณ์นี้ 1 ครั้งต่อเซสชันอินพุต และก่อนเหตุการณ์ onInputChanged

พารามิเตอร์

  • callback

    ฟังก์ชัน

    พารามิเตอร์ callback มีลักษณะดังนี้ 

    () => void