워드프레스 블록 테마 패턴 블록을 올바르게 사용하는 방법

아래 글은 워드프레스 블록 테마에서 “쿼리( Query )”를 패턴/템플릿에 올바르게 쓰는 법을 정리한 설명서입니다. 복사-붙여넣기 시 특수문자 문제 없도록 평문과 최소 코드만 사용했습니다.

블록 테마에서 쿼리를 쓰는 3가지 방식

블록 테마에서는 core/query(Query Loop) 블록으로 글 목록을 표시합니다. 실제로는 아래 3가지 패턴으로 쓰게 됩니다.

아카이브/블로그 인덱스용 쿼리: 메인 쿼리 상속
일반 페이지/랜딩용 쿼리: 독립 쿼리
아이템 전용 패턴: Post Template 내부 전용

각 방식은 “어디에 배치하는가”와 “페이지네이션/타이틀과의 일치”가 핵심입니다.

1) 아카이브용: 메인 쿼리 상속(inherit:true)

아카이브(카테고리, 태그, 날짜, 작성자 등) 템플릿에서는 이미 “메인 쿼리”가 있습니다. 이때 Query Loop를 이렇게 쓰면, 아카이브 타이틀(core/query-title)과 페이지네이션이 정확히 맞습니다.

예시(패턴 또는 템플릿에 삽입):

<!-- wp:query {"inherit":true,"layout":{"type":"constrained"}} -->
  <!-- wp:post-template {"layout":{"type":"grid","columnCount":3,"minimumColumnWidth":"240px"}} -->
    <!-- wp:post-featured-image {"isLink":true,"width":"100%"} /-->
    <!-- wp:post-title {"isLink":true} /-->
    <!-- wp:post-excerpt {"moreText":"더 읽기"} /-->
  <!-- /wp:post-template -->

  <!-- wp:query-no-results -->
    <p class="has-text-align-center">게시된 글이 없습니다.</p>
  <!-- /wp:query-no-results -->

  <!-- wp:query-pagination {"layout":{"type":"flex","justifyContent":"space-between"}} -->
    <!-- wp:query-pagination-previous /-->
    <!-- wp:query-pagination-numbers /-->
    <!-- wp:query-pagination-next /-->
  <!-- /wp:query-pagination -->
<!-- /wp:query -->

포인트:

inherit:true 이면 쿼리 파라미터를 따로 지정하지 않습니다.
grid/flex 같은 레이아웃은 Post Template 쪽(반복 아이템 영역)에만 지정하는 것을 권장합니다.

2) 일반 페이지/랜딩용: 독립 쿼리

정적 페이지나 랜딩에서 최신 글 몇 개를 보여주고 싶다면 “독립 쿼리”를 씁니다. 메인 쿼리를 상속하지 않고, 필요한 파라미터만 짧게 지정합니다.

예시:

<!-- wp:query {"query":{"perPage":6,"postType":"post","order":"desc","orderBy":"date"},"layout":{"type":"constrained"}} -->
  <!-- wp:post-template {"layout":{"type":"grid","columnCount":3,"minimumColumnWidth":"240px"}} -->
    <!-- wp:post-featured-image {"isLink":true,"width":"100%"} /-->
    <!-- wp:post-title {"isLink":true} /-->
    <!-- wp:post-excerpt {"moreText":"더 읽기"} /-->
  <!-- /wp:post-template -->

  <!-- wp:query-no-results -->
    <p class="has-text-align-center">게시된 글이 없습니다.</p>
  <!-- /wp:query-no-results -->

  <!-- wp:query-pagination {"layout":{"type":"flex","justifyContent":"space-between"}} -->
    <!-- wp:query-pagination-previous /-->
    <!-- wp:query-pagination-numbers /-->
    <!-- wp:query-pagination-next /-->
  <!-- /wp:query-pagination -->
<!-- /wp:query -->

포인트:

페이지네이션과 타이틀은 “아카이브 컨텍스트”와 무관합니다.
랜딩에선 보통 페이지네이션을 숨기고 최신 N개만 보여주는 구성도 자주 씁니다.

3) 아이템 전용 패턴: Query Loop 내부에서만 사용

Query Loop 내부(= Post Template 영역)에만 들어갈 “카드 레이아웃”을 패턴으로 만들어 두면 재사용이 쉽습니다. 이 패턴은 쿼리를 포함하지 않고 아이템 구성만 정의합니다.

예시(아이템 패턴 본문):

<!-- wp:post-featured-image {"isLink":true,"width":"100%"} /-->
<!-- wp:post-title {"isLink":true} /-->
<!-- wp:post-excerpt {"moreText":"더 읽기"} /-->

사용법:

* 템플릿 또는 페이지에서 Query Loop를 만든 뒤, Post Template 내부에 위 패턴을 인서트합니다.

패턴 노출 범위 제한으로 UX 개선하기

패턴을 어디서 보이게 할지 제한하면 사용자가 헷갈리지 않습니다.

* 아카이브용 패턴: Post Types를 wp_template로 제한
(사이트 편집기의 템플릿 편집 화면에서만 보이게)

* 페이지용 패턴: Post Types를 page로 제한
(일반 페이지 편집기에서만 보이게)

* 아이템 전용 패턴: Block Types를 core/post-template로 제한
(Query Loop의 Post Template 내부에서만 보이게)

패턴 파일 헤더 예시(설명용, 실제 코드 아님):

/**
 * Title: Post Grid (Archive - Inherit)
 * Slug: yourtheme/post-grid
 * Categories: query
 * Post Types: wp_template
 * Description: 아카이브 템플릿에서 메인 쿼리를 상속하는 그리드.
 */

/**
 * Title: Post Grid (Standalone - Page)
 * Slug: yourtheme/post-grid-standalone
 * Categories: query
 * Post Types: page
 * Description: 페이지/랜딩에서 독립 쿼리로 최신 글을 표시.
 */

/**
 * Title: Post Grid Item (Card)
 * Slug: yourtheme/post-grid-item
 * Categories: query
 * Block Types: core/post-template
 * Description: Query Loop 아이템 카드 전용 레이아웃.
 */

핵심 효과: