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

อ้างอิง

Plugin API (สรุปอ้างอิง)

สรุป API สาธารณะทั้งหมดที่ปลั๊กอินใช้ได้ — เวอร์ชันที่เพิ่มเข้ามา, minCore และ feature detection, site.*, db.*, http/mail/jobs/plugins, ฮุกหน้าเว็บ, หน้าหลังบ้าน และ admin UI kit

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

ดูเป็น Markdown

ในหน้านี้

ระบบหลักไม่เคยเขียนโค้ดพิเศษให้ปลั๊กอินตัวใด — ปลั๊กอินทางการ (seo, forms …) ใช้เฉพาะ API ในหน้านี้ สิ่งที่ปลั๊กอินทางการทำได้ ปลั๊กอินของคุณก็ทำได้ เอกสารฉบับเต็มอยู่ใน repository: docs/plugin-api.md (API), docs/site-code.md (รายละเอียด JS API) และ type ที่ถูกต้องที่สุดคือ anasaki.d.ts (GET /api/v1/code/types)

เวอร์ชันของ API#

เวอร์ชัน CMSเพิ่มอะไร
2.0.0แพลตฟอร์มปลั๊กอินรุ่นแรก (แพ็กเกจ, service, WASM และ JavaScript) — ทุกอย่างในหน้านี้ที่ไม่ได้ระบุเวอร์ชัน
2.0.3AK.line, AK.open, AK.height, data-ak-line, data-ak-open; หน้าจัดการและวิดเจ็ตปรับความสูงตามเนื้อหา
2.0.4AK.pickMedia (เลือกรูปจากคลังสื่อ); พาธที่ปลั๊กอินประกาศถูกสงวน (GET /api/v1/settings/reserved-paths); ปลั๊กอินแนะนำในหน้าตั้งค่าเริ่มต้นมาจาก Store
2.0.5ปลั๊กอิน JavaScript ประกาศประเภทเนื้อหา (site.postType) ของตัวเองได้ — scope post-types, id <id ปลั๊กอินที่ - เป็น _>_<ชื่อ> (≤ 20 ตัว), public: false ปิดการ route ของระบบ, ช่องใน spec เก็บชื่อตรง ๆ (ดู สร้างปลั๊กอิน JavaScript)
2.0.6สิทธิ์ของปลั๊กอิน: capabilities ใน manifest (ผู้ดูแลติ๊กต่อตำแหน่งที่ ผู้ใช้งาน → สิทธิ์การใช้งาน), 'cap:<สิทธิ์>' ในรายการ access, site.can(user, cap) / user.can(cap) และ caps: { edit, publish } ของประเภทเนื้อหา — ดู สิทธิ์ของปลั๊กอิน
2.1.0site.taxonomy และ db.terms.* (scope taxonomies / terms-write), media.* / files.* / request.files() (scope media / media-write / files), ค่าตั้งค่าแบบ secret, ฟิลด์ใหม่ (relation, user, term, file, gallery, repeater, richtext, color), event มี actor และ previous, บทความตั้งเวลาเผยแพร่ (scheduled)
2.1.1site.cron(expr, fn, { name }); toLocaleString('th-TH') / toLocaleDateString ทำงานได้ (ปี พ.ศ.); REST terms รับ slug
2.2.0site.asset('public/…') ใน Site Code และไฟล์ public/ ที่ /site-assets/; atob / btoa; ฝั่งหน้าเว็บ anasaki.ref() / anasaki.refs() (ชื่อสำหรับโค้ด) และ anasaki.lib() / anasaki.style() — ดู API ของหน้าออกแบบ
2.2.2db.users.list / get (scope users) — โปรไฟล์สาธารณะของผู้ใช้ ไม่มีอีเมล; ประเภทเนื้อหาที่ผู้ดูแลสร้างใน ตั้งค่า → ประเภทเนื้อหา อ่านด้วย db.posts ได้เหมือนประเภทจากโค้ด (post-types ของ GET /api/v1/post-types มี admin: true); ctx.preview ใน render ของ site.block (true = แสดงในหน้าออกแบบ, false = หน้าเว็บจริง) ใช้ซ่อนข้อความแนะนำ เช่น "เลือกฟอร์ม" จากผู้เข้าชม; code.routes มีจุดได้ เช่น /feed.xml (ห้าม .. และห้ามขึ้นต้นด้วยจุด); ไฟล์ที่ส่งออกจาก Site Code มี category: "utilities"
2.3.0ctx.isAdminUser (middleware) / isAdminUser (afterResponse) รวมผู้ดูแลที่เปิดดูเว็บในเบราว์เซอร์เดียวกับหลังบ้าน (ctx.user ยังเป็น null); URL ของหน้าแรกจาก db.posts เป็น /; REST GET /posts?status=any และฉบับร่างของหน้าที่เผยแพร่แล้ว (asDraft); รายการแหล่งข้อมูลของหน้าออกแบบไม่แสดงตารางของปลั๊กอิน (p_*); รายการบทความของประเภทเนื้อหาที่สร้างเองกรองด้วยหมวดของตัวเองได้ (slug, id หรือชื่อ)
2.4.0บันทึกกิจกรรมของผู้ดูแล (GET /api/v1/audit, สิทธิ์ manage_users) — action ของหน้าจัดการปลั๊กอินที่ผู้ใช้กดถูกบันทึกด้วย; แพ็กเกจจาก Store มีลายเซ็น Ed25519 (X-Anasaki-Signature, GET /api/v1/signing-key ของ Store) และ CMS ตรวจก่อนติดตั้ง; รูปในหน้าออกแบบมี props.lightbox; ปลั๊กอิน Docs 1.2.0 มีบทความหลายภาษา (/docs/<lang>/…)

