wp-블록-개발은(는) 무엇을 하나요?
워드프레스(구텐베르크) 블록 개발 시 사용: block.json 메타데이터, register_block_type(_from_metadata), 속성/직렬화, supports, 동적 렌더링(render.php/render_callback), 폐기/마이그레이션, viewScript와 viewScriptModule 비교, @wordpress/scripts/@wordpress/create-block 빌드 및 테스트 워크플로우를 다룹니다.
주요 개념
block.json 메타데이터
$schema,apiVersion,name,title,category,icon,description,keywords,textdomain필드를 정의합니다.attributes: 블록 속성과 해당 직렬화 설정을 지정합니다.supports: 블록이 지원하는 기능(예:align,anchor,className,customClassName,html,inserter,multiple,reusable)을 설정합니다.usesContext와providesContext: 블록 간 컨텍스트 전달을 관리합니다.viewScript,viewScriptModule,editorScript,style,editorStyle,render: 프론트엔드/에디터별 스크립트와 스타일을 지정합니다.
블록 등록
register_block_type( __DIR__ . '/build' ): block.json을 기반으로 블록을 등록합니다.register_block_type_from_metadata(): 동일한 기능을 수행하는 대체 함수입니다.- 동적 블록은
render_callback또는render.php를 통해 PHP로 렌더링합니다.
속성과 직렬화
type:string,number,boolean,object,array등.default: 기본값.source:attribute,html,text,children,query.selector: 속성을 추출할 DOM 선택자.meta: (메타 블록에서) 글 메타 필드와 연결.
supports
align: 정렬 옵션.anchor: 앵커 ID.className: 사용자 정의 클래스.customClassName: 사용자 정의 클래스 활성화.html: HTML 편집 허용.inserter: 삽입기 표시.multiple: 여러 번 사용 가능.reusable: 재사용 가능.color,typography,spacing등: 블록 에디터 UI 제어.
동적 렌더링
render.php: 블록의 PHP 렌더링 템플릿.render_callback:register_block_type에 전달되는 콜백 함수.$attributes,$content,$block인자를 받습니다.
폐기 및 마이그레이션
deprecated: 이전 버전의 블록 속성 및 동작을 정의하여 하위 호환성을 유지합니다.- 각 폐기 항목은
attributes,supports,save,migrate속성을 포함합니다. migrate함수는 이전 속성을 새 속성으로 변환합니다.
viewScript vs viewScriptModule
viewScript: 프론트엔드에서 실행되는 표준 JavaScript 파일.viewScriptModule: 프론트엔드에서 실행되는 ES 모듈 형태의 JavaScript 파일.- 모듈을 지원하는 브라우저에서 사용됩니다.
- 필요에 따라 하나 또는 둘 다 사용할 수 있습니다.
빌드 및 테스트 워크플로우
@wordpress/scripts
npm run build: 블록을 프로덕션용으로 빌드합니다.npm run start: 개발 모드에서 빌드하고 파일 변경을 감시합니다.npm run format: 코드 포맷을 정리합니다.npm run lint:css: CSS 린트를 실행합니다.npm run lint:js: JavaScript 린트를 실행합니다.npm run packages-update: 워드프레스 패키지를 업데이트합니다.npm run plugin-zip: 플러그인 ZIP 파일을 생성합니다.
@wordpress/create-block
npx @wordpress/create-block my-block: 새 블록 플러그인을 생성합니다.npx @wordpress/create-block my-block --namespace my-namespace: 네임스페이스를 지정합니다.npx @wordpress/create-block my-block --template my-template: 사용자 정의 템플릿을 사용합니다.- 생성된 구조:
src/,build/,block.json,package.json,webpack.config.js등.
예제
기본 block.json
{
"$schema": "https://schemas.wp.org/trunk/block.json",
"apiVersion": 3,
"name": "my-plugin/my-block",
"title": "내 블록",
"category": "widgets",
"icon": "smiley",
"description": "내 첫 번째 블록입니다.",
"attributes": {
"content": {
"type": "string",
"source": "html",
"selector": "p"
},
"alignment": {
"type": "string",
"default": "none"
}
},
"supports": {
"align": true,
"anchor": true,
"className": true,
"color": {
"background": true,
"text": true
}
},
"editorScript": "file:./index.js",
"script": "file:./script.js",
"viewScript": "file:./view.js",
"style": "file:./style-index.css",
"render": "file:./render.php"
}
PHP 등록 (plugin.php)
function my_plugin_register_blocks() {
register_block_type( __DIR__ . '/build/my-block' );
}
add_action( 'init', 'my_plugin_register_blocks' );
render.php
<?php
$content = $attributes['content'] ?? '';
$alignment = $attributes['alignment'] ?? 'none';
$class_name = 'wp-block-my-plugin-my-block';
if ( $alignment !== 'none' ) {
$class_name .= ' has-text-align-' . $alignment;
}
?>
<p class="<?php echo esc_attr( $class_name ); ?>">
<?php echo wp_kses_post( $content ); ?>
</p>
추가 참고
- 항상
wp_kses_post또는esc_*함수를 사용하여 동적 콘텐츠를 안전하게 출력하세요. - 블록의
viewScript는 실제 사용자가 페이지를 볼 때만 로드됩니다. render_callback또는render.php를 사용하는 동적 블록은save함수가 필요 없으며, 대신 서버 측에서 HTML을 생성합니다.