chrome.permissions

refresh date: 2026-09-25 robots: noindex

คำอธิบาย

ใช้ chrome.permissions API เพื่อขอสิทธิ์ที่ไม่บังคับซึ่งประกาศไว้ในรันไทม์แทนเวลาติดตั้ง เพื่อให้ผู้ใช้เข้าใจว่าเหตุใดจึงต้องใช้สิทธิ์และให้สิทธิ์เฉพาะที่จำเป็นเท่านั้น

ภาพรวม

คำเตือนเกี่ยวกับสิทธิ์มีไว้เพื่ออธิบายความสามารถที่ API มอบให้ แต่คำเตือนบางอย่างอาจไม่ชัดเจน Permissions API ช่วยให้นักพัฒนาแอปอธิบายคำเตือนเกี่ยวกับสิทธิ์และแนะนำฟีเจอร์ใหม่ๆ ได้อย่างค่อยเป็นค่อยไป ซึ่งจะช่วยให้ผู้ใช้ได้รู้จักส่วนขยายโดยไม่มีความเสี่ยง วิธีนี้ช่วยให้ผู้ใช้ระบุระดับการเข้าถึงที่ยินดีให้และฟีเจอร์ที่ต้องการเปิดใช้ได้

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

ปุ่มส่วนขยายที่เปิดใช้ฟีเจอร์เพิ่มเติม

การแสดงเว็บไซต์ยอดนิยมของผู้ใช้ต้องใช้สิทธิ์ topSites ซึ่งมีคำเตือนต่อไปนี้

คำเตือนเกี่ยวกับส่วนขยายสำหรับ topSites API

การใช้สิทธิ์ที่ไม่บังคับ

ขั้นตอนที่ 1: ตัดสินใจว่าสิทธิ์ใดจำเป็นและสิทธิ์ใดไม่บังคับ

ส่วนขยายสามารถประกาศสิทธิ์ทั้งแบบจำเป็นและไม่บังคับได้ โดยทั่วไป คุณควรทำดังนี้

  • ใช้สิทธิ์ที่จำเป็นเมื่อจำเป็นสำหรับฟังก์ชันพื้นฐานของส่วนขยาย
  • ใช้สิทธิ์ที่ไม่บังคับเมื่อจำเป็นสำหรับฟีเจอร์ที่ไม่บังคับในส่วนขยาย

ข้อดีของสิทธิ์ที่จำเป็น

  • ข้อความแจ้งน้อยลง: ส่วนขยายสามารถแจ้งให้ผู้ใช้ยอมรับสิทธิ์ทั้งหมดได้ในครั้งเดียว
  • การพัฒนาที่ง่ายขึ้น: รับประกันว่าสิทธิ์ที่จำเป็นจะปรากฏอยู่

ข้อดีของสิทธิ์ที่ไม่บังคับมีดังนี้

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

ขั้นตอนที่ 2: ประกาศสิทธิ์ที่ไม่บังคับในไฟล์ Manifest

ประกาศสิทธิ์ที่ไม่บังคับในไฟล์ Manifest ของส่วนขยายด้วยคีย์ optional_permissions โดยใช้รูปแบบเดียวกับช่อง permissions ดังนี้

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

หากต้องการขอโฮสต์ที่คุณค้นพบเฉพาะในรันไทม์ ให้ใส่ "https://*/*" ในช่อง optional_host_permissions ของส่วนขยาย ซึ่งช่วยให้คุณระบุต้นทางใน Permissions.origins ได้ตราบใดที่มีรูปแบบที่ตรงกัน

สิทธิ์ที่ไม่สามารถระบุเป็นไม่บังคับได้

สิทธิ์ส่วนขยาย Chrome ส่วนใหญ่สามารถระบุเป็นแบบไม่บังคับได้ โดยมีข้อยกเว้นดังต่อไปนี้

