# 파일 3개로 사용자 지정 블록 만들기

JavaScript도, 빌드 단계도, 상용구 코드도 필요 없습니다.

## JSON에서 필드 정의

`blockstudio` 키를 block.json에 추가하세요. `text`, `toggle`, `color` 와 같은 유형으로 속성을 정의하세요. Blockstudio가 편집기 UI를 자동으로 생성하며, 텍스트 입력부터 반복 입력기와 코드 편집기까지 27 필드 유형을 제공하고 직접 등록한 필드 유형도 지원합니다.

전체 JSON 스키마를 지원해 VS Code, PhpStorm 및 호환되는 모든 편집기에서 자동 완성과 유효성 검사를 사용할 수 있습니다.

각 필드에는 새 블록의 `default` 과 필드가 비어 있을 때 템플릿에 전달되는 `fallback` 을(를) 설정할 수 있습니다.

[필드 유형 참고 자료](https://blockstudio.dev/ko/docs/blocks/attributes/field-types/)

block.json

```
{
  "name": "starter/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading" },
      { "id": "showCta", "type": "toggle", "label": "Show CTA" },
      { "id": "background", "type": "color", "label": "Background" }
    ]
  }
}
```

## 3개 파일로 작업

필드용 block.json, 마크업용 템플릿, 선택 사항인 스타일시트를 사용하세요.

## PHP의 React

RichText, InnerBlocks, useBlockProps는 PHP, Twig 또는 Blade에서 바로 사용할 수 있습니다.

## SCSS 및 Tailwind

CSS, SCSS 또는 Tailwind를 사용하세요. SCSS은 가져오기 경로와 공유 전처리 구문을 지원하며, 중첩된 부분 템플릿을 편집하면 이를 가져오는 모든 파일이 다시 컴파일됩니다.

## 27개 필드 유형

텍스트, 색상, 이미지, 반복 필드, 선택 필드, 코드 편집기 등을 JSON에서 구성하세요.

## JSON Schema

VS Code, PhpStorm 및 호환되는 편집기에서 자동 완성과 유효성 검사를 사용할 수 있습니다.

## 세 가지 템플릿 언어

PHP, Twig, Blade는 같은 변수와 구성 요소를 공유합니다.

## npm 가져오기

script.js에서 패키지를 가져오세요. 프로덕션에서는 로컬 패키지를 사용하고 편집기에서는 CDN을 기반으로 사용합니다.

## Interactivity API

플래그 하나로 WordPress Interactivity API을 활성화하세요.

## PHP 템플릿의 React 구성 요소

하나의 템플릿에서 인라인 편집 및 정적 프런트엔드 HTML에는 `<RichText />` 를, 하위 블록에는 `<InnerBlocks />` 를, 래퍼에는 `useBlockProps` 를 사용하세요.

편집기에서는 실제 React 구성 요소로 표시됩니다. 프런트엔드에서는 서버 측 HTML로 렌더링되므로 방문자에게 JavaScript가 전송되지 않습니다.

[컴포넌트 살펴보기](https://blockstudio.dev/ko/docs/blocks/react-components/)

index.php

```
<div useBlockProps class="container">
  <RichText
    class="text-xl font-semibold"
    tag="h1"
    attribute="headline"
    placeholder="Enter headline"
  />

  <?php if ($a['showCta']): ?>
    <a href="<?= esc_url($a['ctaUrl']) ?>">
      <?= esc_html($a['ctaLabel']) ?>
    </a>
  <?php endif; ?>

  <InnerBlocks class="mt-4 p-4 border" />
</div>
```

## PHP, Twig 또는 Blade로 작성

익숙한 템플릿 언어를 사용하세요. PHP은(는) 기본 제공되고, Timber을(를) 설치하면 Twig이(가) 실행되며, `Blockstudio\Blade_Renderer` 을(를) 통해 `illuminate/view` 8~12에서 Blade이(가) 실행됩니다. 변수, 컴포넌트, 동작은 동일하게 유지됩니다.

`$a` (속성), `$b` (블록), `$c` (컨텍스트), `$innerBlocks` 를 모든 언어에서 사용할 수 있습니다.

Twig 템플릿도 전체 Timber 컨텍스트를 받습니다. Blade는 페이지, 패턴, Site Editor 템플릿도 렌더링합니다. 이전 `jenssegers/blade` 래퍼는 `illuminate/view` 10 이상에서 작동하지 않으므로 대신 `Blade_Renderer` 를 사용하세요.

[템플릿 언어](https://blockstudio.dev/ko/docs/blocks/templating/blade/)

index.twig

```
<div useBlockProps class="card">
  <RichText tag="h2" attribute="title" placeholder="Card title" />
  {% if a.image %}
    <img src="{{ a.image.url|esc_url }}"
      alt="{{ a.image.alt|esc_attr }}" />
  {% endif %}
  <div class="card__body">{{ a.description|esc_html }}</div>
  <InnerBlocks allowedBlocks='["core/button"]' />
</div>
```

## 조건부 로직 및 동적 옵션

`==`, `!=`, `includes`, `empty` 같은 연산자와 비교 조건을 사용해 필드를 표시하거나 숨기세요. OR 로직으로 조건을 결합할 수 있습니다.

옵션은 다른 필드에 종속될 수 있습니다. populate 인수에 `{attributes.post_type.value}` 를 넣으면 해당 필드가 변경될 때 목록이 다시 로드됩니다. 편집자가 입력하는 동안 게시물을 검색하려면 `fetch: true` 을 추가하세요.

`type: custom` 와 `blockstudio/blocks/attributes/populate` 필터를 사용하면 여러 블록에서 하나의 옵션 목록을 공유할 수 있으며, 구매 확인 같은 자체 전역 조건은 `blockstudio/blocks/conditions` 를 통해 등록할 수 있습니다.

[조건부 로직](https://blockstudio.dev/ko/docs/blocks/attributes/conditional-logic/)

block.json

```
{
  "name": "starter/posts",
  "title": "Posts",
  "blockstudio": {
    "attributes": [
      {
        "id": "post_type",
        "type": "select",
        "label": "Post type",
        "options": [
          { "value": "page", "label": "Pages" },
          { "value": "post", "label": "Posts" }
        ]
      },
      {
        "id": "selected_post",
        "type": "select",
        "label": "Post",
        "populate": {
          "type": "query",
          "query": "posts",
          "arguments": { "post_type": "{attributes.post_type.value}" }
        }
      },
      {
        "id": "style",
        "type": "select",
        "label": "Style",
        "populate": { "type": "custom", "custom": "cardStyles" },
        "conditions": [[
          { "type": "purchasedProduct", "operator": "==", "value": "yes" }
        ]]
      }
    ]
  }
}
```

## 관리하기 쉬운 리피터

`min` 와 `max` 을 설정하고, `default` 개 행으로 새 블록을 시작하며, `minimized` 으로 기존 행을 접으세요. `textMinimized` 는 이름과 같은 해당 행의 필드 하나를 사용해 접힌 행에 라벨을 표시합니다.

행에는 탭을 제외한 모든 필드 유형을 사용할 수 있으며, 중첩 리피터도 포함됩니다. 행 안의 조건은 `"context": "main"` 을 사용해 행 외부의 필드를 확인하고, `<RichText />` 과 `<MediaPlaceholder />` 는 `attribute` 이 `repeaterId[index].fieldId` 를 가리킬 때 단일 행을 편집합니다.

[리피터 패턴](https://blockstudio.dev/ko/guides/field-patterns/#repeater-patterns)

block.json

```
{
  "name": "starter/team",
  "title": "Team",
  "blockstudio": {
    "attributes": [
      {
        "id": "members",
        "type": "repeater",
        "label": "Team members",
        "min": 1,
        "max": 12,
        "minimized": true,
        "textMinimized": { "id": "name", "fallback": "Team member" },
        "attributes": [
          { "id": "name", "type": "text", "label": "Name" },
          { "id": "bio", "type": "richtext", "label": "Bio" }
        ]
      }
    ]
  }
}
```

## 재사용 가능한 필드 모음

`field.json` 에서 필드 그룹을 한 번 정의하고 `"type": "custom/cta"` 로 모든 블록에서 참조하세요. 필드가 인라인으로 삽입되므로 템플릿에서 다른 속성과 동일한 방식으로 읽을 수 있습니다.

`hero_{id}` 같은 `idStructure` 을 사용해 같은 필드 모음을 두 번 재사용하고, `overrides` 로 블록마다 라벨, 기본값 또는 조건을 변경하세요. `block` 필드 유형은 블록 전체에도 같은 방식으로 작동합니다. 해당 블록의 필드를 인라인으로 확장하고 렌더링된 HTML를 반환합니다.

[사용자 정의 필드](https://blockstudio.dev/ko/docs/blocks/attributes/custom-fields/)

fields/cta/field.json

```
{
  "name": "cta",
  "title": "Call to action",
  "attributes": [
    { "id": "label", "type": "text", "label": "Button label", "default": "Learn more" },
    { "id": "url", "type": "link", "label": "Button URL" }
  ]
}
```

## 빌드 단계 없는 ES 모듈

`script.js` 를 추가하면 ES 모듈로 로드됩니다. `npm:` 접두사를 사용해 npm 패키지를 가져오면 Blockstudio가 프로덕션용 파일을 로컬에 다운로드합니다.

편집기에서는 즉시 미리 볼 수 있고, 프런트엔드는 외부 의존성 없이 로컬 모듈을 사용하며 한 번만 대기열에 추가됩니다.

스타일시트도 같은 방식으로 가져옵니다. `import "npm:swiper@11.0.0/swiper.min.css"` 는 파일을 다운로드하고 버전별로 한 번만 enqueue하므로 여러 블록에서 사용해도 중복되지 않습니다.

[에셋 처리](https://blockstudio.dev/ko/docs/blocks/assets/)

script.js

```
import Swiper from "npm:swiper@11.0.0";
import "npm:swiper@11.0.0/swiper.min.css";

for (const el of document.querySelectorAll(".swiper")) {
  new Swiper(el, {
    slidesPerView: 3,
    spaceBetween: 20,
    loop: true,
  });
}
```

## 템플릿을 넘어서는 블록 태그

`blockstudio.json` 에서 짧은 접두사를 네임스페이스에 매핑하거나, 별칭 필터로 태그 하나를 블록 하나에 연결하면 `<acme-card>` 가 `acme/card` 를 렌더링합니다. `blockTags.enabled` 을 켜면 게시물 콘텐츠와 위젯의 태그도 렌더링하며, `allow` 및 `deny` 패턴으로 제한됩니다.

`data-*` 속성은 블록의 루트 요소에 전달되고, `html-*` 속성은 접두사 없이 전달됩니다. `blockstudio/block_tags/builders` 로 자체 태그 빌더를 추가하고, `migrate-block-tags` 명령으로 축약 표기를 이식 가능한 `<bs:acme-card>` 표기로 변환하세요.

[가이드 읽기](https://blockstudio.dev/ko/guides/block-tags/)

blockstudio.json

```
{
  "blockTags": {
    "enabled": true,
    "prefixes": {
      "acme": ["acme"],
      "ui": ["acme-ui"]
    },
    "deny": ["acme-ui/admin-*"]
  }
}
```

## 사용자 지정 필드 유형

직접 필드 컨트롤을 등록해 기본 제공 필드처럼 사용하세요.

## 블록 아일랜드

페이지 전체를 캐시하고 방문자 요청에서 블록 하나를 렌더링하세요.

## 조건부 등록

게시물 유형, 사용자 역할 또는 다른 전역 조건에 따라 블록을 등록하거나, 필요한 플러그인 또는 플러그인 버전이 없을 때 등록을 건너뛰세요.

## 게시물 메타 및 옵션

블록 속성과 함께 게시물 메타 또는 옵션에 값을 저장하세요.

## 조건부 로직

값의 일치, 포함 여부, 비어 있는지, 비교 조건에 따라 필드를 표시하세요.

## 동적 값 채우기

게시물, 사용자, 용어, 함수 또는 API에서 선택 항목을 가져오세요.

## 재정의

공유 블록의 이름과 함께 override: true를 설정하면 id별로 속성을 병합하고, 이름이 같은 파일의 에셋을 교체하며, 템플릿을 바꿉니다. Twig 템플릿은 extends를 사용해 개별 블록을 재정의할 수 있습니다.

## 변형

block.json에서 필드 값을 미리 설정하는 변형을 선언하고, 이를 제어하는 필드는 hidden으로 숨기세요.

## 구성 요소

PHP 또는 블록 태그에서만 렌더링되는 블록에 component: true를 설정하세요. 필드, 템플릿, 에셋 및 Tailwind은 유지되지만 삽입기에는 표시되지 않습니다.

## InnerBlocks 규칙

namespace/*, category: 및 @theme 토큰이 있는 블록을 허용하고, select 옵션으로 내부 템플릿을 전환하며, 필터를 사용해 프런트엔드에서 래퍼를 제거하세요.

## 코드 필드 에셋

asset: true인 코드 필드는 편집기의 입력을 해당 블록 전용 CSS, SCSS 또는 JavaScript로 변환하며, %selector%를 통해 인스턴스 범위로 한정합니다.

## 파일 이름으로 에셋 지정

*.view.js는 프런트엔드에서만 로드됩니다. global-, admin-, block-editor- 접두사를 사용하면 파일이 모든 페이지, wp-admin 또는 블록 편집기에서 로드됩니다.

## 아이콘 및 블록 폴더

블록에 사용자 정의 SVG 또는 HTML 아이콘을 지정하고, blockstudio/path 필터로 검색 위치를 옮기며, Blockstudio\Build::init()로 폴더를 추가하세요.

## ACF 및 Meta Box 값

템플릿은 $post_id을 받으므로 get_field() 및 rwmb_get_value()가 편집된 게시물을 읽으며, 저장 후 refreshOn이 미리보기를 새로 고칩니다.

## Query Loop 컨텍스트

Query Loop 안에서는 $block[‘context’][‘postId’]가 현재 항목을 따르고, $block[‘postId’]는 계속 조회 중인 게시물을 가리킵니다.

## WPML

wp bs wpml config는 텍스트 필드를 번역 가능하게 표시하는 wpml-config.xml를 작성하며, 필드에 저장된 이미지도 대체 텍스트와 캡션을 포함해 WPML 번역 작업에 포함됩니다.

Plus

## 공식 확장 키트

프리미엄 사이트 템플릿, AI 시스템 지침, 비공개 Discord 커뮤니티를 제공합니다. 한 번 구매하면 업데이트를 평생 받을 수 있습니다.

- 500개 이상의 사이트 템플릿
- AI 시스템 지침
- 평생 업데이트
- 비공개 Discord 커뮤니티

[Plus 이용하기](https://blockstudio.dev/ko/plus/)
