chrome.contextMenus

คำอธิบาย

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

สิทธิ์

contextMenus

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

{
  "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 ของ contextMenus จากที่เก็บ chrome-extension-samples

ประเภท

ContextType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"วิดีโอ"

"audio"

"launcher"

"browser_action"

"page_action"

"action"

CreateProperties

Chrome 123 ขึ้นไป

พร็อพเพอร์ตี้ของรายการใหม่ในเมนูตามบริบท

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

  • เลือกแล้ว

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

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

  • บริบท

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

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

  • documentUrlPatterns

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

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

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

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

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

  • id

    สตริง ไม่บังคับ

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

  • parentId

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

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

  • targetUrlPatterns

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

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

  • title

    สตริง ไม่บังคับ

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

  • ประเภท

    ItemType ไม่บังคับ

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

  • มองเห็นได้

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

    เลือกว่าจะให้รายการแสดงในเมนูหรือไม่

  • onclick

    void optional

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

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

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

    • ข้อมูล

      OnClickData

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

    • แท็บ

      แท็บ

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

ItemType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"ปกติ"

"ช่องทำเครื่องหมาย"

"radio"

"separator"

OnClickData

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

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

  • เลือกแล้ว

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

    แฟล็กที่ระบุสถานะของช่องทำเครื่องหมายหรือรายการตัวเลือกหลังจากคลิก

  • แก้ไขได้

    บูลีน

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

  • frameId

    หมายเลข ไม่บังคับ

    Chrome 51 ขึ้นไป

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

  • frameUrl

    สตริง ไม่บังคับ

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

  • linkUrl

    สตริง ไม่บังคับ

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

  • mediaType

    สตริง ไม่บังคับ

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

  • menuItemId

    สตริง | ตัวเลข

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

  • pageUrl

    สตริง ไม่บังคับ

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

  • parentMenuItemId

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

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

  • selectionText

    สตริง ไม่บังคับ

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

  • srcUrl

    สตริง ไม่บังคับ

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

  • wasChecked

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

    แฟล็กที่ระบุสถานะของช่องทำเครื่องหมายหรือรายการตัวเลือกก่อนที่จะมีการคลิก

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

ACTION_MENU_TOP_LEVEL_LIMIT

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

ค่า

6

เมธอด

create()

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

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

พารามิเตอร์

  • createProperties

    CreateProperties

  • callback

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

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

    () => void

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

  • number | string

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

remove()

chrome.contextMenus.remove(
  menuItemId: string | number,
): Promise<void>

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

พารามิเตอร์

  • menuItemId

    สตริง | ตัวเลข

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

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

  • Promise<void>

    Chrome 123 ขึ้นไป

removeAll()

chrome.contextMenus.removeAll(): Promise<void>

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

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

  • Promise<void>

    Chrome 123 ขึ้นไป

update()

chrome.contextMenus.update(
  id: string | number,
  updateProperties: object,
): Promise<void>

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

พารามิเตอร์

  • id

    สตริง | ตัวเลข

    รหัสของสินค้าที่จะอัปเดต

  • updateProperties

    ออบเจ็กต์

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

    • เลือกแล้ว

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

    • บริบท

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

    • documentUrlPatterns

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

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

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

    • parentId

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

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

    • targetUrlPatterns

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

    • title

      สตริง ไม่บังคับ

    • ประเภท

      ItemType ไม่บังคับ

    • มองเห็นได้

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

      Chrome 62 ขึ้นไป

      เลือกว่าจะให้รายการแสดงในเมนูหรือไม่

    • onclick

      void optional

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

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

      • ข้อมูล

        OnClickData

        Chrome 44 ขึ้นไป
      • แท็บ

        แท็บ

        Chrome 44 ขึ้นไป

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

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

  • Promise<void>

    Chrome 123 ขึ้นไป

กิจกรรม

onClicked

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

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