본문으로 건너뛰기

ACF Blocks에서 마이그레이션하기

ACF(Advanced Custom Fields)로 사용자 지정 WordPress 블록을 만들어 왔다면 Blockstudio로 마이그레이션하는 과정은 간단합니다. 개념은 비슷합니다. 필드를 정의하고, 템플릿을 작성하면 편집기에 블록이 표시됩니다. 차이점은 Blockstudio가 블록 폴더를 자동으로 찾고, block.json 안의 자체 스키마에 필드를 선언하며, 각 템플릿에 필드 값을 하나의 $a 배열로 전달한다는 것입니다.

이 가이드에서는 ACF과 Blockstudio의 패턴을 나란히 비교하며 마이그레이션 과정을 단계별로 살펴봅니다.

핵심 차이점

ACF 6.0부터 ACF 블록은 렌더링 템플릿을 지정하는 acf 키가 있는 block.json이며, 각 블록 폴더는 자체 register_block_type() 호출로 등록됩니다. 필드는 Block 위치 규칙이 적용된 필드 그룹(관리자 화면에서 만들거나, Local JSON로 동기화하거나, acf_add_local_field_group()로 등록)에서 가져오거나, ACF PRO 6.8.1부터는 같은 block.json 안의 인라인 acf.fields 배열에서 가져옵니다. Blockstudio은 등록 호출을 파일 기반 자동 검색으로 대체합니다. block.json와 index.php이 있는 폴더를 만들면 블록이 자동으로 등록됩니다.

ACF:

JSON
{
  "name": "acf/hero",
  "title": "Hero",
  "acf": {
    "renderTemplate": "template.php"
  }
}
PHP
add_action( 'init', function () {
  register_block_type( __DIR__ . '/blocks/hero' );
} );
PHP
acf_add_local_field_group([
  'key'      => 'group_hero',
  'title'    => 'Hero Fields',
  'fields'   => [
    ['key' => 'field_title', 'name' => 'title', 'type' => 'text', 'label' => 'Title'],
    ['key' => 'field_image', 'name' => 'image', 'type' => 'image', 'label' => 'Background', 'return_format' => 'array'],
  ],
  'location' => [[['param' => 'block', 'operator' => '==', 'value' => 'acf/hero']]],
]);
PHP
<?php
$title = get_field('title');
$image = get_field('image');
?>
<div class="hero" <?php if ($image) : ?>style="background-image: url(<?php echo esc_url($image['url']); ?>)"<?php endif; ?>>
  <h1><?php echo esc_html($title); ?></h1>
</div>

Blockstudio:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "title", "type": "text", "label": "Title" },
      { "id": "image", "type": "files", "label": "Background", "multiple": false }
    ]
  }
}
PHP
<div useBlockProps class="hero" <?php if ($a['image']) : ?>style="background-image: url(<?php echo esc_url($a['image']['url']); ?>)"<?php endif; ?>>
  <h1><?php echo esc_html($a['title']); ?></h1>
</div>

등록 호출과 렌더 콜백이 없습니다. 폴더 구조 자체가 등록이며, 필드는 템플릿 옆의 block.json에 있습니다. 템플릿에서는 get_field()를 호출하는 대신 $a을 읽습니다.

블록 등록

ACF

현재 ACF 블록은 acf 키(renderTemplate 또는 renderCallback, 그리고 blockVersion 같은 옵션)가 있는 block.json에서 등록하며, 일반적으로 functions.php의 init 또는 플러그인 파일에서 블록 폴더별로 명시적인 register_block_type() 호출을 사용해 불러옵니다. 이전 블록은 여전히 acf_register_block_type()을 사용할 수 있습니다. ACF은 ACF 6.0부터 이를 지원 중단으로 안내하고 있지만 계속 작동하므로, 해당 블록도 같은 방식으로 마이그레이션하세요.

Blockstudio

테마의 blockstudio/ 디렉터리(원하는 경우 blocks/)에 폴더를 만드세요. 표준 WordPress 블록 메타데이터와 blockstudio 키가 포함된 block.json을 추가하면 됩니다.

코드
theme/
└── blockstudio/
    └── hero/
        ├── block.json
        └── index.php

block.json은 필드와 구성을 위해 blockstudio 키를 사용하는 표준 WordPress block.json 형식을 사용합니다.

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "category": "theme",
  "icon": "cover-image",
  "description": "Full-width hero section with background image.",
  "blockstudio": {
    "attributes": []
  }
}

필드 값에 접근하기

