FSWP 블록 개발자
기본 (항상 적용): fswp-developer/references/lean-coding.md (적게 작성하고, 재사용 우선), fswp-developer/references/coding-standards.md (코딩 표준, 문서, i18n, 접근성), fswp-security-engineer (입력, 출력, 인가).
핵심 블록을 먼저 사용하고, 핵심 블록과 패턴으로 요구사항을 표현할 수 없을 때만 사용자 정의 블록을 작성합니다. 공식 참고 자료: fswp-developer/references/official-docs.md의 블록 에디터 핸드북 링크. 각 API의 최소 WordPress 버전을 프로젝트의 선언된 최소 버전과 비교하여 확인하세요.
구조
blocks/my-block/
block.json name, title, category, attributes, supports, render, editorScript, viewScriptModule, style
edit.js 편집기 UI (useBlockProps 사용)
save.js 정적 마크업, 또는 동적 블록을 위해 생략
render.php 동적 블록을 위한 서버 렌더링
view.js 프론트엔드 동작 (모듈)
style.scss / editor.scss
메타데이터에서 등록: register_block_type( __DIR__ . '/build/my-block' )를 init에서 호출 (init 콜백에는 이름 있는 함수 사용). "apiVersion": 3 (WordPress 6.3부터 현재) 설정하고 "$schema": "https://schemas.wp.org/trunk/block.json" 추가. 필드별 참고 자료는 블록 에디터 핸드북을 기준으로 검증: references/block-json.md.
결정 사항
| 질문 | 선택 |
|---|---|
| 출력이 저장된 속성에만 의존 | 정적 블록 (save.js) |
| 출력이 실시간 데이터에 의존하거나, 재저장 없이 변경되어야 하거나, 로직 포함 | 동적 블록 (render.php); save는 null 반환 또는 InnerBlocks만 반환 |
| 중첩된 콘텐츠 | InnerBlocks와 allowedBlocks, template 사용 |
| 속성을 데이터(포스트 메타, 사용자 정의 소스)에 바인딩 | 블록 바인딩 API (register_block_bindings_source), 최소 WordPress 버전이 허용하는 경우 |
| 기존 블록의 대체 프리셋 | 새 블록이 아닌 블록 변형 또는 스타일 사용 |
| 재사용 가능한 레이아웃 | 블록이 아닌 패턴 사용 |
규칙
- 속성: 모든 속성에
type과default를 부여하고, 마크업이나 주석에서 일관되게 소싱하며render.php에서 유효성을 검증하세요. - 컨트롤을 직접 작성하는 대신
supports(color, spacing, typography, align, anchor)를 사용하세요. - 편집기 마크업은
useBlockProps()를 사용해야 합니다. 동적 PHP는get_block_wrapper_attributes()를 사용합니다. render.php(block.json의render, WordPress 6.1+)는$attributes,$content,$block(WP_Block 객체)를 전달받습니다. 페이지에서 블록 인스턴스당 한 번 로드되므로, 그 안에서 함수나 클래스를 절대 선언하지 말고 다른 파일의 공유 코드를 호출하세요.- 스크립트 vs 모듈:
viewScript는 클래식 스크립트(WordPress 스크립트에 의존하는 모든 것)용이고,viewScriptModule(6.5+)은 Interactivity API와 같은 스크립트 모듈용입니다. 서로 대체할 수 없으므로 두 종류 간에 의존성을 혼합하지 마세요. render.php에서 모든 것을 이스케이프하세요 (fswp-security-engineer참조). 속성은 사용자 입력입니다.- 출시된 정적 블록의 저장된 마크업을 변경하면 기존 콘텐츠가 손상됩니다. 이전
save, 속성,migrate함수를 포함한deprecated항목을 추가한 후 블록을 변경하세요. - JS와 PHP에서 문자열을 번역하세요 (
__()와 텍스트 도메인 사용);wp_set_script_translations또는 block.json의textdomain. - 블록이 렌더링되는 곳에서만 프론트엔드 스크립트를 로드하세요 (block.json의
viewScriptModule/script가 이 작업을 수행합니다).
패턴
패턴, 변형, 블록 훅, 바인딩에 대한 자세한 내용은 references/patterns-variations.md를 참조하세요. Interactivity API 심화 (서버 렌더링, 비동기 액션, data-wp-each, 감시자, 성능): references/interactivity.md.
PHP에서 register_block_pattern() (및 register_block_pattern_category())로 등록하거나, 테마의 patterns/ 디렉토리에 파일로 등록합니다. 패턴은 프리셋과 번역된 텍스트를 사용하고, 원격 이미지는 사용하지 않으며, 명확한 제목, 카테고리, 키워드를 지정하세요.
Interactivity API
서버 렌더링 마크업에 작은 반응형 동작을 추가하며, 프레임워크가 필요 없습니다.
"supports": { "interactivity": true }및"viewScriptModule": "file:./view.js"로 활성화합니다.- 마크업 디렉티브:
data-wp-interactive="namespace",data-wp-context='{"open":false}',data-wp-on--click="actions.toggle",data-wp-bind--hidden="!context.open",data-wp-class--is-open="context.open",data-wp-text="state.label". view.js의 스토어:import { store, getContext } from '@wordpress/interactivity'; store( 'namespace', { state: {...}, actions: { toggle() { const c = getContext(); c.open = ! c.open; } } } );wp_interactivity_state( 'namespace', array(...) )로 서버 상태를 시딩하여 첫 페인트가 올바르고 깜빡임이 발생하지 않도록 합니다. 상태는 직렬화 가능하게 유지하세요.- 충돌을 피하기 위해 모든 것을 네임스페이스로 구분하고, 상태나 컨텍스트에 비밀 정보를 절대 넣지 마세요 (둘 다 페이지에 인쇄됩니다).
- 접근성을 위해
aria-expanded와 포커스 처리를 상태에 연결하고, 키보드 사용을 테스트하세요.
빌드 및 테스트
시작점으로 npx @wordpress/create-block을 사용하고, @wordpress/scripts로 build, start, lint-js, lint-style, test-unit-js를 실행합니다. 내장된 파일을 src/, package.json, 잠금 파일과 함께 제공하세요 (컴파일된 코드에 대한 디렉토리 규칙). 편집기에서 테스트 (삽입, 편집, 저장, 새로고침, 코드 보기로 전환)하고 프론트엔드에서도 테스트합니다. fswp-qa-engineer에게 전달하세요.