ปลั๊กอิน
สร้างปลั๊กอิน JavaScript
ปลั๊กอิน JavaScript คือ Site Code ที่แพ็กเป็นปลั๊กอิน — manifest, สิทธิ์ของโค้ด (scopes), การตั้งค่า, migration, dependencies, การแพ็ก .zip และการทดสอบ
ในหน้านี้
ปลั๊กอิน 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 ทุกอย่าง |
version | semver — ทุกการอัปเดตต้องสูงขึ้น |
minCore | เวอร์ชัน Anasaki Studio ต่ำสุดที่ติดตั้งได้ |
permissions | ต้องมี code และ permission ของทุกฟีเจอร์ที่ใช้ (settings, bodyEnd, webhooks…) |
code.entry | จำเป็น ไฟล์ .ts / .js / .mjs ใน code/ |
code.scopes | สิทธิ์ของโค้ด — เรียก API นอกสิทธิ์จะ throw |
code.routes | prefix ของพาธสาธารณะที่ 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ต้องมี scopecontent/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 รันตอนเปิดใช้และตอนอัปเกรดปลั๊กอินที่เปิดอยู่ ถ้าเป็นการเปลี่ยนแปลงที่อาจทำให้ข้อมูลหาย ผู้ดูแลต้องติ๊กยืนยัน และระบบสำรองตารางก่อน
แพ็กและทดสอบ#
- ตรวจ type ระหว่างเขียน: คัดลอก
anasaki.d.ts(ดาวน์โหลดจากหน้าโค้ดของเว็บไซต์ หรือanasaki-code types) มาไว้ในโฟลเดอร์ - zip โฟลเดอร์ (ไฟล์อยู่ที่รากของ zip หรือในโฟลเดอร์บนสุดโฟลเดอร์เดียวก็ได้)
cd my-plugin && zip -r ../event-booking-1.0.0.zip . - ในเว็บทดสอบ: ปลั๊กอิน → อัปโหลด .zip → อนุมัติสิทธิ์ → เปิดใช้งาน — ถ้าโค้ด build ไม่ผ่าน ระบบแจ้งไฟล์:บรรทัด และปลั๊กอินยังปิดอยู่
- ดู log ของปลั๊กอินที่ โค้ดของเว็บไซต์ → บันทึกการทำงาน (หรือ
anasaki-code logs --unit event-booking) - แก้แล้วเพิ่ม
versionและอัปโหลดใหม่ — การตั้งค่าและข้อมูลยังอยู่
มี Site Code ที่ใช้งานได้อยู่แล้ว? ปุ่ม ส่งออกเป็นปลั๊กอิน ในหน้าโค้ดของเว็บไซต์สร้าง .zip จากเวอร์ชันที่เผยแพร่อยู่ พร้อม manifest.json ที่เดา scopes, routes, exports และ requires ให้ — ตรวจแล้วแก้ก่อนส่งขึ้นร้าน
พร้อมแล้ว: สมัครและเผยแพร่ปลั๊กอิน · ตัวอย่างครบทั้งตัว: ตัวอย่างปลั๊กอิน · API ทั้งหมด: Plugin API
