본문으로 건너뛰기

확장 기능

확장 기능을 사용하면 간단한 .json 기반 API으로 Blockstudio로 만든 블록을 비롯해 WordPress 설치에 등록된 코어, 타사 블록 등 모든 블록을 확장할 수 있습니다. 이 구성은 block.json 구성과 유사합니다.

모든 필드 유형을 블록에 추가할 수 있으며 데이터는 블록 속성에 저장됩니다. 확장 기능에서도 필터링, 비활성화, 조건부 로직, 옵션 채우기 등 속성의 전체 기능을 사용할 수 있습니다.

확장 유형

확장된 값은 다양한 방식으로 활용할 수 있습니다:

  • class: 속성 값을 사용해 블록에 클래스를 추가합니다.
  • style: 속성 값을 사용해 블록에 인라인 스타일을 추가합니다.
  • attributes: 블록에 속성 값을 직접 설정합니다.
  • data attributes: 확장 값을 사용해 특정 데이터 속성을 설정합니다.

설정

다음 상황을 생각해 보세요. 모든 코어 블록에 사용자 지정 클래스 select 필드를 추가하려고 합니다. 블록 폴더 어디에든 이 .json 파일을 추가하기만 하면 확장으로 자동 등록됩니다.

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "priority": 10,
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "customColor",
        "type": "select",
        "label": "Custom color",
        "options": [
          {
            "value": "#f00",
            "label": "Red"
          },
          {
            "value": "#00f",
            "label": "Blue"
          }
        ],
        "set": [
          {
            "attribute": "style",
            "value": "color: {attributes.customColor}"
          }
        ]
      }
    ]
  }
}

모든 코어 블록에 customColor 필드가 추가되어 블록 텍스트의 색상을 설정할 수 있습니다.

파일 이름

렌더링 템플릿이 없으므로 확장에는 이에 대응하는 index 파일이 필요하지 않으며, 따라서 block.json이라는 이름을 붙일 필요도 없습니다. 덕분에 모든 확장을 한 폴더에 편리하게 저장할 수 있습니다. 여러 파일이 같은 블록을 확장할 수도 있습니다. 예를 들어 "name": "core/*"가 있는 파일 두 개는 각각 자체 필드를 등록합니다.

스키마

Blockstudio은 확장 설정을 위한 사용자 지정 JSON 스키마를 제공합니다.

확장 스키마 보기

이름