마이그레이션 과정에서 가장 자주 변경하게 될 부분입니다.

ACF Blockstudio
get_field('title') $a['title']
get_field('title', $post_id) $a['title'] (항상 사용 가능)
the_field('title') <?php echo $a['title']; ?>
have_rows('items') / the_row() foreach ($a['items'] as $item)
get_sub_field('name') $item['name']

$a 변수는 $attributes의 줄임 표현이며 현재 블록의 모든 필드 값을 포함합니다. 편집기와 프런트엔드 모두에서 템플릿에 항상 사용할 수 있습니다.

템플릿 변수

Blockstudio는 모든 템플릿에서 여러 변수를 제공합니다.

변수 줄임 표현 설명
$attributes $a 모든 필드 값
$block $b 블록 메타데이터(이름, 제목, dir, url, postId)
$context $c 상위 블록 컨텍스트
$content InnerBlocks 콘텐츠
$post_id 현재 글 ID(편집기와 프런트엔드에서 작동하며 Twig에서는 post_id 또는 postId)

필드 유형 매핑

대부분의 ACF 필드 유형은 Blockstudio에서 직접 대응하는 유형이 있습니다. JSON 문법은 다르지만 개념은 자연스럽게 연결됩니다.

텍스트 및 콘텐츠 필드

ACF:

PHP
['name' => 'title', 'type' => 'text', 'label' => 'Title', 'default_value' => 'Hello']
['name' => 'bio', 'type' => 'textarea', 'label' => 'Bio', 'rows' => 4]
['name' => 'content', 'type' => 'wysiwyg', 'label' => 'Content']

Blockstudio:

JSON
{ "id": "title", "type": "text", "label": "Title", "default": "Hello" }
{ "id": "bio", "type": "textarea", "label": "Bio", "rows": 4 }
{ "id": "content", "type": "wysiwyg", "label": "Content" }

블록 편집기에서 편집 가능한 텍스트(단순한 텍스트 입력란이 아닌)를 사용하려면 <RichText /> 컴포넌트와 함께 richtext 유형을 사용하세요.

JSON
{ "id": "heading", "type": "richtext" }
PHP
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />

이미지 및 파일 필드

ACF의 image 및 file 필드는 Blockstudio의 files 유형에 대응합니다.

ACF:

PHP
['name' => 'photo', 'type' => 'image', 'return_format' => 'array']
['name' => 'gallery', 'type' => 'gallery', 'return_format' => 'array']
['name' => 'document', 'type' => 'file', 'return_format' => 'array']

Blockstudio:

JSON
{ "id": "photo", "type": "files", "label": "Photo", "multiple": false }
{ "id": "gallery", "type": "files", "label": "Gallery", "multiple": true }
{ "id": "document", "type": "files", "label": "Document", "multiple": false, "allowedTypes": ["application/pdf"] }

반환되는 객체 구조도 비슷합니다.

PHP
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];

// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];

사용 가능한 속성: ID, title, alt, caption, description, href, url, sizes. 크기는 sizes에 있으며, 예를 들면 $a['photo']['sizes']['full-width']입니다.

선택, 라디오, 체크박스

ACF:

PHP
[
  'name' => 'color',
  'type' => 'select',
  'choices' => ['red' => 'Red', 'blue' => 'Blue'],
  'return_format' => 'value',
]

Blockstudio:

JSON
{
  "id": "color",
  "type": "select",
  "label": "Color",
  "options": [
    { "value": "red", "label": "Red" },
    { "value": "blue", "label": "Blue" }
  ]
}

값과 레이블을 모두 가져오려면 "returnFormat": "both"을 사용하세요.

PHP
echo $a['color']['value'];  // "red"
echo $a['color']['label'];  // "Red"

같은 패턴을 radio 및 checkbox 유형에도 적용할 수 있습니다.

토글 및 참/거짓

ACF:

PHP
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']

Blockstudio:

JSON
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }

ACF:

PHP
['name' => 'cta', 'type' => 'link', 'return_format' => 'array']

// Template
$link = get_field('cta');
echo $link['url'];
echo $link['title'];
echo $link['target'];

Blockstudio:

JSON
{ "id": "cta", "type": "link", "label": "CTA", "opensInNewTab": true }
PHP
echo $a['cta']['url'];
echo $a['cta']['title'];
echo $a['cta']['target'];

색상 및 그라데이션

ACF:

PHP
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']

Blockstudio:

JSON
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }

color 유형은 WordPress 색상 팔레트와 통합됩니다. gradient 유형은 그라데이션 선택기를 제공합니다.

