WordPress의 구텐베르크 블록 편집기(Gutenberg Block Editor)는 콘텐츠 생성 방식을 완전히 바꾸었으며, 페이지 구성의 유연성과 제어권을 편집자에게 직접 제공합니다. 개발자에게 있어 이는 React와 현대적인 JavaScript를 기반으로 한 새로운 개발 패러다임을 의미합니다. 이 글에서는 처음부터 사용자 정의 블록을 만드는 방법부터 동적 블록을 개발하고 블록 변형을 적용하는 등의 고급 기능까지 자세히 살펴보며, 실전적인 개발 가이드를 제공할 것입니다.
이해하기: 블록 편집기의 핵심 아키텍처
구텐베르크 에디터(Gutenberg Editor)는 단일한 애플리케이션이 아니라, 여러 개의 독립적인 패키지(Packages)로 구성된 생태계입니다. 이러한 아키텍처를 이해하는 것은 효과적인 개발을 위한 기초입니다.
편집기와 데이터 계층의 분리 (Editor and Data Layer Separation)
편집기 인터페이스 자체는 WordPress의 데이터 계층과는 분리되어 있습니다. 코어 부분은… @wordpress/editor 이 패키지는 편집기의 UI 구성 요소를 제공합니다. @wordpress/data `Pack`는 Redux와 유사한 상태 관리 기능을 구현합니다. 이러한 분리 덕분에 개발자들은 블록의 뷰와 상호작용 로직에 집중할 수 있으며, 데이터의 영구 저장은 WordPress의 핵심 메커니즘에 의해 자동으로 처리됩니다.
추천 읽기 WordPress 사용자 정의 글 유형을 마스터하기: 생성부터 게시까지의 실전 가이드。
블록의 등록 및 라이프사이클
각 블록은 반드시 통과해야 합니다. registerBlockType 이 함수는 등록을 위해 사용됩니다. 이 함수는 두 개의 매개변수를 받습니다: 블록의 고유한 이름(예: my-plugin/my-custom-block)과 블록의 모든 구성 정보를 포함하는 객체입니다.
등록 후, 블록은 초기화, 렌더링, 편집, 저장 등의 라이프사이클을 거칩니다. 개발자들은 주로 정의를 통해 이러한 과정을 제어합니다. edit 그리고 save 두 개의 핵심 함수를 사용하여 블록이 편집기 내에서와 프론트엔드에서 어떻게 표시되는지를 제어합니다.
제로에서 시작하여 첫 번째 사용자 정의 블록을 만들어 보세요.
우리는 사용자가 배경색과 제목이 있는 힌트 상자를 추가할 수 있는 간단한 “하이라이트 힌트” 기능을 만들 것입니다.
개발 환경 설정 및 기본 파일 준비하기
먼저, 개발 환경이 준비되어 있는지 확인하세요. Node.js와 npm이 필요합니다. 플러그인 디렉터리 내에 새로운 플러그인 폴더를 생성하세요. 예를 들어, `my-new-plugin`와 같은 이름으로 폴더를 만들면 됩니다. my-custom-blocks해당 폴더에 다음과 같은 핵심 파일들을 생성하세요:
- my-custom-blocks.php (플러그인의 주 파일)
- package.json (Node.js 의존성 및 빌드 스크립트를 관리하는 데 사용됩니다.)
- src/ 목록 (소스 코드를 저장하는 데 사용됨)
- build/ 목록 (빌드 도구가 생성한 디렉터리로, WordPress에서 읽어옵니다)
In package.json 중에서, 빌드 스크립트를 설정하고 해당 스크립트를 가져옵니다. @wordpress/scripts `pack`은 Webpack, Babel과 같은 도구의 설정을 크게 단순화할 수 있습니다.
{
"name": "my-custom-blocks",
"scripts": {
"build": "wp-scripts build",
"start": "wp-scripts start"
},
"devDependencies": {
"@wordpress/scripts": "^26.0.0"
}
}플러그인의 메인 파일 내에서… my-custom-blocks.php 여기서, 당신은 register_block_type 이 함수는 WordPress에 특정 정보를 전달하여 워드프레스가 필요한 작업을 수행하도록 합니다. build 디렉터리 로딩 블록의 자산들.
추천 읽기 WordPress 테마 개발 가이드: 제로에서 시작하여 고성능의 커스텀 테마를 구축하기。
<?php
/**
* Plugin Name: My Custom Blocks
*/
function my_custom_blocks_register_block() {
register_block_type( __DIR__ . '/build/highlight-box' );
}
add_action( 'init', 'my_custom_blocks_register_block' );블록의 자바스크립트 소스 코드를 작성하세요.
In src 디렉터리 내에 파일을 생성합니다. highlight-box/index.js 파일입니다. 이 파일은 블록의 주요 입구 파일입니다.
import { registerBlockType } from '@wordpress/blocks';
import { RichText, useBlockProps, InspectorControls, ColorPalette } from '@wordpress/block-editor';
import { PanelBody, PanelRow } from '@wordpress/components';
registerBlockType('my-custom-blocks/highlight-box', {
title: '高亮提示框',
icon: 'warning', // 从 Dashicons 中选择
category: 'design',
attributes: {
title: {
type: 'string',
source: 'html',
selector: '.highlight-title',
},
content: {
type: 'string',
source: 'html',
selector: '.highlight-content',
},
backgroundColor: {
type: 'string',
default: '#fff3cd',
},
},
edit: ({ attributes, setAttributes }) => {
const blockProps = useBlockProps();
const { title, content, backgroundColor } = attributes;
const onChangeTitle = (newTitle) => {
setAttributes({ title: newTitle });
};
const onChangeContent = (newContent) => {
setAttributes({ content: newContent });
};
const onChangeBackgroundColor = (newColor) => {
setAttributes({ backgroundColor: newColor });
};
return (
<>
<inspectorcontrols>
<panelbody title="색상 설정">
<panelrow>
<colorpalette
value="{backgroundColor}"
onchange="{onChangeBackgroundColor}"
/>
</panelrow>
</panelbody>
</inspectorcontrols>
<div {...blockprops} style="{{" backgroundcolor, padding: '20px', borderradius: '5px' }}>
<richtext
tagname="h3"
classname="highlight-title"
onchange="{onChangeTitle}"
value="{title}"
placeholder="输入标题..."
/>
<richtext
tagname="p"
classname="highlight-content"
onchange="{onChangeContent}"
value="{content}"
placeholder="输入提示内容..."
/>
</div>
</>
);
},
save: ({ attributes }) => {
const blockProps = useBlockProps.save();
const { title, content, backgroundColor } = attributes;
return (
<div {...blockprops} style="{{" backgroundcolor, padding: '20px', borderradius: '5px' }}>
<RichText.Content tagName="h3" className="highlight-title" value={title} />
<RichText.Content tagName="p" className="highlight-content" value={content} />
</div>
);
},
});움직여야 합니다. npm start 개발 모드를 시작합니다 (파일 변경을 감지합니다). npm run build 생산용 코드를 빌드합니다. 그 후 WordPress 편집기에서 “디자인” 카테고리를 찾아보면 “강조 표시 상자” 블록을 찾아 사용할 수 있습니다.
고급 개발: 동적 블록 및 서버 측 렌더링
정적 블록의 내용은 기사 본문에 직접 저장됩니다. 하지만 최신 기사 목록이나 사용자 정보와 같이 실시간 데이터가 필요한 블록의 경우에는 동적 블록을 생성해야 합니다. 동적 블록은 저장 시 일부 속성(예: 기사 수)만 저장하며, 프론트엔드에서 PHP 템플릿을 사용하여 동적으로 콘텐츠를 생성하여 표시합니다.
정적 블록을 동적 블록으로 변환하기
먼저, 블록의 등록 설정을 수정하여… save 함수를 반환하는 형태로 수정하세요. null그리고 하나를 더 추가하세요. render_callback 속성.
// 在 registerBlockType 的配置对象中
save: () => {
return null; // 动态区块不在内容中保存 HTML
},그런 다음, PHP 측에서 등록 코드를 업데이트하여 렌더링 콜백 함수를 지정해야 합니다.
function my_custom_blocks_register_dynamic_block() {
register_block_type( __DIR__ . '/build/latest-posts', [
'render_callback' => 'my_custom_blocks_render_latest_posts'
] );
}
add_action( 'init', 'my_custom_blocks_register_dynamic_block' );
function my_custom_blocks_render_latest_posts( $attributes ) {
$posts = get_posts( [
'posts_per_page' => $attributes['numberOfPosts'] ?? 5,
] );
if ( empty( $posts ) ) {
return '<p>현재 기사가 없습니다.</p>'$output = '<ul class="wp-block-my-custom-blocks-latest-posts">';
foreach ( $posts as $post ) {
$output .= sprintf(
'<li><a href="/ko/%s/">\n%s</a></li>'php
esc_url(get_permalink($post));
esc_html(get_the_title($post));
$output .= '';'</ul>';
return $output;
}블록 템플릿 파일을 사용하여 렌더링을 수행합니다.
보다 복잡한 동적 블록의 경우, 템플릿 파일을 사용하는 것이 추천됩니다. 플러그인 디렉터리에 템플릿 파일을 생성하세요. templates/latest-posts.php위의 렌더링 로직을 해당 파일로 옮긴 다음, 그 파일 내에서 필요한 처리를 수행하세요. render_callback 중국에서 사용하세요. ob_get_clean 그리고 include 템플릿을 로드함으로써 PHP와 HTML의 논리가 더 명확해지고 유지보수가 용이해집니다.
추천 읽기 WooCommerce 플러그인 사용 안내서: 설치 및 설정부터 매장 운영까지의 완전한 가이드。
고급 주제 및 모범 사례 (Advanced Topics and Best Practices)
기본적인 블록과 동적 블록의 사용법을 익혔다면, 다음 주제들을 통해 더 강력하고 전문적인 블록들을 개발할 수 있을 것입니다.
블록의 변형 기능을 구현합니다.
“블록 변형(Block Variations)” 기능을 사용하면 기본 블록을 기반으로 여러 가지 사전 정의된 스타일이나 설정을 생성할 수 있습니다. 예를 들어, “강조 표시 상자(highlight提示框)”를 위해 “성공”, “경고”, ‘오류’와 같은 다양한 변형을 만들 수 있습니다.
import { registerBlockVariation } from '@wordpress/blocks';
registerBlockVariation('my-custom-blocks/highlight-box', [
{
name: 'success',
title: '成功提示',
icon: 'yes-alt',
attributes: {
title: '操作成功',
backgroundColor: '#d4edda',
},
isDefault: false,
},
{
name: 'error',
title: '错误警告',
icon: 'dismiss',
attributes: {
title: '发生错误',
backgroundColor: '#f8d7da',
},
},
]);블록 스타일과 에디터 스타일을 활용하기
활용 registerBlockStyle 이 함수를 사용하면 블록에 다양한 시각적 스타일을 적용할 수 있으며, 사용자는 사이드바에서 원하는 스타일을 선택하여 적용할 수 있습니다. add_editor_style 편집기 내의 미리보기가 프론트엔드 스타일과 일치하도록 보장하여, 사용자가 실제로 보는 대로 결과가 나오는 ‘보이는 그대로의 경험’을 제공할 수 있습니다.
성능 최적화와 코드 분할 (Performance Optimization and Code Splitting)
블록의 수가 증가함에 따라 모든 JavaScript 코드를 하나의 파일에 패키징하면 로딩 성능에 영향을 미칩니다. 이를 해결하기 위한 방법을 활용할 수 있습니다. @wordpress/dependency-extraction-webpack-plugin(이미 포함되어 있습니다.) @wordpress/scripts 중) WordPress 패키지에 대한 외부 의존성을 올바르게 선언하는 것을 확인하세요. 대형 플러그인의 경우, 필요에 따라 코드를 로드하거나 코드를 분할하는 기술을 고려해 볼 수 있습니다.
요약
구텐베르크 블록 편집기(Gutenberg Block Editor)의 개발은 현대적인 프론트엔드 기술(React, JSX, Webpack)과 전통적인 WordPress PHP 지식을 결합한 과정입니다. 먼저 그 아키텍처를 이해하는 것부터 시작하여, 정적 블록을 생성함으로써 핵심 API를 익힌 다음, 동적 데이터를 처리하는 동적 블록 기능으로 발전시킵니다. 마지막으로 블록 변형, 스타일링과 같은 고급 기능을 통해 사용자 경험과 개발 효율성을 향상시킵니다. 명확한 코드 구조, 성능 최적화, 충분한 국제화 준비와 같은 모범 사례를 따르면, 강력하고 유지보수가 용이하며 사용자 친화적인 커스텀 블록을 구축할 수 있으며, 구텐베르크 편집기의 잠재력을 최대한 발휘할 수 있습니다.
자주 묻는 질문
구텐베르크 블록(Gutenberg Block)을 개발할 때 반드시 React를 사용해야 합니까?
네, 현재 구텐베르크 에디터(Gutenberg Editor)의 공식 개발 방식은 완전히 React를 기반으로 하고 있습니다. 이론적으로는 다른 프레임워크를 사용할 수도 있지만, WordPress 코어에서 제공하는 모든 컴포넌트, 훅(hook), 도구들은 React 생태계를 중심으로 구축되어 있기 때문에 다른 프레임워크를 사용하면 상당한 복잡성과 호환성 문제가 발생할 수 있습니다.
어떻게 제 블록에 사용자 정의 사이드바 컨트롤을 추가할 수 있나요?
당신은 사용할 수 있습니다. <code>InspectorControls</code> Component. Within the block. edit 함수 내에서, 이 내용을 메인 프리뷰 콘텐츠와 함께 반환하세요. <code>InspectorControls</code> 내부에서는 사용하실 수 있습니다. <code>PanelBody</code>、<code>TextControl</code>、<code>SelectControl</code>、<code>RangeControl</code></code> 等来自 `@wordpress/components` 패키지에 포함된 컴포넌트들을 사용하여 풍부하고 사용자 친화적인 설정 인터페이스를 구축할 수 있습니다.
동적 블록과 정적 블록의 성능상 차이점은 무엇인가요?
정적 블록의 HTML 콘텐츠는 데이터베이스의 게시물 내용에 직접 저장되어 있기 때문에 프론트엔드의 로딩 속도가 매우 빠릅니다. 하지만 동적 데이터를 포함할 수는 없습니다. 동적 블록은 렌더링 시 PHP 코드를 실행하여 데이터베이스에서 데이터를 조회해야 하므로 약간의 성능 저하가 발생하지만, 실시간 데이터를 제공할 수 있습니다. 자주 변경되지 않는 콘텐츠의 경우 정적 블록과 정기적인 캐싱 전략을 결합하는 것을 고려할 수 있으며, 높은 실시간성이 필요한 콘텐츠의 경우에는 반드시 동적 블록을 사용해야 합니다.
전통적인 작은 도구 영역이나 기사 메타 정보 상자에서 블록을 사용할 수 있나요?
네, 이를 “블록 위젯(block widgets)”과 “블록 메타박스(block meta boxes)”라고 부릅니다. WordPress 5.8부터는 위젯 영역도 전적으로 구텐베르크 블록 편집기(Gutenberg Block Editor)를 통해 관리됩니다. 사용하실 수도 있습니다. register_block_type 의 widget_types 블록을 툴바 편집기에서 사용할 수 있도록 하려면 해당 매개변수(또는 관련 API)를 사용해야 합니다. 기사 메타 정보 상자의 경우, ``를 사용할 수 있습니다.register_post_meta API와 블록을 결합하여 보다 직관적인 메타데이터 편집 인터페이스를 만듭니다.
다음 단계는 무엇인가요?
확장된 독서 및 실무 지식
다음은 이 도움말의 주제와 관련이 있으며 더 깊이 있게 읽기에 적합합니다. 현재 문제와 가장 가까운 문서부터 시작하여 점차 주변 주제로 확장하는 것이 우선순위를 정하는 것이 좋습니다.
한국어