chrome.omnibox

คำอธิบาย

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

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

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

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

ไฟล์ Manifest

ต้องประกาศคีย์ต่อไปนี้ในไฟล์ Manifest เพื่อใช้ API นี้

"omnibox"

คุณต้องใส่ฟิลด์ "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"

"match"

"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()

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

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

พารามิเตอร์

  • คำแนะนำ

    DefaultSuggestResult

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

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

  • Promise<void>

    Chrome 100 ขึ้นไป

กิจกรรม

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