สิทธิ์ คำอธิบาย
"debugger" chrome.debugger API ทำหน้าที่เป็นตัวส่งสำรองสำหรับโปรโตคอลการแก้ไขข้อบกพร่องระยะไกลของ Chrome
"declarativeNetRequest" ให้สิทธิ์เข้าถึง chrome.declarativeNetRequest API แก่ส่วนขยาย
"devtools" อนุญาตให้ส่วนขยายขยายฟังก์ชันการทำงานของ เครื่องมือสำหรับนักพัฒนาเว็บใน Chrome
"experimental" เวอร์ชัน Canary และเวอร์ชันที่กำลังพัฒนาเท่านั้น ให้สิทธิ์เข้าถึง API chrome.experimental แก่ส่วนขยาย
"geolocation" อนุญาตให้ส่วนขยายใช้ API ตำแหน่งทางภูมิศาสตร์ของ HTML5
"mdns" ให้สิทธิ์เข้าถึง chrome.mdns API แก่ส่วนขยาย
"proxy" ให้สิทธิ์ส่วนขยายเข้าถึง API chrome.proxy เพื่อจัดการการตั้งค่าพร็อกซีของ Chrome
"tts" chrome.tts API จะเล่นการอ่านออกเสียงข้อความ (TTS) ที่สังเคราะห์ขึ้น
"ttsEngine" chrome.ttsEngine API ใช้เครื่องมืออ่านออกเสียงข้อความ (TTS) โดยใช้ส่วนขยาย
"wallpaper" ChromeOS เท่านั้น ใช้ chrome.wallpaper API เพื่อเปลี่ยนวอลเปเปอร์ ChromeOS

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

ขั้นตอนที่ 3: ขอสิทธิ์ที่ไม่บังคับ

ขอสิทธิ์จากภายในท่าทางผู้ใช้โดยใช้ permissions.request():

document.querySelector('#my-button').addEventListener('click', (event) => {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  chrome.permissions.request({
    permissions: ['tabs'],
    origins: ['https://www.google.com/']
  }, (granted) => {
    // The callback argument will be true if the user granted the permissions.
    if (granted) {
      doSomething();
    } else {
      doSomethingElse();
    }
  });
});

Chrome จะแจ้งให้ผู้ใช้ทราบหากการเพิ่มสิทธิ์ส่งผลให้เกิดข้อความเตือนที่แตกต่างจากที่ผู้ใช้เคยเห็นและยอมรับแล้ว ตัวอย่างเช่น โค้ดก่อนหน้าอาจส่งผลให้เกิดข้อความแจ้งดังนี้

ตัวอย่างข้อความแจ้งยืนยันสิทธิ์

ขั้นตอนที่ 4: ตรวจสอบสิทธิ์ปัจจุบันของส่วนขยาย

หากต้องการตรวจสอบว่าส่วนขยายมีสิทธิ์หรือชุดสิทธิ์ที่เฉพาะเจาะจงหรือไม่ ให้ใช้ permission.contains() ดังนี้