เลขเวอร์ชันของเว็บดูได้จาก GET /api/public/site (version) และหน้า ตั้งค่าเว็บไซต์ → ทั่วไป

minCore และ feature detection#

{ "id": "my-plugin", "version": "1.0.0", "minCore": "2.0.4" }

ตั้ง minCore เป็นเวอร์ชันของ API ที่ ขาดไม่ได้ (ระบบที่เก่ากว่าปฏิเสธการติดตั้ง) ส่วนความสามารถเสริมให้ตรวจก่อนใช้ เพื่อให้เว็บรุ่นเก่ายังติดตั้งได้:

if (typeof site.dashboardWidget === 'function') site.dashboardWidget('visits', { /* … */ });
if (plugins.has('thai')) site.formatter('price', (v) => plugins.call('thai', 'bahtText', v));
// ในหน้าจัดการ (เบราว์เซอร์)
if (window.AK && AK.pickMedia) pickButton.hidden = false; else urlInput.hidden = false;

site.*#

APIscope
site.route(spec, opts?, handler) — "GET /x/{id}", access, rawBody, maxBodyroutes
site.page(path, {access, load}) — ข้อมูลของหน้าที่ออกแบบroutes
site.collection(name, spec) · site.action(name, spec) · site.formatter(name, fn)—
site.on(event, fn) · site.emit(name, data) · site.export(name, fn)—
site.filter(name, fn, {priority}) · site.applyFilter(name, value, ctx)filters-core สำหรับจุดของระบบ
site.visitor(fn) · site.visitorGroups(groups)visitor
site.fields(type, fields) · site.meta(postId) · site.setMeta(postId, values)content-fields
site.postType(id, spec) — ปลั๊กอิน: ตั้งแต่ 2.0.5, id <plugin>_<name>, public: false = ปลั๊กอินเสิร์ฟหน้าเองpost-types
site.job(name, opts?, fn) · site.cron(expr, target, { name }?)jobs
site.can(user, capability) — ตั้งแต่ 2.0.6 (สิทธิ์ของปลั๊กอิน)—
site.adminPage(id, spec) · site.dashboardWidget(id, spec) · site.adminNotice(fn, {access})admin-pages
site.block(type, spec) — บล็อกที่เรนเดอร์ฝั่งเซิร์ฟเวอร์ (render(ctx, props): ctx.site, ctx.post, ctx.item, ctx.path, ctx.query, ctx.user, ctx.preview ตั้งแต่ 2.2.2)—
site.middleware(fn, {priority}) · site.afterResponse(fn)middleware
site.head(fn) · site.bodyEnd(fn)— (head-scripts = ไม่กรอง HTML)
site.settings(key?) · site.saveSettings(values) · site.info() · site.asset(path)—

