chrome.contextMenus

คำอธิบาย

ใช้ chrome.contextMenus API เพื่อเพิ่มรายการลงในเมนูตามบริบทของ Google Chrome คุณเลือกได้ประเภทของวัตถุที่จะใช้เพิ่มเมนูตามบริบท เช่น รูปภาพ ไฮเปอร์ลิงก์ และหน้า

สิทธิ์

contextMenus

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

{
  "name": "My extension",
  ...
  "permissions": [
    "contextMenus"
  ],
  "icons": {
    "16": "icon-bitty.png",
    "48": "icon-small.png",
    "128": "icon-large.png"
  },
  ...
}

แนวคิดและการใช้งาน

รายการเมนูตามบริบทจะปรากฏในเอกสารใดก็ได้ (หรือเฟรมภายในเอกสาร) แม้กระทั่งรายการที่มี URL รูปแบบ file:// หรือ chrome:// หากต้องการควบคุมว่าจะให้รายการปรากฏในเอกสารใดบ้าง ให้ระบุช่อง documentUrlPatterns เมื่อเรียกใช้เมธอด create() หรือ update()

คุณสามารถสร้างรายการเมนูตามบริบทได้มากเท่าที่ต้องการ แต่หากมองเห็นรายการจากส่วนขยายมากกว่า 1 รายการพร้อมกัน Google Chrome จะยุบรายการในเมนูหลักรายการเดียวโดยอัตโนมัติ

ตัวอย่าง

หากต้องการลองใช้ API นี้ ให้ติดตั้งตัวอย่าง API บริบทเมนู จากที่เก็บ chrome-extension-ตัวอย่าง

ประเภท

ContextType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"page_action"

CreateProperties

Chrome 123 ขึ้นไป

คุณสมบัติของรายการเมนูตามบริบทใหม่

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

  • เลือกไว้

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

    สถานะเริ่มต้นของช่องทำเครื่องหมายหรือปุ่มตัวเลือก: true สำหรับรายการที่เลือก false หากไม่ได้เลือก โดยเลือกปุ่มตัวเลือกได้ทีละปุ่มเท่านั้นในกลุ่ม

  • บริบท

    [ContextType,...ContextType[]] ไม่บังคับ

    รายการบริบทที่รายการในเมนูนี้จะปรากฏ ค่าเริ่มต้นคือ ['page']

  • documentUrlPatterns

    string[] ไม่บังคับ

    จำกัดรายการให้ใช้กับเอกสารหรือเฟรมที่มี URL ตรงกับรูปแบบที่ระบุเท่านั้น โปรดดูรายละเอียดเกี่ยวกับรูปแบบลายที่จับคู่รูปแบบ

  • เปิดใช้อยู่

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

    เปิดใช้หรือปิดใช้รายการเมนูตามบริบทนี้ ค่าเริ่มต้นคือ true

  • id

    string ไม่บังคับ

    รหัสที่ไม่ซ้ำกันที่จะกำหนดให้กับรายการนี้ จำเป็นสำหรับหน้ากิจกรรม ต้องไม่เหมือนกับรหัสอื่นสำหรับส่วนขยายนี้

  • parentId

    string|number ไม่บังคับ

    รหัสของรายการในเมนูหลัก ซึ่งทำให้รายการนั้นเป็นรายการย่อยของรายการที่เพิ่มไว้ก่อนหน้านี้

  • targetUrlPatterns

    string[] ไม่บังคับ

    คล้ายกับ documentUrlPatterns ตัวกรองที่ยึดตามแอตทริบิวต์ src ของแท็ก img audio และ video และแอตทริบิวต์ href ของแท็ก a

  • title

    string ไม่บังคับ

    ข้อความที่จะแสดงในรายการ ซึ่งต้องระบุเว้นแต่ type จะเป็น separator เมื่อบริบทคือ selection ให้ใช้ %s ภายในสตริงเพื่อแสดงข้อความที่เลือก ตัวอย่างเช่น หากค่าของพารามิเตอร์นี้คือ "แปล "%s" เป็น Pig Latin" และผู้ใช้เลือกคำว่า "cool" รายการเมนูตามบริบทสำหรับการเลือกไว้จะเป็น "แปล 'cool' เป็น Pig Latin"

  • ประเภท

    ItemType ไม่บังคับ

    ประเภทของรายการในเมนู ค่าเริ่มต้นคือ normal

  • มองเห็นได้

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

    รายการแสดงในเมนูหรือไม่

  • onclick

    เป็นโมฆะ ไม่บังคับ

    ฟังก์ชันที่เรียกกลับมาเมื่อมีการคลิกรายการในเมนู ขั้นตอนนี้ไม่พร้อมใช้งานภายใน Service Worker คุณควรลงทะเบียน Listener สำหรับ contextMenus.onClicked แทน

    ฟังก์ชัน onclick มีลักษณะดังนี้ 

    (info: OnClickData,tab: Tab)=> {...}

    • ข้อมูล

      OnClickData

      ข้อมูลเกี่ยวกับรายการที่คลิกและบริบทที่เกิดการคลิก

    • รายละเอียดของแท็บที่เกิดการคลิก ไม่มีพารามิเตอร์นี้สำหรับแอปแพลตฟอร์ม

ItemType

Chrome 44 ขึ้นไป

ประเภทของรายการในเมนู

ค่าแจกแจง

OnClickData

