สำหรับนักพัฒนา

ปลั๊กอิน

สิทธิ์ของปลั๊กอิน (capabilities) — ให้ผู้ดูแลเลือกได้ว่าตำแหน่งไหนทำอะไรได้

ประกาศสิทธิ์ของปลั๊กอินใน manifest แล้วผู้ดูแลติ๊กต่อตำแหน่งได้ที่ ผู้ใช้งาน → สิทธิ์การใช้งาน — ใช้กับ route, หน้าหลังบ้าน, action, ประเภทเนื้อหา และ user.can() ในโค้ด

อ่าน 8 นาทีอัปเดตล่าสุด

ดูเป็น Markdown

ในหน้านี้

ปลั๊กอินประกาศ สิทธิ์ของตัวเอง ได้ เช่น "ดูสถิติ", "เผยแพร่เอกสาร", "แก้ API key" แล้วผู้ดูแลเว็บเลือกเองว่าตำแหน่งไหนได้สิทธิ์อะไร ที่ ผู้ใช้งาน → สิทธิ์การใช้งาน → 🔌 สิทธิ์ของปลั๊กอิน โค้ดของปลั๊กอินไม่ต้องกำหนดชื่อตำแหน่งตายตัวอีก (ใช้ได้ตั้งแต่ Anasaki Studio 2.0.6 และใช้ได้กับปลั๊กอิน JavaScript, service และ WASM)

1. ประกาศใน manifest.json#

{
  "id": "page-translate",
  "minCore": "2.0.6",
  "capabilities": [
    { "id": "manage",
      "label": { "th": "ตั้งค่าการแปลภาษา", "en": "Manage page translation" },
      "description": { "th": "เปิดหน้า แปลภาษา (ตั้งค่า) และแก้โหมด", "en": "Open the settings page and change the mode" },
      "default": ["administrator", "editor"] },
    { "id": "api_key",
      "label": { "th": "แก้ Google API Key", "en": "Change the API key" },
      "default": ["administrator"] }
  ]
}
ฟิลด์กฎ
ida-z ตัวแรก ตามด้วย a-z 0-9 _ ยาว 2–31 ตัว ไม่ซ้ำในปลั๊กอิน ชื่อเต็มของสิทธิ์คือ <id ปลั๊กอิน>.<id> เช่น page-translate.manage
label{th, en} หรือข้อความ ไม่เกิน 80 ตัวอักษร แสดงในหน้าสิทธิ์และตอนติดตั้ง
descriptionไม่บังคับ {th, en} ไม่เกิน 300 ตัวอักษร
defaultตำแหน่งที่ได้สิทธิ์นี้ตอนติดตั้งครั้งแรก (administrator editor author contributor subscriber หรือตำแหน่งที่สร้างเอง) ไม่เกิน 20

ประกาศได้ไม่เกิน 30 สิทธิ์ต่อปลั๊กอิน และ Store ตรวจกฎเดียวกันตอนอัปโหลด (Store 1.2.2 ขึ้นไป)

2. ใช้ในโค้ด#

ปลั๊กอินอ้างได้เฉพาะ สิทธิ์ของตัวเอง (<id ตัวเอง>.*) และสิทธิ์ของระบบ ถ้าอ้างสิทธิ์ของปลั๊กอินอื่น ระบบจะ error ตอนลงทะเบียน

รายการ access#

ใส่ 'cap:<สิทธิ์>' ปนกับชื่อตำแหน่งได้ ทุกตำแหน่งที่มีสิทธิ์นั้นจะผ่าน

site.adminPage('settings', { label: { th: 'แปลภาษา (ตั้งค่า)', en: 'Page Translate' }, access: ['cap:page-translate.manage'], render });
site.action('saveApiKey', { access: ['cap:page-translate.api_key'], input: { apiKey: 'text?' }, run });
site.route('GET /reports/export', { access: ['cap:reports.export', 'administrator'] }, handler);

ใช้ได้กับ site.route, site.page, site.collection, site.action, site.adminPage, site.dashboardWidget, site.adminNotice และ access.edit ของประเภทเนื้อหา ผู้ดูแลยัง override ได้ที่ โค้ดของเว็บไซต์ → สิทธิ์การเข้าถึง

ตรวจในโค้ด#

run: ({ user }) => {
  if (!user?.can('page-translate.api_key')) return { message: 'ไม่มีสิทธิ์แก้ API key', errors: { form: 'forbidden' } };
  // …
}
site.can(user, 'reports.export');   // user เป็น null → false
user.caps;                          // สิทธิ์ของระบบ + สิทธิ์ของปลั๊กอินนี้ที่ผู้ใช้มี

ปุ่มหรือฟอร์มที่ซ่อนตาม user.can() มีไว้เพื่อหน้าตาเท่านั้น ต้องตรวจสิทธิ์ซ้ำใน access หรือใน run ของ action เสมอ

ประเภทเนื้อหาของปลั๊กอิน#

site.postType('docs_doc', {
  label: { th: 'เอกสาร', en: 'Docs' },
  caps: { edit: 'docs.edit', publish: 'docs.publish' },   // ใครเขียน/แก้ และใครเผยแพร่
});
  • caps.edit แทนรายชื่อตำแหน่งเริ่มต้นของคนแก้ไข
  • caps.publish จำกัดการเผยแพร่ (ถ้าไม่ใส่ คนที่แก้ได้จะเผยแพร่ได้ด้วย) บทความที่เผยแพร่แล้วแก้หรือลบได้เฉพาะคนที่มีสิทธิ์เผยแพร่
  • REST /api/v1/posts และ db.posts บังคับตามนี้ และ GET /api/v1/post-types บอก canEdit / canPublish ของผู้ใช้ที่เรียก

ปลั๊กอินแบบ service / WASM#

  • หน้าหลังบ้าน: ตั้ง service.admin[].cap เป็น "<id ตัวเอง>.<id>"
  • ข้อมูลผู้ใช้ที่ส่งมา (header X-Anasaki-User และ body ของ plugins.call) มี user.caps ซึ่งรวมสิทธิ์ของระบบและสิทธิ์ของปลั๊กอินนี้

3. รองรับ Anasaki Studio รุ่นเก่า#

รุ่นก่อน 2.0.6 ไม่รู้จัก capabilities (ข้ามไปเฉยๆ) แต่จะไม่ยอมรับ cap: ใน access ให้ตรวจก่อนว่ามี site.can หรือไม่:

const CAPS = typeof (site as any).can === 'function';            // 2.0.6+
const ACCESS_MANAGE = CAPS ? ['cap:page-translate.manage'] : ['editor'];
site.adminPage('settings', { label: 'Page Translate', access: ACCESS_MANAGE, render });

ถ้าไม่ต้องรองรับรุ่นเก่า ให้ตั้ง "minCore": "2.0.6" ขึ้นไปแล้วใช้ cap: ตรงๆ ได้เลย

4. ตอนติดตั้ง อัปเดต และถอนการติดตั้ง#

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

5. ตั้งชื่อสิทธิ์ให้ใช้ง่าย#

  • แบ่งตามสิ่งที่คนทำ ไม่ใช่ตามหน้าจอ เช่น view (ดู), edit (แก้), publish (เผยแพร่), manage (ตั้งค่า), export
  • แยกสิทธิ์ที่เสี่ยงออกมาต่างหาก เช่น การแก้ API key หรือการลบข้อมูลทั้งหมด แล้วตั้ง default เป็น administrator อย่างเดียว
  • เขียน label และ description ให้ผู้ดูแลที่ไม่เขียนโค้ดเข้าใจ เพราะผู้ดูแลจะเห็นเฉพาะข้อความนี้ในหน้าสิทธิ์

ดูรายละเอียดทั้งหมดได้ที่ Plugin API และปลั๊กอินทางการ Docs และ Analytics เป็นตัวอย่างที่ใช้สิทธิ์ของตัวเอง