chrome.contextMenus

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

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

สิทธิ์

contextMenus

การใช้งาน

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

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

ไฟล์ Manifest

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

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

ตัวอย่าง

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

ประเภท

ContextType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"all"

"page"

"frame"

"selection"

"link"

"editable"

"image"

"video"

"audio"

"launcher"

"action"
ใช้กับเมนูตามบริบทของการดำเนินการของส่วนขยาย (ไอคอนแถบเครื่องมือ)

"tab"
ใช้กับเมนูตามบริบทของแท็บในแนวแท็บ

CreateProperties

Chrome 123 ขึ้นไป

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

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

  • เลือกแล้ว

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

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

  • บริบท

    [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' เป็นภาษา Pig Latin" และผู้ใช้เลือกคำว่า "cool" รายการเมนูตามบริบทสำหรับการเลือกจะเป็น "แปล 'cool' เป็นภาษา Pig Latin"

  • ประเภท

    ItemType ไม่บังคับ

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

  • มองเห็นได้

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

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

  • onclick

    void ไม่บังคับ

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

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

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

    • ข้อมูล

      OnClickData

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

    • แท็บ

      Tab

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

ItemType

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"normal"

"checkbox"

"radio"

"separator"

OnClickData

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

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

  • เลือกแล้ว

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

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

  • แก้ไขได้

    บูลีน

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

  • frameId

    number ไม่บังคับ

    Chrome 51 ขึ้นไป

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

  • frameUrl

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

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

  • linkUrl

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

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

  • mediaType

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

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

  • menuItemId

    string | number

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

  • pageUrl

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

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

  • parentMenuItemId

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

    รหัสหลัก (หากมี) ของรายการที่คลิก

  • selectionText

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

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

  • srcUrl

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

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

  • wasChecked

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

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

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

ACTION_MENU_TOP_LEVEL_LIMIT

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

ค่า

6

เมธอด

create()

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

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

พารามิเตอร์

  • createProperties

    CreateProperties

  • callback

    function ไม่บังคับ

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

    () => void

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

  • number | string

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

remove()

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

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

พารามิเตอร์

  • menuItemId

    string | number

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

  • callback

    function ไม่บังคับ

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

    () => void

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

  • Promise<void>

    Chrome 123 ขึ้นไป

    แก้ไขเมื่อนำเมนูตามบริบทออกแล้ว

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

removeAll()

Promise 
chrome.contextMenus.removeAll(
  callback?: function,
): Promise<void>

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

พารามิเตอร์

  • callback

    function ไม่บังคับ

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

    () => void

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

  • Promise<void>

    Chrome 123 ขึ้นไป

    ระบบจะแก้ไขเมื่อนำออกเสร็จสมบูรณ์

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

update()

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

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

พารามิเตอร์

  • id

    string | number

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

  • updateProperties

    ออบเจ็กต์

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

    • เลือกแล้ว

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

    • บริบท

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

    • documentUrlPatterns

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

    • เปิดอยู่

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

    • parentId

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

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

    • targetUrlPatterns

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

    • title

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

    • ประเภท

      ItemType ไม่บังคับ

    • มองเห็นได้

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

      Chrome 62 ขึ้นไป

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

    • onclick

      void ไม่บังคับ

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

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

      • ข้อมูล

        OnClickData

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

        Tab

        Chrome 44 ขึ้นไป

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

  • callback

    function ไม่บังคับ

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

    () => void

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

  • Promise<void>

    Chrome 123 ขึ้นไป

    แก้ไขเมื่ออัปเดตเมนูตามบริบทแล้ว

    ระบบรองรับ Promise สำหรับ Manifest V3 ขึ้นไปเท่านั้น แพลตฟอร์มอื่นๆ ต้องใช้ Callback

กิจกรรม

onClicked

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

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

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

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