chrome.permissions.contains({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (result) => {
  if (result) {
    // The extension has the permissions.
  } else {
    // The extension doesn't have the permissions.
  }
});

ขั้นตอนที่ 5: นำสิทธิ์ออก

คุณควรนำสิทธิ์ออกเมื่อไม่ต้องการใช้แล้ว หลังจากนำสิทธิ์ออกแล้ว การเรียกใช้ permissions.request() มักจะเพิ่มสิทธิ์กลับมาโดยไม่แจ้งให้ผู้ใช้ทราบ

chrome.permissions.remove({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (removed) => {
  if (removed) {
    // The permissions have been removed.
  } else {
    // The permissions have not been removed (e.g., you tried to remove
    // required permissions).
  }
});

ประเภท

Permissions

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

  • origins

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

    รายการสิทธิ์ของโฮสต์ รวมถึงสิทธิ์ที่ระบุไว้ในคีย์ optional_permissions หรือ permissions ในไฟล์ Manifest และสิทธิ์ที่เชื่อมโยงกับสคริปต์เนื้อหา

  • สิทธิ์

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

    รายการสิทธิ์ที่มีชื่อ (ไม่รวมโฮสต์หรือต้นทาง)

เมธอด

contains()

Promise 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

ตรวจสอบว่าส่วนขยายมีสิทธิ์ที่ระบุหรือไม่

พารามิเตอร์

  • สิทธิ์

    สิทธิ์

  • callback

    function ไม่บังคับ

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

    (result: boolean) => void

    • ผลลัพธ์

      บูลีน

      True หากส่วนขยายมีสิทธิ์ที่ระบุ หากมีการระบุต้นทางเป็นทั้งสิทธิ์ที่ไม่บังคับและรูปแบบการจับคู่สคริปต์เนื้อหา ระบบจะแสดงผลเป็น false เว้นแต่จะได้รับสิทธิ์ทั้ง 2 รายการ

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

  • Promise<boolean>

    Chrome 96 ขึ้นไป

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

getAll()

Promise 
chrome.permissions.getAll(
  callback?: function,
): Promise<Permissions>

รับชุดสิทธิ์ปัจจุบันของส่วนขยาย

พารามิเตอร์

  • callback

    function ไม่บังคับ

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

    (permissions: Permissions) => void

    • สิทธิ์

      สิทธิ์

      สิทธิ์ที่ใช้งานอยู่ของส่วนขยาย โปรดทราบว่าพร็อพเพอร์ตี้ origins จะมีต้นทางที่ได้รับอนุญาตจากต้นทางที่ระบุไว้ในคีย์ permissions และ optional_permissions ในไฟล์ Manifest และต้นทางที่เชื่อมโยงกับสคริปต์เนื้อหา

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

  • Promise<Permissions>

    Chrome 96 ขึ้นไป

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

remove()

Promise 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

นำสิทธิ์เข้าถึงสิทธิ์ที่ระบุออก หากมีปัญหาในการนำสิทธิ์ออก ระบบจะปฏิเสธ Promise

พารามิเตอร์

  • สิทธิ์

    สิทธิ์

  • callback

    function ไม่บังคับ

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

    (removed: boolean) => void

    • ลบแล้ว

      บูลีน

      เป็นจริงหากนำสิทธิ์ออกแล้ว

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

  • Promise<boolean>

    Chrome 96 ขึ้นไป

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

request()

Promise 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

ขอสิทธิ์เข้าถึงสิทธิ์ที่ระบุ โดยแสดงข้อความแจ้งแก่ผู้ใช้หากจำเป็น สิทธิ์เหล่านี้ต้องกำหนดไว้ในช่อง optional_permissions ของไฟล์ Manifest หรือเป็นสิทธิ์ที่จำเป็นซึ่งผู้ใช้ระงับไว้ ระบบจะไม่สนใจเส้นทางในรูปแบบต้นทาง คุณสามารถขอชุดย่อยของสิทธิ์ต้นทางที่ไม่บังคับได้ เช่น หากระบุ *://*\/* ในส่วน optional_permissions ของไฟล์ Manifest คุณจะขอ http://example.com/ ได้ หากมีปัญหาในการขอสิทธิ์ ระบบจะปฏิเสธสัญญา

พารามิเตอร์

  • สิทธิ์

    สิทธิ์

  • callback

    function ไม่บังคับ

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

    (granted: boolean) => void

    • อนุญาต

      บูลีน

      เป็นจริงหากผู้ใช้ให้สิทธิ์ที่ระบุ

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

  • Promise<boolean>

    Chrome 96 ขึ้นไป

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

กิจกรรม

onAdded

chrome.permissions.onAdded.addListener(
  callback: function,
)

เริ่มทำงานเมื่อส่วนขยายได้รับสิทธิ์ใหม่

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (permissions: Permissions) => void

onRemoved

chrome.permissions.onRemoved.addListener(
  callback: function,
)

เริ่มทำงานเมื่อนำสิทธิ์เข้าถึงออกจากส่วนขยาย

พารามิเตอร์

  • callback

    ฟังก์ชัน

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

    (permissions: Permissions) => void