ผลลัพธ์ของ route/page/action: ค่า (JSON), {status, headers?, body?}, bytes (Uint8Array ≤ 20 MB), {page: {title, html}} (แสดงในหัว/ท้ายของเว็บ) — context: request {method, path, params, query, headers, cookies, body, json(), ip, host}, response.setCookie(...), user, visitor

db.*#

APIscope
db.table(name) / db.from(name) — query builder, aggregate (selectCount, selectSum …)db
db.transaction(fn) · db.raw(sql, params) (ห้าม SELECT/FROM/JOIN) · db.docs(name)db
migration migrations/NNN_name.ts ด้วย migration({up, down})db
db.posts.list / get · view core_*content
db.users.list({ role?, search?, page?, perPage? }) · db.users.get(id) — ชื่อ รูป ประวัติ เว็บไซต์ ตำแหน่ง จำนวนบทความ (ไม่มีอีเมล ไม่รวมผู้ใช้ที่ถูกระงับ, 2.2.2)users
db.posts.create / update / delete · db.asSystem(fn)content-write

ปลั๊กอินไม่ได้ db.query และ schema.raw — ตารางของปลั๊กอินคือ p_<id>_* เท่านั้น

http, mail, jobs, plugins และอื่น ๆ#

APIscope
http.fetch(url, {method, headers, body, timeout})http (+ code.hosts)
http.webhook(url, event, data, {secret?})webhooks
mail.send({to, subject, html?, text?, replyTo?})mail
jobs.enqueue(name, data, {delay, key})jobs
plugins.call(id, fn, ...args) · plugins.has(id) · plugins.version(id) · error PluginUnavailable—
import { x } from '<id>' — library/exports ของปลั๊กอินใน requires—
cache.* · crypto.* · log.* / console.*—

Event และ filter ของระบบ#

  • event: post.published, post.saved, post.deleted, user.created, media.uploaded — event อื่นเป็นของปลั๊กอินที่ส่ง (<id>.… หรือชื่อใน code.eventAliases เช่น form.submitted)
  • filter (scope filters-core): post.content, post.beforeSave, page.head, page.meta, collection.items, action.input, action.result, mail.beforeSend, sitemap.urls, robots.txt — เมื่อมีหน่วยใดกรอง sitemap.urls หรือ robots.txt ระบบจะเสิร์ฟ /sitemap.xml และ /robots.txt ให้

ฮุกของหน้าเว็บสาธารณะ#

ฮุกทำงานเมื่อเวลา
site.middlewareก่อนจัดเส้นทางทุกคำขอ — คืนค่าว่าง = ไปต่อ, คืนผลลัพธ์ = ตอบเลย, คืน {headers} = เพิ่ม header แล้วไปต่อ20 ms
site.afterResponseหลังตอบแล้ว (ในคิว ไม่ทำให้ช้า) — ข้อมูลคำขอ สถานะ IP ฯลฯ2 วินาที (ก่อน 2.2.0: 500 ms)
site.head / site.bodyEndHTML ใน <head> / ก่อน </body> (กรอง HTML ถ้าไม่มี head-scripts)50 ms
filter page.meta{title, fullTitle, description, image, canonical, robots, noindex, og}50 ms

