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

ปลั๊กอิน

สร้างปลั๊กอิน JavaScript

ปลั๊กอิน JavaScript คือ Site Code ที่แพ็กเป็นปลั๊กอิน — manifest, สิทธิ์ของโค้ด (scopes), การตั้งค่า, migration, dependencies, การแพ็ก .zip และการทดสอบ

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

ดูเป็น Markdown

ในหน้านี้

ปลั๊กอิน JavaScript ("runtime": "js") ใช้ API เดียวกับ Site Code แต่รันเป็น หน่วยแยก ของตัวเอง: มีตาราง การตั้งค่า คุกกี้ ฮุก และ route ของตัวเอง และทำได้เฉพาะสิทธิ์ที่ผู้ดูแลอนุมัติ ปลั๊กอินทางการทุกตัวก็เขียนแบบนี้ (ซอร์สอยู่ใน plugins-official/ ของ repository)

โครงสร้างแพ็กเกจ#

my-plugin/
├── manifest.json          (จำเป็น — ที่รากของ zip)
├── README.md              (แสดงในร้าน — เขียนไทย + อังกฤษ)
├── code/
│   ├── main.ts            (ไฟล์เริ่มต้น)
│   ├── lib.ts
│   └── index.d.ts         (ไม่บังคับ: type ให้ปลั๊กอินที่ import)
├── migrations/
│   └── 001_create_tables.ts
├── assets/                (css / js / รูป / ฟอนต์ ที่เสิร์ฟสาธารณะ)
└── screenshots/           (รูปสำหรับหน้าร้าน)

ไฟล์ใน code/ และ migrations/ รับ .ts .js .mjs .json .md ไม่เกิน 200 ไฟล์ ไฟล์ละ 512 KB รวม 2 MB ทั้งแพ็กเกจไม่เกิน 30 MB

manifest.json#

{
  "id": "event-booking",
  "name": "Event booking",
  "version": "1.0.0",
  "description": "จองที่นั่งอีเวนต์ / Event seat booking",
  "author": "Your name",
  "icon": "🎟",
  "category": "content",
  "license": "MIT",
  "minCore": "2.0.4",
  "runtime": "js",
  "permissions": ["code", "settings"],
  "settings": [
    { "key": "notifyEmail", "type": "text", "label": { "th": "อีเมลแจ้งเตือน", "en": "Notification email" } }
  ],
  "code": {
    "entry": "code/main.ts",
    "scopes": ["db", "routes", "mail", "admin-pages"],
    "routes": ["/booking"],
    "exports": ["seatsLeft"],
    "hooks": { "events": ["event-booking.booked"] }
  },
  "requires": { "thai": "^1.0.0" }
}
ฟิลด์หมายเหตุ
id^[a-z0-9][a-z0-9-]{2,39}$ ไม่ซ้ำ — ใช้เป็น namespace ทุกอย่าง
versionsemver — ทุกการอัปเดตต้องสูงขึ้น
minCoreเวอร์ชัน Anasaki Studio ต่ำสุดที่ติดตั้งได้
permissionsต้องมี code และ permission ของทุกฟีเจอร์ที่ใช้ (settings, bodyEnd, webhooks…)
code.entryจำเป็น ไฟล์ .ts / .js / .mjs ใน code/
code.scopesสิทธิ์ของโค้ด — เรียก API นอกสิทธิ์จะ throw
code.routesprefix ของพาธสาธารณะที่ site.route / site.page ใช้ได้ (ต้องมี scope routes) — a-z 0-9 _ - และตั้งแต่ CMS 2.2.2 มีจุดได้ เช่น /feed.xml
code.hostsโดเมนที่ http.fetch เรียกได้ (ต้องมี scope http)
code.library / code.exportsโมดูลที่ปลั๊กอินอื่น import ได้ / ฟังก์ชันที่เรียกด้วย plugins.call
code.hooksชื่อ filter / event ของตัวเอง ต้องขึ้นต้นด้วย <id>.
requires / optionalRequiresปลั๊กอินที่ต้องมี / ใช้ร่วมได้ถ้ามี (^1.2.0, ~1.2, 1.x, >=1.0.0 <2)
capabilitiesสิทธิ์ของปลั๊กอินที่ผู้ดูแลติ๊กต่อตำแหน่งได้ (ตั้งแต่ 2.0.6) — ดู สิทธิ์ของปลั๊กอิน

