본문으로 건너뛰기

사용자 정의 필드 유형 만들기

일부 값은 단일 원시 값이 아닙니다. 가격은 금액과 통화로 구성됩니다. 기본 제공 필드로는 숫자 필드와 선택 필드를 나란히 사용해야 하고, 가격을 표시하는 모든 블록에서 필드 쌍과 라벨, 두 값을 함께 유지하는 로직을 반복해야 합니다. 게시물 메타에서는 키 두 개가 되고, 반복 필드 안에서는 서로 나란한 목록 두 개가 됩니다.

사용자 정의 필드 유형을 사용하면 이 쌍을 하나의 필드로 만들 수 있습니다. acme/price 같은 유형을 PHP과 JavaScript에 한 번 등록하면, 모든 block.json에서 기본 필드처럼 사용할 수 있습니다. 최상위 수준, 그룹과 반복 필드 내부, 게시물 메타 또는 옵션 저장소, 그리고 PHP, Twig, Blade 템플릿에서 사용할 수 있습니다. Blockstudio은 등록 정보를 바탕으로 WordPress 속성과 저장소 REST 스키마를 생성합니다.

사용자 정의 필드와는 다릅니다. custom/{name} 참조는 기존 필드 그룹을 재사용합니다. 사용자 정의 필드 유형은 자체 값 구조를 가진 새 컨트롤을 추가합니다.

이 가이드에서는 acme/price을 처음부터 끝까지 만듭니다. PHP 등록, 편집기 컨트롤, 최상위 수준과 반복 필드 내부에서 사용하는 가격 블록, 엄격한 REST 스키마를 이용한 게시물 메타 저장, 렌더링된 결과를 다룹니다.

PHP에서 유형 등록

PHP 측에서는 속성 유형, 기본값, 컨트롤을 제공하는 편집기 스크립트, 블록 외부에서 값을 저장하는 방식을 선언합니다.

PHP
add_action( 'init', function () {
	wp_register_script(
		'acme-field-price',
		get_stylesheet_directory_uri() . '/fields/price.js',
		array( 'blockstudio-blocks', 'wp-components', 'wp-element' ),
		'1.0.0',
		true
	);

	bs_register_field_type( 'acme/price', array(
		'attribute'     => 'object',
		'default'       => array(),
		'editor_script' => 'acme-field-price',
		'storage'       => array(
			'type'        => 'object',
			'rest_schema' => array(
				'type'                 => 'object',
				'properties'           => array(
					'amount'   => array( 'type' => 'number', 'minimum' => 0 ),
					'currency' => array( 'type' => 'string', 'pattern' => '^[A-Z]{3}$' ),
				),
				'additionalProperties' => false,
			),
		),
	) );
} );

attribute은 WordPress 속성 유형이며, 여기서는 object입니다. storage.type은 필드를 게시물 메타나 옵션에 저장할 때 사용하는 값 유형이며, storage.rest_schema는 WordPress가 REST 쓰기를 검증하는 데 사용하는 스키마입니다. rest_schema가 없으면 객체 값에 허용적인 스키마가 적용되어 모든 속성이 허용됩니다.

기본 우선순위로 init에 등록하세요. Blockstudio은 init에서 블록을 늦게 검색하므로, 그때까지 등록되지 않은 유형은 생성된 블록 속성에서 제외됩니다.

bs_register_field_type()은 성공하면 true을, 이름이나 정의가 잘못되면 false를 반환합니다. 이름은 소문자여야 하고 네임스페이스가 있어야 하며 대시 표기법을 사용해야 합니다. 다음 두 네임스페이스는 예약되어 있습니다.

이름 결과
acme/price true
Acme/Price false, 소문자가 아님
custom/price false, 재사용 가능한 필드 그룹용으로 예약됨
blockstudio/price false, Blockstudio 핵심 기능용으로 예약됨

bs_unregister_field_type()은 등록을 취소하며, blockstudio/field_types 필터는 이름을 키로 사용한 배열 형태로 동일한 정의를 받습니다.

편집기 컨트롤 만들기

위에서 등록한 스크립트는 React 컴포넌트를 제공합니다. 편집기에 이미 로드된 WordPress 컴포넌트를 사용하므로 빌드 단계가 필요하지 않습니다.

JavaScript
const { createElement: el } = wp.element;
const { Flex, FlexBlock, FlexItem, SelectControl, TextControl } = wp.components;

window.blockstudio.registerFieldType('acme/price', {
  component(props) {
    const value =
      props.value && typeof props.value === 'object' && !Array.isArray(props.value)
        ? props.value
        : {};
    const currencies = props.currencies || ['EUR'];

    return el(
      Flex,
      { align: 'flex-end' },
      el(
        FlexBlock,
        {},
        el(TextControl, {
          label: props.label,
          type: 'number',
          min: 0,
          step: 0.01,
          disabled: props.disabled,
          value: value.amount ?? '',
          onChange(next) {
            props.onChange({ ...value, amount: next === '' ? 0 : Number(next) });
          },
        }),
      ),
      el(
        FlexItem,
        {},
        el(SelectControl, {
          label: 'Currency',
          hideLabelFromVision: true,
          disabled: props.disabled,
          value: value.currency || currencies[0],
          options: currencies.map((code) => ({ label: code, value: code })),
          onChange(next) {
            props.onChange({ ...value, currency: next });
          },
        }),
      ),
    );
  },
});

