본문으로 건너뛰기

사용자 지정 필드

사용자 지정 필드를 사용하면 여러 블록에서 참조할 수 있는 재사용 가능한 필드 그룹을 정의할 수 있습니다. 필드 템플릿처럼 한 번 정의해 어디서나 사용하세요.

사용자 지정 필드는 사용자 지정 필드 유형과 다릅니다. 기존 필드를 재사용 가능한 그룹으로 묶으려면 custom/{name}를 사용하세요. 테마나 플러그인에서 새 편집기 컨트롤과 값 구조를 등록하는 경우 acme/dimensions 같은 네임스페이스가 지정된 사용자 지정 필드 유형을 사용하세요.

파일 시스템 등록

blockstudio 디렉터리 안의 fields/ 디렉터리에 field.json 파일을 만드세요.

코드
theme/
└── blockstudio/
    └── fields/
        └── hero/
            └── field.json
JSON
{
  "$schema": "https://blockstudio.dev/schema/field",
  "name": "hero",
  "title": "Hero Section",
  "attributes": [
    {
      "id": "heading",
      "type": "text",
      "label": "Heading",
      "default": "Hello World"
    },
    { "id": "description", "type": "textarea", "label": "Description" },
    { "id": "enabled", "type": "toggle", "label": "Enabled" }
  ]
}

PHP 필터 등록

blockstudio/fields 필터를 사용해 사용자 지정 필드를 프로그래밍 방식으로 등록하세요.

PHP
add_filter('blockstudio/fields', function ($fields) {
    $fields['cta'] = [
        'title'      => 'Call to Action',
        'attributes' => [
            ['id' => 'text', 'type' => 'text', 'label' => 'Button Text'],
            ['id' => 'url', 'type' => 'text', 'label' => 'URL'],
        ],
    ];
    return $fields;
});

block.json에서 사용

custom/{name} 유형을 사용해 사용자 지정 필드를 참조하세요.

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero" }]
  }
}

이렇게 하면 사용자 지정 필드 정의에 지정된 필드가 인라인으로 확장됩니다. 확장된 필드는 원래 ID(heading, description, enabled)를 사용합니다.

사용자 지정 필드는 완전한 그룹 정의도 재사용할 수 있습니다.

JSON
{
  "name": "section-header",
  "attributes": [
    {
      "id": "section-header",
      "type": "group",
      "title": "Header",
      "attributes": [
        { "id": "kicker", "type": "text", "label": "Kicker" },
        { "id": "title", "type": "text", "label": "Title" }
      ]
    }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/section-header" }]
  }
}

그룹의 하위 항목은 section-header_kicker, section-header_title 등으로 저장됩니다. 템플릿에서는 bs_get_group()를 사용해 이를 깔끔한 그룹 객체로 추출하세요.

ID 구조

idStructure를 사용해 필드 ID에 접두사를 붙이거나 변환하세요. {id} 자리표시자는 원래 필드 ID로 대체됩니다.

JSON
{
  "blockstudio": {
    "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
  }
}

이렇게 하면 hero_heading, hero_description, hero_enabled ID를 가진 필드가 생성됩니다.

재정의

overrides를 사용해 인스턴스별 개별 필드를 사용자 지정하세요. 키는 정의에 지정된 원래 필드 ID입니다.

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "default": "Welcome", "label": "Title" },
          "enabled": { "id": "active" }
        }
      }
    ]
  }
}

재정의 속성은 원래 필드 정의에 병합됩니다. id 재정의는 idStructure 패턴을 우회합니다. 위 예시에서는 enabled가 hero_enabled 대신 active이 됩니다.

병합은 한 단계 깊이로 적용됩니다. 재정의한 속성은 원래 속성 전체를 대체합니다. options 재정의는 옵션을 추가하는 것이 아니라 전체 옵션 목록이며, conditions과 그룹의 attributes에도 동일하게 적용됩니다. 참조의 조건은 그 후에도 추가됩니다.

JSON
{
  "type": "custom/background",
  "overrides": {
    "background": {
      "options": [
        { "value": "white", "label": "White" },
        { "value": "grey", "label": "Grey" }
      ]
    }
  }
}

이 블록은 정의에 옵션이 몇 개 나열되어 있든 흰색과 회색만 제공합니다.

조건

사용자 지정 필드 정의 내의 조건은 idStructure가 적용될 때 자동으로 다시 작성됩니다. 형제 필드에 조건부로 종속된 필드는 확장 후에도 계속 작동합니다.

JSON
{
  "name": "font-size",
  "attributes": [
    { "id": "enable", "type": "toggle", "label": "Modify font size" },
    {
      "id": "min",
      "type": "number",
      "label": "Min Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    },
    {
      "id": "max",
      "type": "number",
      "label": "Max Size",
      "conditions": [[{ "id": "enable", "operator": "==", "value": true }]]
    }
  ]
}
JSON
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }

Blockstudio는 이를 title_font_enable, title_font_min, title_font_max으로 확장하고, enable 대신 title_font_enable를 참조하도록 조건을 다시 작성합니다. 토글 컨트롤은 필드가 인라인으로 정의된 경우와 똑같이 작동합니다.

참조 수준 조건

참조에 conditions를 추가하면 확장된 모든 필드에 조건을 적용할 수 있습니다. 외부 토글로 그룹 전체를 숨길 때 유용합니다.

JSON
{
  "type": "custom/font-size",
  "idStructure": "subtitle_font_{id}",
  "conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}

이러한 조건은 필드 정의 내부에 이미 정의된 조건과 병합됩니다. 조건 ID도 idStructure를 통해 다시 작성됩니다.

여러 사용자 지정 필드

일반 필드와 함께 하나의 블록에서 여러 사용자 지정 필드를 사용할 수 있습니다.

JSON
{
  "blockstudio": {
    "attributes": [
      { "id": "intro", "type": "text", "label": "Intro" },
      { "type": "custom/hero", "idStructure": "hero_{id}" },
      { "type": "custom/cta", "idStructure": "cta_{id}" }
    ]
  }
}

중첩

사용자 지정 필드는 그룹, 탭, 반복기 안에서도 작동합니다.

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "group",
        "id": "content",
        "title": "Content",
        "attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
      }
    ]
  }
}

추가 검색 경로

blockstudio/fields/paths 필터를 사용해 필드 검색을 위한 추가 디렉터리를 지정하세요.

PHP
add_filter('blockstudio/fields/paths', function ($paths) {
    $paths[] = get_stylesheet_directory() . '/blockstudio/fields';
    return $paths;
});

정적 분석

blockstudio/phpstan 패키지는 파일에 정의된 custom/* 참조를 확장해 PHP, Twig, Blade, 블록 태그 및 추론된 속성 구조를 검증합니다. 이 확장은 위에서 설명한 중첩, idStructure 및 overrides 규칙을 따릅니다.

분석 대상 프로젝트 외부의 정의를 사용하려면 phpstan.neon의 blockstudioScanRoots에 라이브러리 디렉터리를 추가하세요. blockstudio/fields PHP 필터를 통해서만 등록된 필드는 런타임에 존재하며 정적으로 추론할 수 없습니다.