สิทธิ์ของโค้ด (scopes)#

db · content · content-write · content-fields · post-types (ตั้งแต่ 2.0.5) · mail · http · webhooks · visitor · routes · jobs · admin-pages · filters-core · middleware · head-scripts — ความหมายของแต่ละตัวดูที่ สิทธิ์ที่ปลั๊กอินขอ ขอเท่าที่ใช้จริง เพราะผู้ดูแลเห็นทุกตัวก่อนติดตั้ง และการขอเพิ่มในเวอร์ชันถัดไปจะทำให้ปลั๊กอินถูกปิดจนกว่าจะอนุมัติใหม่

ทุกอย่างมี namespace#

สิ่งของในปลั๊กอิน event-booking
ตารางschema.create('seats') → ตารางจริง p_event_booking_seats (ระบบเติม/ตัด prefix ให้)
การตั้งค่าsite.settings('notifyEmail') อ่านค่าจาก ปลั๊กอิน → ตั้งค่า ก่อน แล้ว โค้ดของเว็บไซต์ → ค่าลับและการตั้งค่า (ของปลั๊กอินนี้) แล้วค่า default ใน manifest
คุกกี้response.setCookie('cart', …) → ชื่อจริงขึ้นต้นด้วย pl_<id>_ — ปลั๊กอินไม่เห็นคุกกี้ของระบบหรือปลั๊กอินอื่น
action / collection/_a/event-booking:<ชื่อ> · code:event-booking:<ชื่อ>
หน้าหลังบ้าน / งานevent-booking:<ชื่อ>
ฮุกของตัวเองsite.emit('event-booking.booked', …)

ปลั๊กอินไม่ได้ db.query / schema.raw และมองไม่เห็นตารางของหน่วยอื่น

ประเภทเนื้อหาของปลั๊กอิน (ตั้งแต่ 2.0.5)#

ปลั๊กอินที่ขอ scope post-types (และตั้ง "minCore": "2.0.5") เรียก site.postType ได้เหมือน Site Code:

site.postType('docs_doc', {
  label: { th: 'เอกสาร', en: 'Docs' }, icon: '📘',
  slug: 'docs',          // ค่าเริ่มต้น = id ที่เปลี่ยน _ เป็น - (docs-doc)
  public: false,         // ระบบไม่ route /docs และ /docs/<slug> ให้ — ปลั๊กอินเสิร์ฟหน้าเอง
  fields: {
    product: { type: 'select', options: ['studio', 'store'] },
    order: 'number',
  },
});
  • id ของ type ต้องเป็น <id ของปลั๊กอินที่เปลี่ยน - เป็น _>_<ชื่อ> และยังต้องตรง ^[a-z][a-z0-9_]{1,19}$ (รวมไม่เกิน 20 ตัวอักษร) — ปลั๊กอิน docs → docs_doc ✔, docs เฉย ๆ ✘, ปลั๊กอิน event-booking → event_booking_seat ✔ ถ้ายาวเกินหรือ id ของปลั๊กอินขึ้นต้นด้วยตัวเลข การเปิดใช้จะล้มพร้อมข้อความแจ้ง
  • public: false — ระบบไม่ทำหน้ารวม /<slug> และหน้า /<slug>/<post-slug> ให้ (ค่าเริ่มต้น true) แต่ลิงก์ของโพสต์ (post.url, ปุ่ม "ดู" ในหลังบ้าน) ยังเป็น /<slug>/<post-slug> ปลั๊กอินจึงควรรับพาธนั้นเอง (เช่น redirect) — slug ตั้งให้ตรงกับ prefix ใน code.routes ของปลั๊กอินเองได้ แต่ห้ามชนกับพาธของระบบ ของปลั๊กอินอื่น หรือ slug ของ type อื่น
  • ช่องข้อมูลที่ประกาศใน fields ของ spec เก็บด้วยชื่อตรง ๆ (product, order) — ใช้ใน db.posts.list({ type: 'docs_doc', where: { 'meta.order': { gte: 1 } }, orderBy: 'meta.order' }) และได้กลับเป็น post.meta.product ส่วน site.fields(type, …) ของปลั๊กอินยังเก็บแบบ <id>.<key> (กรองด้วย where ไม่ได้) จึงควรประกาศช่องไว้ใน spec ของ type สเปกของช่อง (รวมตัวเลือกของ select) ถูกกำหนดตอนลงทะเบียน — เปลี่ยนการตั้งค่าแล้วจะมีผลเมื่อปลั๊กอินโหลดใหม่
  • อ่าน/เขียนโพสต์ของ type ด้วย db.posts ต้องมี scope content / content-write ตามปกติ หน่วยอื่น (Site Code, ปลั๊กอินอื่น) อ่านได้ แต่เขียนได้เฉพาะปลั๊กอินเจ้าของ
  • type ได้เมนูและหน้าแก้ไขในหลังบ้าน อยู่ในตัวเลือกของรายการบทความในหน้าออกแบบ และส่งออก/นำเข้าพร้อมเว็บ — ปิดหรือลบปลั๊กอินแล้วโพสต์ยังอยู่ (ซ่อนไว้) จนกว่าจะเปิดใช้อีกครั้ง