숫자, 범위, 날짜

ACF:

PHP
['name' => 'count', 'type' => 'number', 'min' => 1, 'max' => 10]
['name' => 'opacity', 'type' => 'range', 'min' => 0, 'max' => 100, 'step' => 5]
['name' => 'eventDate', 'type' => 'date_picker']

Blockstudio:

JSON
{ "id": "count", "type": "number", "label": "Count", "min": 1, "max": 10 }
{ "id": "opacity", "type": "range", "label": "Opacity", "min": 0, "max": 100, "step": 5 }
{ "id": "eventDate", "type": "date", "label": "Event Date" }

반복 필드

ACF의 반복 필드는 Blockstudio의 repeater 유형에 직접 대응합니다. ACF 템플릿에서는 보통 have_rows() / the_row() / get_sub_field()로 반복합니다(반복 필드에서 get_field()도 행 배열을 반환합니다). Blockstudio에는 이미 $a 형식으로 된 일반 PHP 배열만 있습니다.

ACF:

PHP
['name' => 'features', 'type' => 'repeater', 'sub_fields' => [
  ['name' => 'title', 'type' => 'text'],
  ['name' => 'description', 'type' => 'textarea'],
]]

// Template
if (have_rows('features')) :
  while (have_rows('features')) : the_row();
    echo get_sub_field('title');
    echo get_sub_field('description');
  endwhile;
endif;

Blockstudio:

JSON
{
  "id": "features",
  "type": "repeater",
  "label": "Features",
  "min": 1,
  "max": 10,
  "attributes": [
    { "id": "title", "type": "text", "label": "Title" },
    { "id": "description", "type": "textarea", "label": "Description" }
  ]
}
PHP
<?php foreach ($a['features'] as $feature) : ?>
  <h3><?php echo esc_html($feature['title']); ?></h3>
  <p><?php echo esc_html($feature['description']); ?></p>
<?php endforeach; ?>

Blockstudio 반복 필드는 최대 3단계까지 중첩(반복 필드 안에 반복 필드)할 수 있습니다.

그룹

ACF의 그룹 필드는 Blockstudio의 group 유형에 대응합니다. 그룹 안의 필드 ID에는 그룹 ID가 접두사로 붙습니다.

ACF:

PHP
['name' => 'author', 'type' => 'group', 'sub_fields' => [
  ['name' => 'name', 'type' => 'text'],
  ['name' => 'role', 'type' => 'text'],
]]

// Template
$author = get_field('author');
echo $author['name'];
echo $author['role'];

Blockstudio:

JSON
{
  "id": "author",
  "type": "group",
  "title": "Author",
  "attributes": [
    { "id": "name", "type": "text", "label": "Name" },
    { "id": "role", "type": "text", "label": "Role" }
  ]
}
PHP
<?php $author = bs_get_group($a, 'author'); ?>
<p><?php echo esc_html($author['name']); ?></p>
<p><?php echo esc_html($author['role']); ?></p>

bs_get_group() 헬퍼는 필드 ID에서 그룹 접두사를 제거해 간편하게 접근할 수 있게 합니다. 이를 사용하지 않으면 $a['author_name'] 및 $a['author_role']처럼 필드에 접근해야 합니다.

조건부 로직

ACF와 Blockstudio 모두 다른 필드 값에 따라 필드를 표시하거나 숨기는 조건부 로직을 지원합니다.

ACF:

PHP
['name' => 'showSubtitle', 'type' => 'true_false'],
[
  'name' => 'subtitle',
  'type' => 'text',
  'conditional_logic' => [[['field' => 'field_showSubtitle', 'operator' => '==', 'value' => '1']]]
]

Blockstudio:

JSON
{ "id": "showSubtitle", "type": "toggle", "label": "Show Subtitle" },
{
  "id": "subtitle",
  "type": "text",
  "label": "Subtitle",
  "conditions": [[{ "id": "showSubtitle", "operator": "==", "value": true }]]
}

Blockstudio 조건은 필드 키가 아닌 필드 ID를 직접 참조합니다. 사용 가능한 연산자: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.

Blockstudio는 글 유형, 글 ID, 사용자 역할, 사용자 ID를 기준으로 하는 전역 조건도 지원합니다.

