사용자 지정 필드
사용자 지정 필드를 사용하면 여러 블록에서 참조할 수 있는 재사용 가능한 필드 그룹을 정의할 수 있습니다. 필드 템플릿처럼 한 번 정의해 어디서나 사용하세요.
사용자 지정 필드는 사용자 지정 필드 유형과 다릅니다. 기존 필드를 재사용 가능한 그룹으로 묶으려면 custom/{name}를 사용하세요. 테마나 플러그인에서 새 편집기 컨트롤과 값 구조를 등록하는 경우 acme/dimensions 같은 네임스페이스가 지정된 사용자 지정 필드 유형을 사용하세요.
파일 시스템 등록
blockstudio 디렉터리 안의 fields/ 디렉터리에 field.json 파일을 만드세요.
theme/
└── blockstudio/
└── fields/
└── hero/
└── field.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 필터를 사용해 사용자 지정 필드를 프로그래밍 방식으로 등록하세요.
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} 유형을 사용해 사용자 지정 필드를 참조하세요.
{
"blockstudio": {
"attributes": [{ "type": "custom/hero" }]
}
}
이렇게 하면 사용자 지정 필드 정의에 지정된 필드가 인라인으로 확장됩니다. 확장된 필드는 원래 ID(heading, description, enabled)를 사용합니다.
사용자 지정 필드는 완전한 그룹 정의도 재사용할 수 있습니다.
{
"name": "section-header",
"attributes": [
{
"id": "section-header",
"type": "group",
"title": "Header",
"attributes": [
{ "id": "kicker", "type": "text", "label": "Kicker" },
{ "id": "title", "type": "text", "label": "Title" }
]
}
]
}
{
"blockstudio": {
"attributes": [{ "type": "custom/section-header" }]
}
}
그룹의 하위 항목은 section-header_kicker, section-header_title 등으로 저장됩니다. 템플릿에서는 bs_get_group()를 사용해 이를 깔끔한 그룹 객체로 추출하세요.
ID 구조
idStructure를 사용해 필드 ID에 접두사를 붙이거나 변환하세요. {id} 자리표시자는 원래 필드 ID로 대체됩니다.
{
"blockstudio": {
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
}
이렇게 하면 hero_heading, hero_description, hero_enabled ID를 가진 필드가 생성됩니다.
재정의
overrides를 사용해 인스턴스별 개별 필드를 사용자 지정하세요. 키는 정의에 지정된 원래 필드 ID입니다.
{
"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에도 동일하게 적용됩니다. 참조의 조건은 그 후에도 추가됩니다.
{
"type": "custom/background",
"overrides": {
"background": {
"options": [
{ "value": "white", "label": "White" },
{ "value": "grey", "label": "Grey" }
]
}
}
}
이 블록은 정의에 옵션이 몇 개 나열되어 있든 흰색과 회색만 제공합니다.
조건
사용자 지정 필드 정의 내의 조건은 idStructure가 적용될 때 자동으로 다시 작성됩니다. 형제 필드에 조건부로 종속된 필드는 확장 후에도 계속 작동합니다.
{
"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 }]]
}
]
}
{ "type": "custom/font-size", "idStructure": "title_font_{id}" }
Blockstudio는 이를 title_font_enable, title_font_min, title_font_max으로 확장하고, enable 대신 title_font_enable를 참조하도록 조건을 다시 작성합니다. 토글 컨트롤은 필드가 인라인으로 정의된 경우와 똑같이 작동합니다.
참조 수준 조건
참조에 conditions를 추가하면 확장된 모든 필드에 조건을 적용할 수 있습니다. 외부 토글로 그룹 전체를 숨길 때 유용합니다.
{
"type": "custom/font-size",
"idStructure": "subtitle_font_{id}",
"conditions": [[{ "id": "show_advanced", "operator": "==", "value": true }]]
}
이러한 조건은 필드 정의 내부에 이미 정의된 조건과 병합됩니다. 조건 ID도 idStructure를 통해 다시 작성됩니다.
여러 사용자 지정 필드
일반 필드와 함께 하나의 블록에서 여러 사용자 지정 필드를 사용할 수 있습니다.
{
"blockstudio": {
"attributes": [
{ "id": "intro", "type": "text", "label": "Intro" },
{ "type": "custom/hero", "idStructure": "hero_{id}" },
{ "type": "custom/cta", "idStructure": "cta_{id}" }
]
}
}
중첩
사용자 지정 필드는 그룹, 탭, 반복기 안에서도 작동합니다.
{
"blockstudio": {
"attributes": [
{
"type": "group",
"id": "content",
"title": "Content",
"attributes": [{ "type": "custom/hero", "idStructure": "hero_{id}" }]
}
]
}
}
추가 검색 경로
blockstudio/fields/paths 필터를 사용해 필드 검색을 위한 추가 디렉터리를 지정하세요.
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 필터를 통해서만 등록된 필드는 런타임에 존재하며 정적으로 추론할 수 없습니다.