Plugin Store รองรับ scope post-types ตั้งแต่ Store 1.2.1 — อัปโหลดปลั๊กอินที่ใช้ scope นี้ขึ้น Store ได้ตามปกติ

Migration#

// migrations/001_create_tables.ts
export default migration({
  up(schema) {
    schema.create('seats', (t) => {
      t.id();
      t.string('event_slug', 191).index();
      t.string('email', 191);
      t.timestamps();
    });
  },
  down(schema) { schema.drop('seats'); },
});

ต้องมี scope db — migration รันตอนเปิดใช้และตอนอัปเกรดปลั๊กอินที่เปิดอยู่ ถ้าเป็นการเปลี่ยนแปลงที่อาจทำให้ข้อมูลหาย ผู้ดูแลต้องติ๊กยืนยัน และระบบสำรองตารางก่อน

แพ็กและทดสอบ#

  1. ตรวจ type ระหว่างเขียน: คัดลอก anasaki.d.ts (ดาวน์โหลดจากหน้าโค้ดของเว็บไซต์ หรือ anasaki-code types) มาไว้ในโฟลเดอร์
  2. zip โฟลเดอร์ (ไฟล์อยู่ที่รากของ zip หรือในโฟลเดอร์บนสุดโฟลเดอร์เดียวก็ได้)
    cd my-plugin && zip -r ../event-booking-1.0.0.zip .
  3. ในเว็บทดสอบ: ปลั๊กอิน → อัปโหลด .zip → อนุมัติสิทธิ์ → เปิดใช้งาน — ถ้าโค้ด build ไม่ผ่าน ระบบแจ้งไฟล์:บรรทัด และปลั๊กอินยังปิดอยู่
  4. ดู log ของปลั๊กอินที่ โค้ดของเว็บไซต์ → บันทึกการทำงาน (หรือ anasaki-code logs --unit event-booking)
  5. แก้แล้วเพิ่ม version และอัปโหลดใหม่ — การตั้งค่าและข้อมูลยังอยู่

มี Site Code ที่ใช้งานได้อยู่แล้ว? ปุ่ม ส่งออกเป็นปลั๊กอิน ในหน้าโค้ดของเว็บไซต์สร้าง .zip จากเวอร์ชันที่เผยแพร่อยู่ พร้อม manifest.json ที่เดา scopes, routes, exports และ requires ให้ — ตรวจแล้วแก้ก่อนส่งขึ้นร้าน

พร้อมแล้ว: สมัครและเผยแพร่ปลั๊กอิน · ตัวอย่างครบทั้งตัว: ตัวอย่างปลั๊กอิน · API ทั้งหมด: Plugin API