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

อ้างอิง

API ของหน้าออกแบบ — สร้างและแก้หน้าด้วยสคริปต์

endpoint ของหน้า คอมโพเนนต์ เมนู และสื่อ, โครงสร้าง node ของหน้าออกแบบ, class ที่ render ออกมา, ชื่อสำหรับโค้ด (data-ref) และข้อควรระวังเวลาเรียกผ่าน Cloudflare

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

ดูเป็น Markdown

ในหน้านี้

หน้าทุกหน้าที่สร้างในหน้าออกแบบเก็บเป็น ต้นไม้ของ 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/* ที่มี header Authorization

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#

MethodPathใช้ทำอะไร
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 คู่กับ header X-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
texttext, rich (HTML ย่อย), tag (h1…p), href, newTab
buttontext, href, newTab, icon (ชื่อไอคอน), iconPosition: 'end', action
imagesrc, alt, href, lightbox (2.4.0: กดแล้วเปิดรูปเต็มในแกลเลอรี จัดกลุ่มตามเฟรมที่ครอบ)
menumenuId, burger (พับเป็น ☰ บนมือถือ)
postListquery: {postType, category, limit, order} + การ์ดใบแรกเป็น children
inputkind (text search select checkbox …), name, placeholder, value (+ valueText: true = ข้อความตรงตัว), options, filter: {collection, param}
codeblockhtml, css (:scope = ตัวบล็อก), js
instancecomponentId, variant, overrides
iconicon, 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()