ข้อมูลที่ส่งเมื่อมีการคลิกรายการในเมนูตามบริบท

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

  • เลือกไว้

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

    ธงแสดงสถานะของช่องทำเครื่องหมายหรือรายการวิทยุหลังจากคลิก

  • แก้ไขได้

    boolean

    ธงระบุว่าองค์ประกอบนั้นแก้ไขได้หรือไม่ (การป้อนข้อความ พื้นที่ข้อความ ฯลฯ)

  • frameId

    ตัวเลข ไม่บังคับ

    Chrome 51 ขึ้นไป

    รหัสของเฟรมขององค์ประกอบที่มีการคลิกเมนูตามบริบทหากอยู่ในเฟรม

  • frameUrl

    string ไม่บังคับ

    URL ของเฟรมขององค์ประกอบที่มีการคลิกเมนูตามบริบทหากอยู่ในเฟรม

  • linkUrl

    string ไม่บังคับ

    หากองค์ประกอบเป็นลิงก์ URL ที่องค์ประกอบนั้นชี้ไป

  • mediaType

    string ไม่บังคับ

    เช่น "รูปภาพ" "วิดีโอ" หรือ "เสียง" หากเปิดใช้งานเมนูตามบริบทในองค์ประกอบอย่างใดอย่างหนึ่งเหล่านี้

  • menuItemId

    string|number

    รหัสของรายการในเมนูที่มีการคลิก

  • pageUrl

    string ไม่บังคับ

    URL ของหน้าเว็บที่มีการคลิกรายการในเมนู พร็อพเพอร์ตี้นี้ไม่ได้ตั้งค่าหากการคลิกเกิดขึ้นในบริบทที่ไม่มีหน้าปัจจุบัน เช่น ในเมนูตามบริบทของ Launcher

  • parentMenuItemId

    string|number ไม่บังคับ

    รหัสระดับบนสุด (หากมี) ของรายการที่คลิก

  • selectionText

    string ไม่บังคับ

    ข้อความสำหรับการเลือกบริบท (หากมี)

  • srcUrl

    string ไม่บังคับ

    จะปรากฏสำหรับองค์ประกอบที่มี URL "src"

  • wasChecked

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

    ธงแสดงสถานะของช่องทำเครื่องหมายหรือรายการวิทยุก่อนที่จะคลิก

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

ACTION_MENU_TOP_LEVEL_LIMIT

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

ค่า

6

วิธีการ

create()

chrome.contextMenus.create(
  createProperties: CreateProperties,
  callback?: function,
)

สร้างรายการเมนูตามบริบทใหม่ หากเกิดข้อผิดพลาดระหว่างการสร้าง ระบบอาจตรวจไม่พบข้อผิดพลาดจนกว่าการเรียกกลับของการสร้างจะเริ่มทำงาน รายละเอียดจะอยู่ใน runtime.lastError

พารามิเตอร์

  • createProperties

    CreateProperties

  • Callback

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

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

    ()=>void

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

  • number|string

    รหัสของรายการที่สร้างขึ้นใหม่

remove()

สัญญา 
chrome.contextMenus.remove(
  menuItemId: string|number,
  callback?: function,
)

นำรายการเมนูตามบริบทออก

พารามิเตอร์

  • menuItemId

    string|number

    รหัสของรายการเมนูตามบริบทที่จะนำออก

  • Callback

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

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

    ()=>void

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

  • Promise<void>

    Chrome 123 ขึ้นไป

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

removeAll()

สัญญา 
chrome.contextMenus.removeAll(
  callback?: function,
)

นำรายการเมนูตามบริบททั้งหมดที่ส่วนขยายนี้เพิ่มเข้ามาออก

พารามิเตอร์

  • Callback

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

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

    ()=>void

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

  • Promise<void>

    Chrome 123 ขึ้นไป

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

update()

สัญญา 
chrome.contextMenus.update(
  id: string|number,
  updateProperties: object,
  callback?: function,
)

อัปเดตรายการเมนูตามบริบทที่สร้างไว้ก่อนหน้านี้

พารามิเตอร์

  • id

    string|number

    รหัสของรายการที่จะอัปเดต

  • updateProperties

    ออบเจ็กต์

    พร็อพเพอร์ตี้ที่จะอัปเดต ยอมรับค่าเดียวกันกับฟังก์ชัน contextMenus.create

    • เลือกไว้

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

    • บริบท

      [ContextType,...ContextType[]] ไม่บังคับ

    • documentUrlPatterns

      string[] ไม่บังคับ

    • เปิดใช้อยู่

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

    • parentId

      string|number ไม่บังคับ

      รหัสของรายการที่จะตั้งให้เป็นรายการหลักของรายการนี้ หมายเหตุ: คุณไม่สามารถตั้งค่ารายการให้เป็นรายการย่อยของรายการสืบทอดนั้นได้

    • targetUrlPatterns

      string[] ไม่บังคับ

    • title

      string ไม่บังคับ

    • ประเภท

      ItemType ไม่บังคับ

    • มองเห็นได้

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

      Chrome 62 ขึ้นไป

      รายการแสดงในเมนูหรือไม่

    • onclick

      เป็นโมฆะ ไม่บังคับ

      ฟังก์ชัน onclick มีลักษณะดังนี้ 

      (info: OnClickData,tab: Tab)=> {...}

      • ข้อมูล

        OnClickData

        Chrome 44 ขึ้นไป
      • Chrome 44 ขึ้นไป

        รายละเอียดของแท็บที่เกิดการคลิก ไม่มีพารามิเตอร์นี้สำหรับแอปแพลตฟอร์ม

  • Callback

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

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

    ()=>void

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

  • Promise<void>

    Chrome 123 ขึ้นไป

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

กิจกรรม

onClicked

chrome.contextMenus.onClicked.addListener(
  callback: function,
)

เริ่มทำงานเมื่อมีการคลิกรายการในเมนูตามบริบท

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (info: OnClickData,tab?: tabs.Tab)=>void