theme.json을 사용자 정의 포스트 유형 및 플러그인 출력으로 확장: 실용 가이드

요약

많은 WordPress 개발자는 사용자 정의 포스트 유형이나 플러그인(예: 추천글, 포트폴리오)을 통해 콘텐츠를 출력합니다. 그러나 글로벌 스타일을 위한 중앙 구성 파일인 theme.json은 기본적으로 이러한 사용자 정의 요소를 무시하여 디자인이 일관되지 않을 수 있습니다. 이 글에서는 사용자 정의 포스트 유형이 theme.json 스타일을 상속받도록 등록하고, 특정 블록의 설정을 재정의하며, 플러그인 출력을 핵심 디자인 토큰과 연결하는 방법을 단계별로 안내합니다. '팀 멤버' CPT 스타일링 같은 실제 예제와 성능 및 타사 플러그인 충돌에 대한 주의사항을 제공합니다. 이 과정을 마치면 모든 사용자 정의 콘텐츠가 사이트의 편집기에서 정의한 디자인 시스템과 일치하도록 할 수 있습니다.

사용자 정의 포스트 유형을 만들거나 타사 플러그인을 통합한 후, 해당 출력이 theme.json에서 정성스럽게 구성한 아름다운 디자인 시스템을 완전히 무시하는 경험을 해보셨나요? 당신만 그런 것이 아닙니다. 기본적으로 theme.json은 핵심 WordPress 블록과 등록된 블록 스타일에만 적용되며, 사용자 정의 포스트 유형 및 플러그인 생성 콘텐츠는 스스로 처리해야 합니다. 그 결과 인라인 CSS, 중복된 글꼴 스택, 사용자 경험을 해치는 색상 팔레트 불일치가 발생합니다. 하지만 더 나은 방법이 있습니다: theme.json을 이러한 사용자 정의 요소로 확장하여 사이트 전체에서 일관되고 유지 관리 가능한 디자인 시스템을 보장할 수 있습니다. 이 가이드에서는 코드 예제와 실제 주의사항과 함께 이를 실현하는 네 가지 실용적인 단계를 다룹니다.

theme.json 범위 이해

시작하기 전에 theme.json이 블록 테마 개념이라는 점을 이해하는 것이 중요합니다. 이는 블록 편집기와 프론트 엔드에 대한 글로벌 스타일, 설정(색상 팔레트 및 글꼴 크기 등), 블록별 스타일을 정의합니다. 그러나 그 범위는 제한적입니다: register_block_type 또는 이전 add_theme_support를 통해 theme.json 속성을 명시적으로 지원하는 블록만 제어합니다. register_post_type으로 생성된 사용자 정의 포스트 유형은 블록으로 구축되거나 명시적으로 스타일링되지 않는 한 이러한 스타일을 자동으로 상속받지 않습니다.

1단계: 블록 편집기 지원으로 사용자 정의 포스트 유형 등록

첫 번째 단계는 사용자 정의 포스트 유형이 블록 편집기를 사용하도록 하는 것입니다. register_post_type을 호출할 때 'show_in_rest' => true로 설정하고 'editor'를 supports 배열에 포함시킵니다. 이렇게 하면 해당 포스트 유형에 블록 편집기가 활성화되어 작성자가 theme.json의 블록 수준 스타일을 사용할 수 있습니다. 예를 들어, '팀 멤버' CPT는 다음과 같습니다:

function create_team_member_cpt() {
    $args = array(
        'public' => true,
        'show_in_rest' => true,
        'supports' => array( 'title', 'editor', 'thumbnail', 'custom-fields' ),
        'show_in_menu' => true,
        'labels' => array(
            'name' => 'Team Members',
            'singular_name' => 'Team Member',
        ),
        'rewrite' => array( 'slug' => 'team' ),
    );
    register_post_type( 'team_member', $args );
}
add_action( 'init', 'create_team_member_cpt' );

이제 팀 멤버 포스트를 편집하면 단락, 제목, 이미지와 같은 핵심 블록에 테마의 글로벌 스타일이 적용된 블록 편집기를 볼 수 있습니다. 이 단계만으로도 대부분의 스타일 문제가 해결됩니다. 더 세밀한 제어가 필요하면 다음 단계로 진행하세요. 블록 테마를 theme.json으로 구축하는 방법에 대한 자세한 내용은 How to Build a Custom WordPress Block Theme with theme.json을 참조하세요.

2단계: theme.json을 통해 사용자 정의 블록 스타일 추가

때로는 사용자 정의 포스트 유형 콘텐츠의 모든 인스턴스에 특정 스타일을 적용하고 싶을 수 있습니다(예: 전체 포스트에 배경색이나 특별한 패딩을 지정). core/post-content를 타겟팅하거나 콘텐츠를 사용자 정의 그룹 블록으로 감싸서 theme.json을 통해 스타일을 지정할 수 있습니다. theme.json 파일의 styles 객체에 다음을 추가하세요:

