การใช้ token

Design Controller เผยแพร่ระบบดีไซน์ของเว็บเป็น CSS custom properties ชื่อ --dc-* บน :root พิมพ์ครั้งเดียวที่ wp_head จาก option ที่ autoload ตัวเดียว การอ่านจึงไม่มี query เพิ่ม และมี helper PHP สามตัวสำหรับกรณีที่ต้องการค่าจริง หน้านี้สำหรับใครก็ตามที่อยากให้ธีมหรือปลั๊กอินของตัวเอง "ตามเว็บ" โดยไม่ต้องมีหน้าตั้งค่าของตัวเอง

กฎข้อเดียว: var(--dc-…, fallback)

ตัวอย่าง: ปลั๊กอินที่ตามเว็บ

สมมติ stylesheet ของปลั๊กอินคุณประกาศตัวแปรของตัวเองไว้:

:root {
	--my-primary: #0b67b2;
	--my-primary-dark: #084d86;
	--my-radius: 8px;
}

เปลี่ยนแต่ละตัวให้เป็น "ค่าของเว็บถ้ามี ไม่มีก็ค่าของฉัน" ได้ในบรรทัดเดียวต่อตัวแปร โดยไม่ต้องแตะ selector อื่นเลย:

:root {
	--my-primary: var(--dc-color-brand-primary, #0b67b2);
	--my-primary-dark: var(--dc-color-brand-primary-strong, #084d86);
	--my-font: var(--dc-font-family-body, "Sarabun", sans-serif);
	--my-radius: var(--dc-radius-md, 8px);
}
.my-button {
	background: var(--my-primary);
	border-radius: var(--my-radius);
	font-family: var(--my-font);
}

เปลี่ยนสีแบรนด์หรือฟอนต์เนื้อหาใน Design Controller แล้วปลั๊กอินเปลี่ยนตามทันที รวมถึงใน ตัวอย่างสดด้วย โดยปลั๊กอินไม่ต้องรู้จัก Design Controller เลย

ตัวแปรที่ใช้บ่อย

| กลุ่ม | ตัวแปร | หมายเหตุ | | --- | --- | --- | | สีแบรนด์ | --dc-color-brand-primary, -secondary, -accent | แต่ละตัวมี -soft, -strong, -contrast (คำนวณให้; -contrast คือสีตัวอักษรบนสีนั้น) | | สีกลาง | --dc-color-neutral-50 … -950 | ลำดับจาก seed สีเดียว | | สื่อความหมาย | --dc-color-semantic-success, -warning, -danger, -info | พร้อม -soft, -contrast | | พื้นผิวและข้อความ | --dc-color-surface-page, -card, -muted, -inverse; --dc-color-text-default, -muted, -inverse, -link, -link-hover; --dc-color-border-default, -strong | | | ฟอนต์ | --dc-font-family-heading, -body, -ui, -mono | stack เต็ม รวม fallback ที่ปรับ metric แล้ว | | ขนาด | --dc-font-size-xs … -5xl (-md คือฐาน), --dc-font-heading-h1-size … -h6-size | เป็น clamp() แบบ fluid เมื่อเปิด | | น้ำหนักและระยะบรรทัด | --dc-font-weight-regular, -medium, -semibold, -bold; --dc-font-line-height-tight, -normal, -relaxed | | | ระยะห่าง | --dc-space-1 … -12, --dc-space-section-sm, -md, -lg, --dc-layout-container-sm … -xl, --dc-layout-gutter | | | รูปทรงและเงา | --dc-radius-sm, -md, -lg, -xl, -full; --dc-shadow-sm, -md, -lg; --dc-border-width-thin, -thick | | | การเคลื่อนไหว | --dc-motion-duration-fast, -normal, --dc-motion-easing | | | คอมโพเนนต์ | --dc-component-button-primary-background, -text, -border, -radius, -padding-x, -padding-y, -weight; …-secondary-*, …-outline-*; --dc-component-input-*, --dc-component-card-*, --dc-component-nav-* | มีค่าเสมอ แม้ปิด recipe |

ชื่อตัวแปรคือ path ของ token ที่แปลง camelCase เป็น kebab-case และ . เป็น -: font.lineHeight.normal กลายเป็น --dc-font-line-height-normal คำสั่ง wp dctl export --resolved พิมพ์ค่าจริงทั้งหมดเป็น DTCG JSON

ฝั่ง PHP เมื่อต้องการค่าจริง

สำหรับ PDF อีเมล หรือแผนภูมิ อะไรก็ตามที่อ่าน CSS ของหน้าเว็บไม่ได้:

// hex ที่ resolve แล้ว (alias และค่าที่คำนวณถูกจัดการให้) คืน $fallback เมื่อไม่มีปลั๊กอินหรือไม่มีค่า
$primary = function_exists( 'dctl_token' ) ? dctl_token( 'color.brand.primary' ) : null;
$primary = $primary ?? '#0b67b2';

// สตริง var(--dc-…, fallback) สำเร็จรูปสำหรับ inline style
$css = function_exists( 'dctl_var' ) ? dctl_var( 'radius.md', '8px' ) : '8px';

// font stack ตามบทบาท (heading | body | ui | mono) เป็นสตริง CSS
$font = function_exists( 'dctl_font_stack' ) ? dctl_font_stack( 'body' ) : '"Sarabun", sans-serif';

ทั้งสาม helper อ่านจาก option ที่ autoload ไม่มี query และปลอดภัยที่จะเรียกในทุก template ไฟล์ฟอนต์ที่ Design Controller โฮสต์อยู่ใน wp_font_dir() ดูรายการได้ด้วย wp dctl fonts list

Hook ที่ควรรู้

| Hook | ใช้เมื่อ | | --- | --- | | dctl_design_published (action; $design_id, $compiled) | ต้องทำอะไรหลังเผยแพร่ เช่น สร้างไฟล์ CSS ของตัวเองใหม่ | | dctl_compiled_updated (action; $design_id, $compiled, $published) | ทุกครั้งที่ CSS บนเว็บเปลี่ยน รวม recompile จากฟอนต์หรือการตั้งค่า | | dctl_cache_purged (action; $ids) | หลังล้างแคช ให้ล้างแคชของตัวเองต่อ | | dctl_cache_targets (filter) | เพิ่มแคชของโฮสต์หรือปลั๊กอินที่ยังไม่รู้จัก: ['id', 'label', 'detect' => callable, 'purge' => callable] | | dctl_component_selectors (filter; $map, $theme) | ให้ recipe ของปุ่ม ช่องกรอก การ์ด และเมนู ครอบคลุม selector ของปลั๊กอินคุณ | | dctl_frontend_css (filter; $css, $compiled) | พิมพ์ CSS เพิ่มใน <style id="dctl-bridges"> ใช้เฉพาะ var(--dc-*) ห้ามมี query | | dctl_bridges (filter) | เพิ่ม bridge ของโมดูลอื่นทั้งตัว (BridgeInterface) |

สามสิ่งที่ห้ามทำ