อ้างอิง
API ของหน้าออกแบบ — สร้างและแก้หน้าด้วยสคริปต์
endpoint ของหน้า คอมโพเนนต์ เมนู และสื่อ, โครงสร้าง node ของหน้าออกแบบ, class ที่ render ออกมา, ชื่อสำหรับโค้ด (data-ref) และข้อควรระวังเวลาเรียกผ่าน Cloudflare
ในหน้านี้
หน้าทุกหน้าที่สร้างในหน้าออกแบบเก็บเป็น ต้นไม้ของ node (JSON) ในฟิลด์ design ของบทความ สคริปต์และเครื่องมือ AI จึงสร้างหรือแก้หน้าได้ด้วย REST API ชุดเดียวกับที่หลังบ้านใช้ หน้านี้รวบรวมสิ่งที่ต้องรู้ไว้ที่เดียว (CMS 2.2.0)
การยืนยันตัวตน#
ส่ง Authorization: Bearer <token> ทุกคำขอ token ได้จาก POST /api/v1/auth/login {email, password} หรือ token ระยะยาวจาก POST /api/v1/auth/tokens การแก้ดีไซน์ต้องมีสิทธิ์ edit_pages และถ้ามีบล็อกโค้ดต้องมี edit_scripts ด้วย
ใช้ผ่าน Cloudflare: ถ้าเว็บอยู่หลัง Cloudflare คำขอที่ไม่มี
User-Agentหรือใช้ค่าเริ่มต้นของไลบรารีบางตัว เช่นurllibของ Python จะได้403 error code: 1010(Browser Integrity Check) ให้ตั้งUser-Agentเอง เช่นmy-script/1.0หรือสร้าง WAF rule ยกเว้น/api/v1/*ที่มี headerAuthorization
import json, urllib.request
req = urllib.request.Request("https://example.com/api/v1/posts/11",
headers={"Authorization": "Bearer " + TOKEN, "User-Agent": "qraft-sync/1.0"})
page = json.load(urllib.request.urlopen(req))
Endpoint#
| Method | Path | ใช้ทำอะไร |
|---|---|---|
| GET | /api/v1/posts?type=page | รายการหน้า (perPage, page, q, status = draft / publish / scheduled / any) |
| GET | /api/v1/posts/{id} | หน้าเดียว พร้อม design, updatedAt และ draft (ถ้ามีฉบับร่าง) |
| POST | /api/v1/posts | สร้าง {type:"page", title, slug?, status?, design?} |
| PUT | /api/v1/posts/{id} | แก้ {title?, slug?, status?, design?, baseUpdatedAt?, asDraft?, discardDraft?} |
| GET / POST / PUT | /api/v1/components · /api/v1/components/{id} | ส่วนที่ใช้ซ้ำ {name, node, baseUpdatedAt?} |
| GET / POST / PUT | /api/v1/menus · /api/v1/menus/{id} | เมนู {name, items:[{label, url}]} |
| POST | /api/v1/media (multipart file) | อัปโหลดรูป/ไฟล์ → {id, url, width, height} |
| GET | /api/v1/settings → theme | สีและฟอนต์ของเว็บ (var(--c-<key>)) และ breakpoints |
| POST | /api/v1/links/replace {from, to} | เปลี่ยนลิงก์ทุกที่ (ดีไซน์ คอมโพเนนต์ เมนู) เมื่อย้ายที่อยู่หน้า |
- กันเขียนทับ: ส่ง
baseUpdatedAtเป็นค่าupdatedAtที่อ่านมา ถ้ามีคนบันทึกใหม่กว่าในระหว่างนั้น ระบบตอบ409แทนการทับงานของเขา - id ของชั้นต้องไม่ซ้ำ: ถ้า id ซ้ำ ระบบตอบ
400พร้อมบอก id นั้น (ตั้งแต่ 2.1.1) - หมวดของบทความ:
terms: {"category": ["news", 12]}รับได้ทั้ง slug และ id - status: ไม่ใส่ หรือ
any/all= ทุกสถานะ ค่าอื่นที่ไม่รู้จักตอบ400(ตั้งแต่ 2.3.0 ก่อนหน้านี้ได้รายการว่าง) - ฉบับร่างของหน้าที่เผยแพร่แล้ว (2.3.0):
asDraft: trueเก็บtitle/slug/designไว้ในdraftของหน้า ผู้เยี่ยมชมยังเห็นฉบับที่เผยแพร่ ส่งอีกครั้งโดยไม่มีasDraft(หรือstatus: "publish") เพื่อเผยแพร่ ส่งdiscardDraft: trueเพื่อทิ้งฉบับร่าง — หน้าที่ยังไม่เผยแพร่asDraftไม่มีผล (บันทึกตามปกติ) - ยืนยันตัวตน: สคริปต์ใช้
Authorization: Bearerส่วนหน้าจัดการ (2.3.0) ใช้คุกกี้HttpOnlyคู่กับ headerX-Anasaki-Session: cookieคุกกี้อย่างเดียวไม่นับเป็นการล็อกอิน - ทุกการบันทึกเก็บเวอร์ชันก่อนหน้าไว้ ดูได้ที่
GET /api/v1/posts/{id}/revisions(25 เวอร์ชันล่าสุด)
โครงสร้าง node#
interface Node {
id: string; // ไม่ซ้ำในหน้า → class n-<id>
type: 'frame' | 'text' | 'rect' | 'image' | 'button' | 'menu' | 'postList' | 'postContent' | 'instance'
| 'embed' | 'collection' | 'pluginBlock' | 'download' | 'breadcrumb' | 'icon' | 'shape' | 'vector'
| 'pagination' | 'input' | 'codeblock';
name?: string; // ชื่อในแผงชั้น
visible?: boolean; locked?: boolean;
absolute?: boolean; x?: number; y?: number; // วางอิสระในกล่อง auto layout
width: Size; height: Size; // { mode: 'fixed', value: 320 } | { mode: 'fill' } | { mode: 'hug' }
layout?: { mode?: 'none' | 'horizontal' | 'vertical'; gap?: number; padding?: [top, right, bottom, left];
align?: 'start' | 'center' | 'end' | 'stretch'; justify?: 'start' | 'center' | 'end' | 'between';
wrap?: boolean; columns?: number };
style?: Style; // ด้านล่าง
props?: Record<string, any>; // ตามชนิด ด้านล่าง
responsive?: { tablet?: Override; mobile?: Override }; // ค่าที่ต่างไปบนจอเล็ก (มือถือได้ค่าของแท็บเล็ตด้วย)
children?: Node[];
}
// Override = { x?, y?, width?, height?, visible?, layout?: Partial<layout>, style?: Partial<style> }
style ที่ใช้บ่อย: fill color stroke + strokeWidth (+ strokeStyle) radius / radii shadow opacity fontFamily (ใส่หลายฟอนต์คั่นด้วยจุลภาคได้ เช่น "Kanit, system-ui") fontSize fontWeight lineHeight letterSpacing textAlign maxWidth minHeight minHeightScreen + minHeightOffset (สูงเท่าจอ หักแถบเมนู) backgroundImage overlay objectFit hover: {fill, color, stroke, scale, lift, shadow, opacity, duration} active: {fill, color, stroke} (แท็บที่เลือก / ลิงก์ของหน้าปัจจุบันในเมนู) anim: {type: 'fade' | 'up' | …, delay, duration} textStyle (id ของสไตล์ตัวอักษรในธีม) และสำหรับเมนู linkPadding: [v, h] linkRadius
props ตามชนิด
| ชนิด | props |
|---|---|
text | text, rich (HTML ย่อย), tag (h1…p), href, newTab |
button | text, href, newTab, icon (ชื่อไอคอน), iconPosition: 'end', action |
image | src, alt, href, lightbox (2.4.0: กดแล้วเปิดรูปเต็มในแกลเลอรี จัดกลุ่มตามเฟรมที่ครอบ) |
menu | menuId, burger (พับเป็น ☰ บนมือถือ) |
postList | query: {postType, category, limit, order} + การ์ดใบแรกเป็น children |
input | kind (text search select checkbox …), name, placeholder, value (+ valueText: true = ข้อความตรงตัว), options, filter: {collection, param} |
codeblock | html, css (:scope = ตัวบล็อก), js |
instance | componentId, variant, overrides |
icon | icon, strokeWidth, label |
ทุกชนิดมี props.ref (ชื่อสำหรับโค้ด) และ props.showWhen (เงื่อนไขแสดง) ได้
class ที่ render ออกมา#
- แต่ละชั้นได้
class="n-<id>"ซึ่งคงที่ตราบที่ id ไม่เปลี่ยน ส่วนชั้นข้างในคอมโพเนนต์ที่วางไว้ได้n-<id ของ instance>-<id ในคอมโพเนนต์> - id เปลี่ยนได้เมื่อ ทำซ้ำ วาง หรือแยกคอมโพเนนต์ และหน้าออกแบบจะตั้ง id ใหม่ให้ชั้นที่ซ้ำกันตอนเปิดหน้า โค้ดที่ต้องการชื่อถาวรจึงควรใช้ ชื่อสำหรับโค้ด แทน
ชื่อสำหรับโค้ด (data-ref)#
ตั้งได้ที่แท็บ เนื้อหา → ชื่อสำหรับโค้ด ของทุกชั้น (หรือ props.ref ใน API) ระบบ render เป็น data-ref="<ชื่อ>" และบล็อกโค้ดหาชั้นนั้นได้ด้วย
const btn = anasaki.ref('download'); // ตัวแรก (หรือ null)
anasaki.refs('card').forEach(c => …); // ทุกตัว เช่น การ์ดในรายการ
ชื่อใช้ได้ a-z ตัวแรก ตามด้วย a-z A-Z 0-9 _ - ไม่เกิน 40 ตัว แผงชั้นแสดงป้าย </> ที่ชั้นซึ่งมีชื่อสำหรับโค้ด ผู้ออกแบบจะได้รู้ว่ามีโค้ดอ้างถึงชั้นนั้นอยู่
ไฟล์ที่บล็อกโค้ดใช้ร่วมกัน#
ไฟล์ในโฟลเดอร์ public/ ของ Site Code (เช่น public/qr.js, public/base.css, .svg, .txt, .json) จะไม่ถูก bundle แต่เวอร์ชันที่เผยแพร่จะเสิร์ฟไฟล์เหล่านี้ที่ /site-assets/<ชื่อไฟล์> บล็อกโค้ดโหลดไฟล์ที่ใช้ร่วมกันได้ครั้งเดียวต่อหน้า:
await anasaki.lib('qr'); // รัน /site-assets/qr.js หนึ่งครั้ง (ทุกบล็อกรอ promise เดียวกัน)
await anasaki.style('base'); // ใส่ /site-assets/base.css
ใน Site Code ใช้ site.asset('public/qr.js') เพื่อได้ url (พร้อม ?v=<เวอร์ชัน> และ cache หนึ่งปี) และ text()