설정 객체의 name 속성은 확장할 블록을 지정합니다. 필요에 따라 다음 세 가지 옵션 중 하나를 선택할 수 있습니다.

  • blockName: 단일 블록 이름, e.g. core/paragraph
  • [blockNameA, blockNameB]: 블록 이름 배열, e.g. ["core/paragraph", "core/heading"]
  • core/*: 특정 유형의 모든 블록을 확장하는 와일드카드

별표로 끝나는 이름은 core/*뿐 아니라 모두 접두사 와일드카드입니다. 다음 확장 기능은 이름이 my-plugin/로 시작하는 모든 블록에 적용됩니다. Blockstudio로 만든 블록도 포함됩니다:

JSON
{
  "name": "my-plugin/*",
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

블록 제외하기

최상위 exclude 배열을 사용해 name와 일치했을 블록을 건너뛰세요:

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "exclude": ["core/button", "core/image"],
  "blockstudio": {
    "extend": true,
    "attributes": []
  }
}

제외 항목은 name와 마찬가지로 정확한 이름 및 끝에 *가 붙는 접두사 일치를 사용합니다. 제외 항목은 단일 이름, 이름 목록, 와일드카드보다 우선합니다. 제외된 블록에는 확장 기능의 편집기 필드나 프런트엔드 속성 및 에셋이 적용되지 않습니다. 일치하는 다른 확장 기능에는 영향을 주지 않습니다. 기존 동작을 유지하려면 exclude를 생략하거나 빈 배열을 사용하세요.

Blockstudio 키

사용자 지정 블록에 block.json을 사용할 때와 마찬가지로, 설정 객체에는 extend가 true으로 설정된 blockstudio 속성이 있어야 합니다.

위치

기본적으로 확장은 블록 검사기의 별도 탭에 표시됩니다. 확장의 위치를 변경하려면 group 속성을 사용할 수 있습니다.

  • settings: 기본 위치
  • styles: 스타일 탭
  • advanced: 고급 탭
JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "group": "styles",
    "attributes": []
  }
}

우선순위

priority 속성으로 확장이 표시되는 순서를 지정할 수 있습니다. 우선순위가 높을수록 나중에 표시됩니다. 설정 예시처럼 파일의 최상위 수준이나 extend 내부에 설정하세요.

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": { "priority": 10 },
    "attributes": []
  }
}

둘 다 설정된 경우 blockstudio.extend.priority이 우선합니다.

속성

속성의 작동 방식에 대한 자세한 내용은 속성 섹션을 참조하세요.

확장 내 속성에서 알아둘 점은 set 속성뿐입니다. 이 속성은 속성 값을 확장 유형 중 하나에 적용하는 데 사용됩니다.

JSON
{
  "$schema": "https://blockstudio.dev/schema/extend",
  "name": "core/*",
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "customColor",
        "type": "select",
        "label": "Heading color",
        "options": [
          {
            "value": "#f00",
            "label": "Red"
          },
          {
            "value": "#00f",
            "label": "Blue"
          }
        ],
        "set": [
          {
            "attribute": "style",
            "value": "color: {attributes.customColor}"
          }
        ]
      }
    ]
  }
}

값 가져오기

중괄호 안에서 점 표기법을 사용해 속성 값을 가져옵니다.

속성에서 단일 값이 반환되지 않는 경우에도 중첩된 값을 가져올 수 있습니다. 예를 들어 옵션이 있는 필드 유형에서 반환 형식을 both으로 설정할 때 사용할 수 있습니다.

JSON
{
  "attributes": [
    {
      "id": "customColor",
      "type": "select",
      "label": "Heading color",
      "options": [
        {
          "value": "#f00",
          "label": "Red"
        },
        {
          "value": "#00f",
          "label": "Blue"
        }
      ],
      "returnFormat": "both",
      "set": [
        {
          "attribute": "style",
          "value": "color: {attributes.customColor.value}"
        },
        {
          "attribute": "data-color",
          "value": "{attributes.customColor.label}"
        }
      ]
    }
  ]
}

위 예시에서는 값에 따라 style 속성을 color: #f00 또는 color: #00f로, data-color 속성을 Red 또는 Blue로 설정합니다.

현재는 set 정의에서 현재 속성의 값만 사용할 수 있습니다. 향후 다른 속성의 값을 사용하는 기능이 추가될 수 있습니다.

배열

배열을 사용하면 set 속성이 배열의 모든 항목에 적용됩니다.

각 항목은 자체 클래스 또는 스타일 선언을 추가합니다. 다른 속성은 단일 값만 가지므로 각 항목이 이전 값을 덮어쓰며 마지막 항목이 적용됩니다. 대신 모든 항목의 결과를 공백으로 구분해 기록하고 빈 값이나 중복 값을 제외하려면 join를 true로 설정하세요. 그러면 [data-langs~="en"]와 같은 선택자가 선택된 모든 항목과 일치합니다. join은 class 및 style에는 영향을 주지 않으며, 단일 값을 반환하는 필드에도 영향을 주지 않습니다.

JSON
{
  "id": "langs",
  "type": "checkbox",
  "label": "Languages",
  "options": [
    {
      "value": "en",
      "label": "English"
    },
    {
      "value": "de",
      "label": "German"
    }
  ],
  "set": [
    {
      "attribute": "data-langs",
      "value": "{attributes.langs}",
      "join": true
    }
  ]
}

두 옵션을 모두 선택하면 data-langs="en de"가 렌더링됩니다. join가 없으면 data-langs="de"가 렌더링됩니다.

속성 필드

attributes 필드를 사용할 때는 set 속성이 필요하지 않습니다. 필드가 값을 속성 이름과 값에 자동으로 매핑하기 때문입니다.

확장 필드 검사하기

bs_block_extension_fields('core/paragraph')는 블록과 일치하는 모든 확장 기능의 필드 정의를 반환합니다. 반환값과 bs_block_fields()와의 관계는 블록 검사를 참조하세요.