chrome.permissions

คำอธิบาย

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

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

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

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

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

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

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

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

ขั้นตอนที่ 1: เลือกสิทธิ์ที่จําเป็นและไม่จําเป็น

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

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

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

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

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

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

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

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

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

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

สิทธิ์ที่ไม่ได้ระบุไว้ว่าไม่บังคับ

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

สิทธิ์ คำอธิบาย
"debugger" API chrome.debugger ทำหน้าที่เป็นช่องทางการนำส่งสำรองสำหรับโปรโตคอลการแก้ไขข้อบกพร่องจากระยะไกลของ Chrome
"declarativeNetRequest" ให้สิทธิ์เข้าถึง chrome.declarativeNetRequest API แก่ส่วนขยาย
"devtools" อนุญาตให้ส่วนขยายขยายฟังก์ชันของ Chrome DevTools
"geolocation" อนุญาตให้ส่วนขยายใช้ Geolocation API ของ HTML5
"mdns" ให้สิทธิ์เข้าถึง chrome.mdns API แก่ส่วนขยาย
"proxy" ให้สิทธิ์เข้าถึง chrome.proxy API แก่ส่วนขยายเพื่อจัดการการตั้งค่าพร็อกซีของ 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

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

  • ต้นกำเนิด

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

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

  • สิทธิ์

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

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

เมธอด

addHostAccessRequest()

Promise รอดำเนินการMV3 ขึ้นไป 
chrome.permissions.addHostAccessRequest(
  request: object,
  callback?: function,
)

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

พารามิเตอร์

  • ส่งคำขอ

    ออบเจ็กต์

    • documentId

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

      รหัสของเอกสารที่แสดงคำขอเข้าถึงโฮสต์ได้ ต้องเป็นเอกสารระดับบนสุดภายในแท็บ หากระบุไว้ คำขอจะแสดงในแท็บของเอกสารที่ระบุและจะถูกนำออกเมื่อเอกสารไปยังต้นทางใหม่ การเพิ่มคำขอใหม่จะลบล้างคำขอที่มีอยู่สำหรับ tabId ต้องระบุค่านี้หรือ tabId

    • รูปแบบ

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

      รูปแบบ URL ที่แสดงคำขอสิทธิ์เข้าถึงโฮสต์ได้ หากระบุไว้ คำขอการเข้าถึงโฮสต์จะแสดงใน URL ที่ตรงกับรูปแบบนี้เท่านั้น

    • tabId

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

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

  • Callback

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

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

    () => void

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

  • Promise<void>

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

contains()

สัญญา 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

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

พารามิเตอร์

  • สิทธิ์

    สิทธิ์

  • Callback

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

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

    (result: boolean) => void

    • ผลลัพธ์

      บูลีน

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

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

  • Promise<boolean>

    Chrome 96 ขึ้นไป

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

getAll()

สัญญา 
chrome.permissions.getAll(
  callback?: function,
)

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

พารามิเตอร์

  • Callback

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

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

    (permissions: Permissions) => void

    • สิทธิ์

      สิทธิ์

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

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

  • Promise<Permissions>

    Chrome 96 ขึ้นไป

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

remove()

สัญญา 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

นำสิทธิ์เข้าถึงที่ระบุออก หากพบปัญหาในการนําสิทธิ์ออก ระบบจะตั้งค่า runtime.lastError

พารามิเตอร์

  • สิทธิ์

    สิทธิ์

  • Callback

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

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

    (removed: boolean) => void

    • ลบแล้ว

      บูลีน

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

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

  • Promise<boolean>

    Chrome 96 ขึ้นไป

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

removeHostAccessRequest()

Promise รอดำเนินการMV3 ขึ้นไป 
chrome.permissions.removeHostAccessRequest(
  request: object,
  callback?: function,
)

นำคำขอเข้าถึงของโฮสต์ออก (หากมี)

พารามิเตอร์

  • ส่งคำขอ

    ออบเจ็กต์

    • documentId

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

      รหัสของเอกสารที่จะนำคำขอสิทธิ์เข้าถึงโฮสต์ออก ต้องเป็นเอกสารระดับบนสุดภายในแท็บ ต้องระบุค่านี้หรือ tabId

    • รูปแบบ

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

      รูปแบบ URL ที่ระบบจะนำคำขอเข้าถึงของโฮสต์ออก หากระบุค่านี้ ค่าต้องตรงกับรูปแบบของคำขอสิทธิ์เข้าถึงโฮสต์ที่มีอยู่ทุกประการ

    • tabId

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

      รหัสของแท็บที่จะนำคำขอเข้าถึงของโฮสต์ออก ต้องระบุค่านี้หรือ documentId

  • Callback

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

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

    () => void

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

  • Promise<void>

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

request()

สัญญา 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

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

พารามิเตอร์

  • สิทธิ์

    สิทธิ์

  • Callback

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

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

    (granted: boolean) => void

    • อนุญาต

      บูลีน

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

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

  • Promise<boolean>

    Chrome 96 ขึ้นไป

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

กิจกรรม

onAdded

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (permissions: Permissions) => void

onRemoved

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (permissions: Permissions) => void