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"
  },
  ...
}

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

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

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

ตัวอย่าง

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

ประเภท

ContextType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"ทั้งหมด"

"page"

"frame"

"selection"

"ลิงก์"

"แก้ไขได้"

"รูปภาพ"

"วิดีโอ"

"เสียง"

"launcher"

"browser_action"

"page_action"

"การกระทำ"

CreateProperties

Chrome 123 ขึ้นไป

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

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

  • เลือกไว้

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

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

  • บริบท

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

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

  • documentUrlPatterns

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

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

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

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

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

  • id

    string ไม่บังคับ

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

  • parentId

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

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

  • targetUrlPatterns

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

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

  • title

    string ไม่บังคับ

    ข้อความที่จะแสดงในรายการ ต้องระบุเว้นแต่ type คือ separator เมื่อบริบทคือ selection ให้ใช้ %s ภายในสตริงเพื่อแสดงข้อความที่เลือก เช่น หากค่าของพารามิเตอร์นี้คือ "แปล "%s" to Pig Latin" และผู้ใช้เลือกคำว่า "เย็น" รายการเมนูตามบริบทสำหรับการเลือกจะเป็น "แปลคำว่า "น่าสนใจ" 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 | หมายเลข

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

  • pageUrl

    string ไม่บังคับ

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

  • parentMenuItemId

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

    รหัสหลักสำหรับรายการที่ถูกคลิก (หากมี)

  • selectionText

    string ไม่บังคับ

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

  • srcUrl

    string ไม่บังคับ

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

  • wasChecked

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

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

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

ACTION_MENU_TOP_LEVEL_LIMIT

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

ค่า

6

เมธอด

create()

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

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

พารามิเตอร์

  • createProperties

    CreateProperties

  • Callback

    ไม่บังคับ

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

    () => void

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

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

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

remove()

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

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

พารามิเตอร์

  • menuItemId

    string | หมายเลข

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

  • Callback

    ไม่บังคับ

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

    () => void

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

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

    Chrome 123 ขึ้นไป

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

removeAll()

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

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

พารามิเตอร์

  • Callback

    ไม่บังคับ

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

    () => void

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

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

    Chrome 123 ขึ้นไป

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

update()

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

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

พารามิเตอร์

  • id

    string | หมายเลข

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

  • updateProperties

    ออบเจ็กต์

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

    • เลือกไว้

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

    • บริบท

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

    • documentUrlPatterns

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

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

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

    • parentId

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

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

    • targetUrlPatterns

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

    • title

      string ไม่บังคับ

    • ประเภท

      ItemType ไม่บังคับ

    • มองเห็นได้

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

      Chrome 62 ขึ้นไป

      รายการจะปรากฏในเมนูหรือไม่

    • onclick

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

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

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

      • ข้อมูล

        OnClickData

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

        แท็บ

        Chrome 44 ขึ้นไป

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

  • Callback

    ไม่บังคับ

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

    () => void

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

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

    Chrome 123 ขึ้นไป

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

กิจกรรม

onClicked

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

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