{
  "styles": {
    "blocks": {
      "core/post-content": {
        "css": "background-color: var(--wp--preset--color--light); padding: 2rem;"
      }
    }
  }
}

이렇게 하면 팀 멤버 CPT를 포함한 모든 포스트의 콘텐츠 영역에 밝은 배경색과 패딩이 적용됩니다. 또한 settings.blocks 내부에 블록별 변형을 정의하여 편집기에서 스타일 옵션을 제공할 수도 있습니다.

3단계: 플러그인 출력에 theme.json 사용자 정의 속성 사용

플러그인은 종종 숏코드, 위젯 또는 사용자 정의 블록을 통해 콘텐츠를 출력합니다. 이러한 요소에 일관된 스타일을 적용하려면 theme.json이 생성하는 CSS 사용자 정의 속성을 활용하세요. 예를 들어, 테마에서 기본 색상을 --wp--preset--color--primary로 정의한 경우 플러그인의 CSS에서 이를 사용할 수 있습니다:

.my-plugin-button {
    background-color: var(--wp--preset--color--primary);
    font-size: var(--wp--preset--font-size--medium);
}

이렇게 하면 사이트 관리자가 theme.json에서 색상 팔레트를 변경할 때 플러그인의 버튼이 자동으로 업데이트됩니다. 견고하게 만들려면 항상 사전 설정된 CSS 변수를 사용하고 값을 하드코딩하지 마세요. 또한 플러그인이 자체 블록을 등록하는 경우 JavaScript에서 useSetting을 사용하거나 PHP 렌더링에서 $attributes를 전달하여 theme.json 설정을 상속받을 수 있습니다. 이에 대한 자세한 내용은 Mastering WordPress Dynamic Blocks를 참조하세요.

4단계: 동적 블록 처리

동적 콘텐츠를 출력하는 사용자 정의 블록(예: 추천글 슬라이더)의 경우 블록 편집기 지원으로 블록을 등록하고 theme.json에 명시적으로 연결해야 합니다. PHP에서 register_block_type을 'render_callback'을 포함한 $args와 함께 사용하고, 블록의 block.json 파일에서 'supports' => array( 'color' => true, 'typography' => true )를 설정하세요. 그런 다음 렌더 콜백에서 wp_get_global_styles()를 통해 글로벌 스타일에 접근하여 적용할 수 있습니다. 예를 들어:

function render_testimonial_block( $attributes, $content ) {
    $styles = wp_get_global_styles();
    $color = $styles['elements']['link']['color']['text'] ?? '#000';
    return '<div style="color: ' . esc_attr( $color ) . ';">' . $content . '</div>';
}

이 방법은 사용자 정의 블록이 테마의 디자인 토큰을 존중하도록 보장합니다. 블록 등록에 대한 자세한 내용은 Building Robust WordPress Plugins를 참조하세요.

주의사항

theme.json 확장은 강력하지만 다음 함정에 주의하세요:

1. 성능: theme.json에 너무 많은 사용자 정의 스타일을 추가하면 파일이 비대해지고 CSS 파싱 시간이 증가할 수 있습니다. 글로벌 설정을 유지하고 블록별 스타일은 신중하게 사용하세요.
2. 플러그인 충돌: 일부 플러그인은 theme.json 설정을 재설정하거나 재정의합니다. 최소한의 플러그인 세트로 테스트하고 after_setup_theme에 후크하여 사용자 정의를 다시 적용하는 것을 고려하세요.
3. 클래식 테마: 테마가 블록 편집기를 사용하지 않는 경우(즉, 클래식 테마인 경우) theme.json의 효과는 제한적입니다. 블록 테마로 마이그레이션하거나 wp_enqueue_global_styles 함수를 사용하여 스타일을 로드하는 것을 고려하세요.
4. 브라우저 캐시: theme.json 변경 사항이 캐싱으로 인해 즉시 나타나지 않을 수 있습니다. 브라우저 캐시를 지우고 스타일시트에 버전 관리를 사용하세요.

결론

이제 사용자 정의 포스트 유형과 플러그인 출력이 theme.json 디자인 시스템과 잘 연동되도록 하는 명확한 로드맵을 갖추셨습니다. 핵심은 블록 편집기 지원으로 CPT를 등록하고, 포스트 콘텐츠 블록에 특정 스타일을 정의하고, 플러그인 출력에 CSS 사용자 정의 속성을 사용하며, 적절한 theme.json 통합으로 사용자 정의 블록을 등록하는 것입니다. 이 접근 방식은 불일치를 제거하고 유지 관리를 줄이며 사이트 관리자가 단일 진실 공급원에서 모양과 느낌을 제어할 수 있는 권한을 부여합니다. 지금 이 단계를 구현하여 WordPress 프로젝트에 통일성을 가져오세요.