ctx.isAdminUser ของ middleware และ isAdminUser ของ afterResponse เป็น true เมื่อผู้ใช้ CMS ที่ล็อกอินอยู่เป็นคนเปิดหน้า ตั้งแต่ 2.3.0 นับรวมผู้ดูแลที่เปิดดูเว็บ (GET) ในเบราว์เซอร์เดียวกับหลังบ้านด้วย แต่ ctx.user ยังเป็น null ในกรณีนั้น ใช้ตัดสินใจเรื่องการแสดงผลได้ (เช่น ข้ามหน้าปิดปรับปรุง ไม่นับสถิติ) แต่ห้ามใช้ให้สิทธิ์ทำรายการ

หน้าหลังบ้าน วิดเจ็ต และแถบแจ้งเตือน#

  • หน้าจัดการ (site.adminPage) อยู่ที่ /admin/x/code/<id>:<page> รันใน iframe แบบ sandbox — ใช้ anasaki.call('<id>:<action>', input) เรียก action ในนามผู้ใช้, anasaki.download(query) สำหรับไฟล์ดาวน์โหลด และวาด <header class="ak-page-head"> เอง
  • วิดเจ็ตแดชบอร์ด (site.dashboardWidget, ≤ 10 ต่อปลั๊กอิน) แสดงบนหน้าหลักของหลังบ้าน
  • แถบแจ้งเตือน (site.adminNotice, ≤ 5 ต่อปลั๊กอิน) ระดับ info | warning | danger | success พร้อมลิงก์
  • ผู้ดูแลระบบ override ตำแหน่งที่เปิดหน้าได้ที่ โค้ดของเว็บไซต์ → สิทธิ์การเข้าถึง

Admin UI kit (window.AK)#

ทุกหน้าจัดการและวิดเจ็ตโหลด /ext-ui/kit.css + /ext-ui/kit.js ให้เอง — คลาส ak-* (การ์ด ปุ่ม ป้าย ตาราง ฟอร์ม แท็บ toast dialog กราฟ) รองรับธีมสว่าง/มืด

ฟังก์ชันเวอร์ชัน
AK.toast(msg, kind?) · AK.confirm(text, {ok, cancel, danger}) · AK.tabs(el) · AK.table(el, opts) · AK.sortable(table) · AK.pager(el, opts) · AK.validate(form) · AK.bar(el, data) · AK.sparkline(el, data) · AK.lang() · AK.t(key)2.0.0
AK.line(el, {labels, series}) · AK.open(path) · AK.height()2.0.3
AK.pickMedia({accept: 'image' | 'file'}) → {url, id, alt, width, height} หรือ null2.0.4

พาธสาธารณะที่สงวนไว้#

ปลั๊กอินประกาศพาธของตัวเองใน code.routes (JavaScript) หรือ service.public (service/WASM) และใช้พาธของระบบไม่ได้: api, uploads, download, plugin-assets, ext-ui, setup, _a, _c, site-assets (ตั้งแต่ 2.2.0), sitemap.xml, robots.txt, favicon.ico, favicon.svg, assets, static รวมถึงที่อยู่หน้าจัดการและคำนำหน้าบทความ/หมวดหมู่ ตั้งแต่ 2.0.4 พาธที่ปลั๊กอินที่ติดตั้งประกาศไว้ก็ถูกสงวน — ผู้ดูแลตั้งที่อยู่หน้าจัดการหรือคำนำหน้าให้ชนกับพาธเหล่านั้นไม่ได้

---

ขาด API ที่ต้องใช้? ทุก API ในหน้านี้ถูกเพิ่มเพราะมีปลั๊กอินต้องการ — อธิบาย use case และ API ทั่วไปที่เล็กที่สุดที่แก้ปัญหาได้ แทนการพึ่งการทำงานภายในของระบบ ดูตัวอย่างการใช้งานจริงที่ ตัวอย่างปลั๊กอิน