컴포넌트는 필드 정의의 모든 속성을 받으므로 block.json에 넣은 currencies 키는 props.currencies로 전달됩니다. 또한 다음과 같은 안정적인 props를 받습니다. value, onChange, field, defaultValue, attributes, block, clientId, disabled, inRepeater. 반복 필드 행 안에서 렌더링될 때는 repeaterId도 전달됩니다. onChange은 지정한 값을 그대로 저장합니다. 사용자 정의 값에는 기본 select, radio, color, gradient 필드가 적용하는 옵션 정규화가 적용되지 않습니다.

첫 몇 줄처럼 객체가 아닌 값을 방어하세요. 필드가 생기기 전에 저장되었거나 다른 구조로 저장된 블록도 편집기에서 계속 열려야 합니다.

Blockstudio은 acme/price를 사용하는 블록이 등록된 경우에만 블록 편집기에 acme-field-price을 로드합니다. 컨트롤 등록 스크립트가 실패하면 편집기는 저장된 값을 유지하고 필드 대신 편집할 수 없는 알림을 표시합니다. 프런트엔드에서는 계속 값이 렌더링됩니다.

블록에서 사용하기

가격 블록은 이 유형을 두 번 사용합니다. 블록 밖에서도 검색할 수 있어야 하는 시작 가격에 한 번, 등급 반복 필드의 각 행에 한 번 사용합니다.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/pricing",
  "title": "Pricing",
  "blockstudio": {
    "attributes": [
      {
        "id": "price",
        "type": "acme/price",
        "label": "Starting price",
        "currencies": ["EUR", "USD"],
        "default": { "amount": 19, "currency": "EUR" },
        "storage": {
          "type": "postMeta",
          "postMetaKey": "acme_price"
        }
      },
      {
        "id": "tiers",
        "type": "repeater",
        "label": "Tiers",
        "min": 0,
        "max": 4,
        "attributes": [
          { "id": "name", "type": "text", "label": "Name", "default": "" },
          {
            "id": "price",
            "type": "acme/price",
            "label": "Price",
            "currencies": ["EUR", "USD"],
            "default": { "amount": 0, "currency": "EUR" },
            "storage": {
              "type": "postMeta",
              "postMetaKey": "acme_tier_prices"
            }
          }
        ]
      }
    ]
  }
}

필드 수준의 default은 레지스트리 기본값보다 우선합니다. Blockstudio은 두 필드를 등록 정보에 지정된 WordPress 속성으로 변환합니다. 등록된 블록 유형에는 다음이 포함됩니다.

JSON
{
  "price": {
    "blockstudio": true,
    "type": "object",
    "field": "acme/price",
    "id": "price",
    "default": { "amount": 19, "currency": "EUR" },
    "storage": { "type": "postMeta", "postMetaKey": "acme_price" }
  },
  "tiers": {
    "blockstudio": true,
    "type": "array",
    "field": "repeater",
    "id": "tiers",
    "attributes": [
      { "blockstudio": true, "type": "string", "field": "text", "default": "", "id": "name" },
      {
        "blockstudio": true,
        "type": "object",
        "field": "acme/price",
        "id": "price",
        "default": { "amount": 0, "currency": "EUR" },
        "storage": { "type": "postMeta", "postMetaKey": "acme_tier_prices" }
      }
    ]
  }
}

값 렌더링

템플릿에서 값은 일반 배열입니다. 저장된 값은 마지막으로 기록한 항목만큼만 신뢰할 수 있으므로 사용 전에 유형을 좁히세요.

PHP
<?php
/** @var array{price: mixed, tiers: array<int, array{name: string, price: mixed}>} $a */
$format = static function ( mixed $price ): string {
	if ( ! is_array( $price ) ) {
		return '';
	}
	$amount   = is_numeric( $price['amount'] ?? null ) ? (float) $price['amount'] : 0.0;
	$currency = is_string( $price['currency'] ?? null ) ? $price['currency'] : '';

	return number_format_i18n( $amount, 2 ) . ' ' . $currency;
};
?>
<section useBlockProps class="acme-pricing">
  <p>From <?php echo esc_html( $format( $a['price'] ) ); ?></p>
  <?php foreach ( $a['tiers'] ?: array() as $tier ) : ?>
    <div class="acme-tier">
      <h3><?php echo esc_html( $tier['name'] ); ?></h3>
      <p><?php echo esc_html( $format( $tier['price'] ?? null ) ); ?></p>
    </div>
  <?php endforeach; ?>
</section>

