사용자 지정 필드 유형
사용자 지정 필드 유형을 사용하면 테마나 플러그인에서 새로운 Blockstudio 필드 컨트롤을 추가할 수 있습니다. 사용자 지정 필드와는 다릅니다.
custom/{name}는 기존 필드를 재사용 가능한 그룹으로 묶은 것입니다.namespace/type-name는 자체 편집기 컨트롤과 값 구조를 가진 등록된 필드 유형을 사용합니다.
Blockstudio는 등록 시스템을 제공합니다. 컨트롤은 테마나 플러그인에서 제공합니다.
사용 시점
프로젝트에서 어디서나 기본 Blockstudio 필드처럼 작동해야 하는 단일 목적의 편집 컨트롤이 필요할 때 사용자 지정 필드 유형을 사용하세요.
- 블록 속성
- 재사용 가능한
custom/{name}필드 그룹 - 그룹, 탭, 반복기
- PHP, Twig, Blade 템플릿
- 게시물 메타 및 옵션 저장소
{attributes.margin.top}같은 확장 템플릿
예를 들어 간격 컨트롤은 텍스트 필드 4개 대신 객체 하나를 저장할 수 있습니다.
{
"blockstudio": {
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"sides": ["top", "right", "bottom", "left"],
"default": {
"top": "sm",
"right": "md",
"bottom": "sm",
"left": "md"
}
}
]
}
}
이름 지정
사용자 지정 필드 유형 이름은 소문자, 네임스페이스 포함, 대시 표기법을 사용해야 합니다.
namespace/type-name
유효한 예:
acme/dimensionsacme/text-optionstheme/spacing-token
예약된 네임스페이스:
custom/는 재사용 가능한 사용자 지정 필드 그룹용으로 예약되어 있습니다.blockstudio/는 Blockstudio 핵심용으로 예약되어 있습니다.
잘못된 이름은 API 필터에서 무시되며 API 헬퍼에서 거부됩니다.
PHP 등록
PHP에서 필드 유형 메타데이터를 등록하세요.
add_action('init', function () {
wp_register_script(
'acme-field-dimensions',
get_stylesheet_directory_uri() . '/fields/dimensions.js',
['blockstudio-blocks', 'wp-components', 'wp-element'],
'1.0.0',
true
);
bs_register_field_type('acme/dimensions', [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
'storage' => [
'type' => 'object',
'rest_schema' => [
'type' => 'object',
'additionalProperties' => ['type' => 'string'],
],
],
]);
});
등록에 성공하면 bs_register_field_type()는 true을 반환하고, 이름이나 정의가 유효하지 않으면 false를 반환합니다.
수동 등록은 bs_unregister_field_type()을 사용해 해제할 수 있습니다.
API 필터를 사용할 수도 있습니다.
add_filter('blockstudio/field_types', function (array $types): array {
$types['acme/dimensions'] = [
'attribute' => 'object',
'default' => [],
'editor_script' => 'acme-field-dimensions',
];
return $types;
});
정의 키
| 키 | 유형 | 설명 |
|---|---|---|
attribute |
string, array, null |
WordPress 속성 유형입니다. string, number, boolean, object, array 또는 이러한 유형의 배열을 사용하세요. |
default |
mixed | 필드에 자체 기본값이 정의되지 않은 경우 사용하는 레지스트리 수준 기본값입니다. |
source |
string | 사용자 지정 직렬화 사례를 위한 WordPress 속성 소스입니다. |
produces_attribute |
boolean | 표시 전용 컨트롤에는 false로 설정하세요. 기본값은 true입니다. |
editor_script |
string or array | 해당 유형을 사용할 때 블록 편집기에 추가할 등록된 스크립트 핸들입니다. 하나 이상 지정할 수 있습니다. |
editor_style |
string or array | 해당 유형을 사용할 때 블록 편집기에 추가할 등록된 스타일 핸들입니다. 하나 이상 지정할 수 있습니다. |
storage |
array | 저장 값 유형 및 게시물 메타와 옵션을 위한 REST 스키마 힌트입니다. |
supports |
array | 자체 컨트롤에 사용할 수 있는 선택적 기능 플래그입니다. |
translate |
boolean | 값이 WPML에서 번역할 텍스트인 경우 true로 설정하세요. attribute string가 필요합니다. |
translate 값이 불리언이 아니거나, translate이 true로 설정되어 있고 attribute이 string가 아닌 정의는 유효하지 않습니다.
bs_register_field_type()은 false을 반환하며 필터 API은 이를 무시합니다.
WPML
wp bs wpml config은 등록 정보만으로 사용자 지정 필드 유형의 값이 텍스트인지 판별할 수 없으므로 해당 필드를 제외하고 각 필드에 경고를 표시합니다. 일반 텍스트 문자열을 저장하는 필드 유형을 등록할 때 translate을 true로 설정하면 명령이 해당 필드를 text 필드로 선언합니다. 필드별로 "translate": false를 사용해 제외할 수도 있습니다. 자세한 내용은 WPML필드 등록을 참조하세요.
bs_register_field_type('acme/headline', [
'attribute' => 'string',
'translate' => true,
]);
JavaScript 등록
편집기 스크립트에서 이에 대응하는 React 컨트롤을 등록합니다.
const { createElement: el } = wp.element;
const { TextControl } = wp.components;
window.blockstudio.registerFieldType('acme/dimensions', {
component(props) {
const value =
props.value &&
typeof props.value === 'object' &&
!Array.isArray(props.value)
? props.value
: {};
const sides = props.sides || ['top', 'right', 'bottom', 'left'];
return el(
'div',
{},
sides.map((side) =>
el(TextControl, {
key: side,
label: side,
value: value[side] || '',
onChange(nextValue) {
props.onChange({
...value,
[side]: nextValue,
});
},
}),
),
);
},
});
등록이 승인되면 registerFieldType()는 true을 반환합니다. 클라이언트 등록은 다음과 같이 제거하세요.
window.blockstudio.unregisterFieldType('acme/dimensions');
컴포넌트는 필드 정의 속성과 함께 다음의 고정된 props를 받습니다.
| Prop | 설명 |
|---|---|
type |
필드 유형 이름. |
id |
필드 ID. |
field |
block.json의 전체 필드 정의. |
value |
현재 저장된 값. |
defaultValue |
필드 기본값. |
onChange |
새 값을 직접 저장합니다. |
attributes |
현재 블록 속성. |
block |
현재 블록 유형 정의. |
clientId |
현재 편집기 블록 클라이언트 ID. |
inRepeater |
필드가 반복기 행 안에 있는지 여부. |
repeaterId |
현재 반복기 경로(있는 경우). |
disabled |
편집기에서 필드가 비활성화되어 있는지 여부. |
사용자 지정 필드 유형 값은 직접 저장됩니다. 기본 select, radio, color, gradient 옵션 정규화를 거치지 않습니다.
값 렌더링
객체 값은 다른 Blockstudio 속성과 마찬가지로 사용할 수 있습니다.
PHP
<div class="<?php echo esc_attr('mt-' . ($a['margin']['top'] ?? '')); ?>">
<?php echo esc_html($a['title'] ?? ''); ?>
</div>
Twig
<div class="mt-{{ a.margin.top }}">
{{ a.title }}
</div>
Blade
<div class="mt-{{ $a['margin']['top'] ?? '' }}">
{{ $a['title'] ?? '' }}
</div>
중첩된 객체 경로도 확장 템플릿에서 사용할 수 있습니다.
{
"blockstudio": {
"extend": "core/group",
"attributes": [
{
"id": "margin",
"type": "acme/dimensions",
"set": [
{
"attribute": "class",
"value": "mt-{attributes.margin.top} mb-{attributes.margin.bottom}"
}
]
}
]
}
}
저장
사용자 지정 필드 유형을 postMeta 또는 option 저장소와 함께 사용하면 Blockstudio는 등록된 저장 값 유형과 REST 스키마를 사용합니다.
{
"id": "margin",
"type": "acme/dimensions",
"label": "Margin",
"storage": {
"type": "postMeta",
"postMetaKey": "acme_margin"
}
}
array 및 object 값의 경우 필드 유형 등록에 storage.rest_schema를 정의하세요. 반복기는 행을 저장하므로 하위 항목은 배열 기반 저장소를 계속 사용합니다.
대체 동작
PHP에서 필드 유형은 알고 있지만 편집기 스크립트에 이에 대응하는 컨트롤이 등록되지 않은 경우, Blockstudio는 저장된 값을 유지하고 편집기에 수정할 수 없다는 알림을 표시합니다. 프런트엔드 렌더링에서는 계속 저장된 값을 받습니다.
필드 유형이 PHP에 등록되지 않은 경우 Blockstudio는 생성된 WordPress 속성에서 해당 필드를 제외합니다. 블록 검색이 실행되기 전에 PHP 정의를 등록하세요. 보통 init에서 Blockstudio가 블록을 빌드하기 전에 등록합니다.