chrome.omnibox

คำอธิบาย

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

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

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

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

ไฟล์ Manifest

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

"omnibox"

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

เช่น

{
  "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" (สำหรับการไฮไลต์ข้อความที่ตรงกับคำค้นหาของผู้ใช้) และ "หรี่ไฟ" (สำหรับข้อความตัวช่วยหรี่แสง) สไตล์สามารถซ้อนกันได้ ��ช่น การทำงานแบบสีจาง

DescriptionStyleType

Chrome 44 ขึ้นไป

ประเภทสไตล์

ค่าแจกแจง

"url"

"match"

"หรี่"

OnInputEnteredDisposition

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"currentTab"

"newForegroundTab"

"newBackgroundTab"

SuggestResult

ผลการค้นหาที่แนะนำ

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

  • เนื้อหา

    สตริง

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

  • ลบได้

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

    Chrome 63 ขึ้นไป

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

  • คำอธิบาย

    สตริง

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

เมธอด

setDefaultSuggestion()

สัญญา 
chrome.omnibox.setDefaultSuggestion(
  suggestion: DefaultSuggestResult,
  callback?: function,
)

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

พารามิเตอร์

  • คำแนะนำ

    DefaultSuggestResult

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

  • Callback

    ไม่บังคับ

    Chrome 100 ขึ้นไป

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

    () => void

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

  • คำมั่นสัญญา<โมฆะ>

    Chrome 100 ขึ้นไป

    รองรับคำสัญญาในไฟล์ Manifest V3 ขึ้นไป แต่จะมี Callback สำหรับ ความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 อย่างในการเรียกใช้ฟังก์ชันเดียวกันได้ จะมีการแก้ไขด้วยประเภทเดียวกันที่ส่งไปยัง Callback

กิจกรรม

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,
)

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    () => void