JSON
{
  "conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}

InnerBlocks

ACF와 Blockstudio 모두 사용자 지정 블록 안에 다른 블록을 중첩하기 위한 InnerBlocks를 지원합니다. 동일한 <InnerBlocks /> 태그와 allowedBlocks, template, templateLock 속성을 사용하므로 템플릿의 이 부분은 대개 수정 없이 옮길 수 있습니다.

Blockstudio:

PHP
<div useBlockProps class="my-wrapper">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr(wp_json_encode(["core/heading", "core/paragraph", "core/image"])); ?>'
    template='<?php echo esc_attr(wp_json_encode([
      ["core/heading", ["placeholder" => "Section title"]],
      ["core/paragraph", ["placeholder" => "Section content"]]
    ])); ?>'
    templateLock="insert"
  />
</div>

<InnerBlocks /> 태그는 편집기에서 React 컴포넌트로 대체되고, 프런트엔드에서는 렌더링된 블록 콘텐츠로 대체됩니다.

글 메타 저장

기본적으로 ACF Blocks와 Blockstudio 모두 필드 값을 글 메타가 아니라 글 콘텐츠의 블록 속성으로 저장합니다. 따라서 메타 저장을 선택하지 않으면 WP_Query로 필드 값을 쿼리할 수 없습니다.

ACF은 ACF PRO 6.3에서 usePostMeta: true를 통해 블록의 글 메타 저장 기능을 선택적으로 추가했습니다. 페이지마다 최상위 블록 하나에 적용됩니다. Blockstudio은 storage 속성을 사용해 필드별로 저장 방식을 선택할 수 있습니다:

JSON
{
  "id": "featured",
  "type": "toggle",
  "label": "Featured",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "is_featured"
  }
}

메타 키는 show_in_rest에 자동 등록됩니다. get_post_meta($post_id, 'is_featured', true)로 어디서든 접근할 수 있습니다.

ACF 옵션 페이지처럼 사이트 전체에서 사용하는 값에는 옵션 저장을 사용하세요:

JSON
{
  "storage": {
    "type": "option",
    "optionKey": "site_company_name"
  }
}

기존 블록 확장하기

ACF의 블록 위치 규칙은 필드 그룹을 ACF 블록에만 연결하며, 코어 블록이나 타사 블록에 필드를 추가하지 않습니다. Heading, Paragraph, Image, Button 같은 코어 블록을 확장하려면 ACF의 WordPress Block Bindings API를 사용하세요. 이 기능은 기존 블록 속성을 ACF 필드 값과 연결합니다. Blockstudio은 확장 파일을 통해 등록된 모든 블록에 새 필드와 컨트롤을 추가할 수 있습니다.

blockstudio 디렉터리에 확장 파일을 만드세요:

JSON
{
  "name": "core/heading",
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "accentColor",
        "type": "color",
        "label": "Accent Color",
        "set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
      }
    ]
  }
}

set 속성은 필드 값을 블록의 HTML에 자동으로 적용합니다. 와일드카드를 사용하면 여러 블록을 한 번에 확장할 수 있습니다: "name": "core/*".

마이그레이션 체크리스트

  1. theme/blockstudio/{block-name}/에서 block.json과 index.php를 사용해 블록 폴더를 만드세요.
  2. 블록의 필드 그룹(Local JSON, acf_add_local_field_group() 또는 인라인 acf.fields 배열)에 정의된 필드를 block.json의 blockstudio.attributes 배열로 옮기세요. name을 id로 바꾸고, key을 제거한 뒤 필요한 경우 타입 이름을 조정하세요.
  3. 템플릿 접근 방식을 get_field('name')에서 $a['name']로 업데이트하세요. have_rows() 반복문을 foreach ($a['repeater'] as $item)로 바꾸세요.
  4. get_sub_field()을 직접 배열 접근으로 바꾸세요: $item['fieldId'].
  5. 올바른 편집기 통합을 위해 템플릿의 가장 바깥 요소에 useBlockProps을 추가하세요.
  6. 조건부 로직을 ACF의 conditional_logic에서 Blockstudio의 conditions로 옮기고, 필드 키 대신 필드 ID를 참조하세요.
  7. 이전에 get_post_meta()로 쿼리했거나 WP_Query에서 사용한 필드에 저장 방식을 추가하세요.
  8. ACF 등록 코드를 제거하세요. 이전한 블록의 register_block_type() 호출과 acf 키(또는 해당 블록의 acf_register_block_type() 호출), 그리고 필드 그룹을 제거하세요. 필드 그룹은 Local JSON, acf_add_local_field_group(), 인라인 acf.fields 배열 또는 관리자 화면에 있을 수 있습니다.
  9. 편집기에서 필드가 올바르게 표시되는지 확인한 다음 프런트엔드 출력을 확인하세요.