?: array()이 중요합니다. 행이 없는 반복 필드는 빈 배열이 아닌 false로 템플릿에 전달됩니다. 여기에 foreach를 바로 적용하면 PHP 경고가 발생합니다. @var 줄은 아래의 정적 분석에서 설명합니다.

시작 가격과 등급 두 개가 있는 블록을 렌더링하면 다음과 같습니다.

PHP
echo bs_block( array(
	'name' => 'acme/pricing',
	'data' => array(
		'price' => array( 'amount' => 19, 'currency' => 'EUR' ),
		'tiers' => array(
			array( 'name' => 'Starter', 'price' => array( 'amount' => 19, 'currency' => 'EUR' ) ),
			array( 'name' => 'Team', 'price' => array( 'amount' => 49, 'currency' => 'EUR' ) ),
		),
	),
) );
HTML
<!--blockstudio/acme/pricing--><section class="acme-pricing wp-block-acme-pricing">
  <p>From 19.00 EUR</p>
      <div class="acme-tier">
      <h3>Starter</h3>
      <p>19.00 EUR</p>
    </div>
      <div class="acme-tier">
      <h3>Team</h3>
      <p>49.00 EUR</p>
    </div>
  </section>

데이터가 전혀 없으면 필드 기본값이 적용되어 블록에 From 19.00 EUR가 렌더링되고 등급은 표시되지 않습니다. Twig과 Blade는 a.price.amount 및 $a['price']['amount']와 같은 값을 읽습니다. 확장 템플릿에서는 {attributes.price.amount}로 사용할 수 있습니다.

REST 스키마와 저장소

두 필드 모두 postMeta 저장소를 선언하므로 Blockstudio은 블록을 만들 때 메타 키 두 개를 등록합니다. 최상위 필드에는 등록된 저장소 스키마를 그대로 사용합니다.

JSON
{
  "type": "object",
  "single": true,
  "show_in_rest": {
    "schema": {
      "type": "object",
      "properties": {
        "amount": { "type": "number", "minimum": 0 },
        "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
      },
      "additionalProperties": false
    }
  }
}

반복 필드 내부의 필드는 행마다 값 하나를 저장하므로 메타 키는 배열 기반이며, 같은 스키마가 항목 스키마가 됩니다.

JSON
{
  "type": "array",
  "single": true,
  "show_in_rest": {
    "schema": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "amount": { "type": "number", "minimum": 0 },
          "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
        },
        "additionalProperties": false
      }
    }
  }
}

블록이 포함된 게시물을 저장하면 두 키가 모두 동기화됩니다. 위의 두 등급을 사용하면 get_post_meta( $id, 'acme_price', true )은 {"amount":19,"currency":"EUR"}을 반환하고 acme_tier_prices는 행별 가격 목록을 반환합니다.

JSON
[
  { "amount": 19, "currency": "EUR" },
  { "amount": 49, "currency": "EUR" }
]

두 키는 REST 응답의 meta 아래에 표시되며, REST 쓰기는 스키마에 따라 검증됩니다. 소문자 통화 코드를 사용한 쓰기는 거부됩니다.

JSON
{
  "code": "rest_invalid_pattern",
  "message": "meta.acme_price[currency] does not match pattern ^[A-Z]{3}$.",
  "data": { "status": 400 }
}

메타는 복사본입니다. 게시물 콘텐츠의 블록 속성이 원본이며, 저장할 때마다 구성된 키에 다시 동기화됩니다. 따라서 메타에 직접 쓴 값은 다음 게시물 저장 시 덮어써집니다. 옵션 저장소도 register_setting()를 통해 같은 방식으로 작동합니다. 반복 필드 내부의 배열 기반 저장소를 포함한 사용자 정의 필드 유형은 Blockstudio 7.5.0부터 사용할 수 있습니다.

정적 분석

PHPStan 확장은 기본 제공 필드 유형은 알고 있지만 프로젝트에서 런타임에 등록한 유형은 알지 못합니다. acme/price를 사용하는 블록에서는 필드 유형을 알 수 없는 것으로 보고하고 값을 mixed 유형으로 지정합니다.

Text
  2      block.json field "price" has unknown type "acme/price" in
         blockstudio/pricing/block.json
         🪪  blockstudio.blockJson.type

프로젝트 구성에서 자체 유형에 대한 진단을 무시하고 템플릿에서 유형을 좁히는 작업은 유지하세요. PHPStan에서 mixed 값을 max 수준으로 허용하려면 이 작업이 필요합니다.

Neon
parameters:
    level: max
    ignoreErrors:
        -
            identifier: blockstudio.blockJson.type
            message: '#unknown type "acme/price"#'

위 구성과 템플릿을 사용하면 분석을 통과합니다. 7.6에서는 @var 줄도 필요하며 사용자 정의 필드가 있는 위치에 mixed을 사용해야 합니다. Blockstudio 7.7에서는 해당 구조를 자체적으로 추론하므로 이 줄을 생략할 수 있습니다. 분석 실행 방법은 PHPStan를 사용하는 템플릿 확인을 참조하세요.

다음 단계