필드 유형
Blockstudio는 블록 인터페이스를 구축하기 위한 다양한 필드 유형을 제공합니다.
프로젝트에서는 blockstudio/field_types를 사용해 자체 네임스페이스 필드 유형을 등록할 수도 있습니다. 새 편집기 컨트롤이나 구조화된 값 형식이 필요할 때 사용하세요. 기존 필드 그룹만 재사용하려면 custom/{name} 필드를 사용하세요.
실용적인 레시피: 조건부 그룹, 스마트 선택 메뉴, 반복기, 쿼리 가능한 저장소.
일반 속성
아래 표에는 공통 속성과 일반적인 값 옵션이 나와 있습니다. 각 필드 유형의 속성 표에 표시된 경우 default 및 fallback이 지원됩니다.
| 속성 | 유형 | 설명 |
|---|---|---|
id |
문자열 | 속성의 고유 식별자 |
type |
문자열 | 필드 유형 |
label |
문자열 | 편집기에 표시되는 레이블 |
description |
문자열 | 필드 아래에 표시되는 설명 텍스트 |
default |
혼합형 | 필드의 기본값 |
fallback |
혼합형 | 필드가 비어 있을 때 사용할 대체 값 |
help |
문자열 | 레이블 옆에 툴팁으로 표시되는 도움말 텍스트 |
hidden |
불리언 | UI에서 필드 숨기기 |
switch |
불리언 | 필드를 비활성화할 수 있는 토글 표시. 기본값은 false. |
translate |
불리언 | false로 설정하면 필드를 WPML 구성에서 제외합니다 |
conditions |
배열 | 조건부 로직 규칙 |
"returnFormat": "id"이 있는 파일 필드는 반복 필드 내부의 단일 값을 포함해 가져온 문자열 참조를 보존합니다. 확인할 수 없는 이름은 썸네일 없이 대체 카드를 표시하며, Blockstudio은 이를 첨부 파일 ID로 변환하지 않습니다. 자세한 내용은 이식 가능한 미디어 참조를 참조하세요.
선택기 요청, 재시도 및 아이콘 하위 집합은 아이콘 로딩을 참조하세요.
속성
데이터 속성 입력 필드를 렌더링합니다.
{
"type": "attributes"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
array |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
array |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
link |
boolean |
드롭다운에서 링크를 선택할 수 있습니다. |
media |
boolean |
드롭다운에서 미디어를 선택할 수 있습니다. |
블록
다른 Blockstudio 블록을 참조해 해당 필드를 인라인으로 확장합니다. 템플릿에서는 렌더링된 블록 출력이 값으로 반환됩니다.
{
"type": "block"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
block |
string |
참조할 블록의 이름입니다(e.g., "mytheme/card"). |
returnFormat |
string |
템플릿에서 값을 반환할 형식입니다. |
체크박스
체크박스 입력 필드 집합을 렌더링합니다.
{
"type": "checkbox",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
array | string | number |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
array | string | number |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
options |
array |
선택할 수 있는 옵션입니다. |
returnFormat |
string |
반환 형식 값을 지정합니다. |
populate |
object |
|
toggle |
boolean | string |
모든 옵션을 선택하거나 선택 해제하는 체크박스를 옵션 위에 추가합니다. 문자열은 체크박스 레이블로 사용되며, true이면 기본 레이블을 사용합니다. |
클래스
CSS 클래스를 선택하는 필드를 렌더링합니다.
{
"type": "classes"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
string |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
string |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
tailwind |
boolean |
이 입력 필드에서 Tailwind 클래스를 사용할지 여부입니다. |
코드
코드 편집기를 렌더링합니다.
{
"type": "code"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
string |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
string |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
autoCompletion |
boolean |
자동 완성을 활성화할지 여부입니다. |
foldGutter |
boolean |
접기 여백을 표시할지 여부입니다. |
height |
string |
편집기의 높이입니다. |
language |
string |
구문 강조에 사용할 언어입니다. |
lineNumbers |
boolean |
줄 번호를 표시할지 여부입니다. |
maxHeight |
string |
편집기의 최대 높이입니다. |
minHeight |
string |
편집기의 최소 높이입니다. |
popout |
boolean |
편집기를 팝업 창에서 여는 버튼을 표시할지 여부입니다. |
asset |
boolean |
필드의 CSS, SCSS 또는 JavaScript를 블록 에셋으로 렌더링하므로 템플릿에서 스타일 또는 스크립트 태그를 출력할 필요가 없습니다. |
색상
색상 팔레트와 색상 선택기를 렌더링합니다.
{
"type": "color",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
string |
블록을 처음 추가할 때 선택할 옵션 값입니다. |
fallback |
string |
필드 값이 비어 있을 때 표시할 옵션 값입니다. |
options |
array |
|
populate |
object |
|
clearable |
boolean |
팔레트에 지우기 버튼을 표시할지 여부입니다. |
disableCustomColors |
boolean |
사용자 지정 색상을 허용할지 여부입니다. |
날짜
날짜 선택기를 렌더링합니다.
{
"type": "date"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
string |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
string |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
startOfWeek |
number |
한 주가 시작되는 요일입니다. 일요일은 0, 월요일은 1이며, 그 이후 요일은 순서대로 지정됩니다. |
날짜 및 시간
날짜 및 시간 선택기를 렌더링합니다.
{
"type": "datetime"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
string |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
string |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
is12Hour |
boolean |
12시간제를 사용할지 여부입니다. 12시간제를 사용하면 AM/PM 위젯이 표시되며, 기본 형식 DD-MM-YYYY 대신 날짜 형식은 MM-DD-YYYY로 간주합니다. |
파일
미디어 라이브러리를 여는 버튼을 렌더링합니다. 선택한 항목은 인라인으로 순서를 변경할 수 있습니다.
{
"type": "files",
"min": 0,
"max": 100,
"multiple": false
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
array | object | number |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
array | object | number |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
addToGallery |
boolean |
true이면 갤러리 미디어 모달이 미디어 라이브러리에서 바로 열려 사용자가 이미지를 추가할 수 있습니다. false이면 갤러리 미디어 모달이 편집 모드로 열려 기존 이미지의 순서를 바꾸거나 삭제하거나 속성을 변경할 수 있습니다. gallery === true일 때만 적용됩니다. |
allowedTypes |
array | string |
미디어 라이브러리에서 업로드하거나 선택할 미디어 유형의 배열입니다. 각 유형은 일반 MIME 유형 e.g: ‘image’, ‘audio’, ‘text’를 포함할 수 있는 문자열이거나 완전한 MIME 유형 e.g: ‘audio/mpeg’, ‘image/gif’입니다. allowedTypes를 설정하지 않으면 모든 MIME 유형을 허용합니다. |
gallery |
boolean |
true이면 갤러리를 나타내는 데 필요한 모든 상태를 구성 요소가 초기화합니다. 기본적으로 미디어 모달은 갤러리 편집 화면에서 열리지만 addToGalleryflag를 사용해 변경할 수 있습니다. |
max |
number |
추가할 수 있는 파일의 최대 개수입니다. |
min |
number |
추가할 수 있는 파일의 최소 개수입니다. |
multiple |
boolean |
여러 항목을 선택할 수 있는지 여부입니다. |
size |
boolean |
필드에 미디어 크기 드롭다운을 추가합니다. |
textMediaButton |
string |
미디어 버튼 텍스트입니다. |
title |
string |
미디어 모달에 표시되는 제목입니다. |
returnFormat |
string |
반환 형식을 지정합니다. |
returnSize |
string |
URL 반환 형식을 사용할 때 반환할 미디어 크기입니다. |
그라디언트
그라디언트 팔레트와 선택기를 렌더링합니다.
{
"type": "gradient",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
string |
블록을 처음 추가할 때 선택할 옵션 값입니다. |
fallback |
string |
필드 값이 비어 있을 때 표시할 옵션 값입니다. |
options |
array |
|
populate |
object |
|
clearable |
boolean |
팔레트에 지우기 버튼을 표시할지 여부입니다. |
disableCustomGradients |
boolean |
사용자 지정 색상을 허용할지 여부입니다. |
그룹
필드를 (선택적으로) 접을 수 있는 컨테이너에 여러 개 렌더링합니다.
{
"type": "group"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
title |
string |
제목 텍스트입니다. 구성 요소가 닫혀 있어도 표시됩니다. |
opened |
boolean |
true로 설정하면 initialOpen 속성과 관계없이 구성 요소가 열린 상태로 유지됩니다. |
initialOpen |
boolean |
패널을 처음에 열어 둘지 여부입니다. |
scrollAfterOpen |
boolean |
콘텐츠가 표시될 때 해당 위치로 스크롤합니다. |
class |
string |
그룹에 적용할 사용자 지정 CSS 클래스입니다. |
style |
object |
그룹에 적용할 사용자 지정 CSS 스타일입니다. |
attributes |
array |
다른 탭을 제외한 모든 필드 유형을 허용합니다. |
HTML 태그
HTML 태그 선택기를 렌더링합니다. 제목 수준이나 시맨틱 요소를 선택할 때 유용합니다.
{
"type": "html-tag"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
string |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
string |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
tags |
string | array |
포함할 태그입니다. 프리셋 문자열이나 태그 이름 배열을 사용합니다. |
exclude |
array |
프리셋에서 제외할 태그입니다. tags에 프리셋 문자열을 사용할 때만 적용됩니다. |
아이콘
아이콘 세트의 SVG 아이콘을 렌더링합니다.
{
"type": "icon"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
object |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
object |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
sets |
array | string |
포함할 아이콘 세트입니다. 비워 두면 모두 포함합니다. |
subSets |
array | string |
포함할 하위 아이콘 세트입니다. 비워 두면 모두 포함합니다. |
returnFormat |
string |
아이콘의 반환 형식입니다. |
링크
내부 또는 외부 링크를 선택하는 링크 컨트롤을 렌더링합니다.
{
"type": "link"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
object |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
object |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
hasRichPreviews |
boolean |
URL을 추가할 때 서식 있는 미리보기를 표시할지 여부입니다. |
noDirectEntry |
boolean |
URL와 유사한 검색어를 링크로 바로 변환할 수 있는지 여부입니다. |
noURLSuggestion |
boolean |
검색어를 URL로 처리하는 대체 제안을 추가할지 여부입니다. |
opensInNewTab |
boolean |
링크 모달에 토글 컨트롤을 추가합니다. |
showSuggestions |
boolean |
URL 입력 시 제안을 표시할지 여부입니다. |
textButton |
string |
링크 버튼 안에 표시할 사용자 지정 텍스트입니다. |
withCreateSuggestion |
boolean |
일치하는 링크 검색 결과가 없을 때 새 임시 페이지 제안을 만들 수 있는지 여부입니다. |
메시지
사용자 지정 콘텐츠가 포함된 메시지를 렌더링합니다.
{
"type": "message"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
string |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
string |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
value |
string |
표시할 메시지입니다. 블록 및 속성 데이터는 대괄호 구문으로 사용할 수 있습니다. e.g: {block.title} 또는 {attributes.text} |
숫자
숫자 입력 필드를 렌더링합니다.
{
"type": "number",
"min": 0,
"max": 100,
"step": 1
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
number |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
number |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
dragDirection |
string |
값을 늘리거나 줄일 때 사용할 드래그 축을 지정합니다. |
dragThreshold |
number |
isDragEnabled가 true이면 값이 바뀌기 전에 드래그해야 하는 픽셀 수입니다. |
hideHTMLArrows |
boolean |
true이면 기본 입력 HTML 화살표를 숨깁니다. |
isShiftStepEnabled |
boolean |
true이면 마우스 드래그 동작으로 숫자 값을 늘리거나 줄일 수 있습니다. 드래그하는 동안 SHIFT를 누르면 shiftStep만큼 값이 증가합니다. |
max |
number |
최대 값 길이입니다. |
min |
number |
최소 값 길이입니다. |
required |
boolean |
true이면 컨트롤의 min/max 범위 안에서 유효한 숫자를 입력하도록 합니다. false이면 빈 문자열도 유효한 값으로 허용합니다. |
shiftStep |
number |
SHIFT 키를 누른 상태에서 증가시킬 양입니다. 이 shift 값은 step 값의 배수입니다. 예를 들어 step 값이 5이고 shiftStep이 10이면 한 번 움직일 때마다 50씩 증가하거나 감소합니다. |
step |
number |
값을 늘리거나 줄일 때 변경되는 양입니다. 값이 유효하려면 step의 배수여야 하므로(min이 지정된 경우 min을 기준으로 계산) 유효성 검사에도 사용됩니다. 특수 문자열 값 any를 사용하면 유효성 검사 제약이 해제되고 단계별 조정 시 1씩 증가하거나 감소합니다. |
라디오
라디오 입력 필드 집합을 렌더링합니다.
{
"type": "radio",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
]
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
string | number |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
string | number |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
options |
array |
선택할 수 있는 옵션입니다. |
returnFormat |
string |
반환 형식 값을 지정합니다. |
populate |
object |
|
display |
string |
라디오 입력 대신 버튼 그룹으로 옵션을 표시하려면 buttonGroup으로 설정합니다. |
allowNull |
boolean |
선택된 라디오 입력을 다시 클릭해 값을 지울 수 있습니다. |
범위
두 지점 사이의 숫자 값을 설정하는 범위 입력 필드를 렌더링합니다.
{
"type": "range",
"min": 0,
"max": 100,
"step": 1
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
number |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
number |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
allowReset |
boolean |
true이면 슬라이더를 초기화하는 버튼을 렌더링합니다. |
initialPosition |
number |
값이 전달되지 않았을 때 사용할 슬라이더 시작 위치입니다. initialPosition은 지정된 min 및 max 속성 값 사이로 제한됩니다. |
isShiftStepEnabled |
boolean |
true이면 마우스 드래그 동작으로 숫자 값을 늘리거나 줄일 수 있습니다. 드래그하는 동안 SHIFT를 누르면 shiftStep만큼 값이 증가합니다. |
marks |
array |
단계 눈금을 시각적으로 표시합니다. Array를 사용해 사용자 지정 표시를 지정할 수 있습니다. |
max |
number |
최대 값 길이입니다. |
min |
number |
최소 값 길이입니다. |
railColor |
string |
레일 요소의 배경을 사용자 지정하는 CSS 색상 문자열입니다. |
resetFallbackValue |
number |
Reset 버튼을 클릭할 때 되돌릴 값입니다(allowReset으로 활성화). |
separatorType |
string |
컨트롤 행 위/아래의 구분선을 비활성화할지 또는 전체 너비로 표시할지 지정합니다. 기본적으로는 컨트롤 아이콘 아래쪽 밑줄을 제외한 위치에 표시됩니다. |
shiftStep |
number |
SHIFT 키를 누른 상태에서 증가시킬 양입니다. 이 shift 값은 step 값의 배수입니다. 예를 들어 step 값이 5이고 shiftStep이 10이면 한 번 움직일 때마다 50씩 증가하거나 감소합니다. |
showTooltip |
boolean |
Tooltip UI을 강제로 표시하거나 숨깁니다. step을 특수 문자열 값 any로 설정하면 이 값은 false로 재정의됩니다. |
step |
number |
값을 늘리거나 줄일 때 변경되는 양입니다. 값이 유효하려면 step의 배수여야 하므로(min이 지정된 경우 min을 기준으로 계산) 유효성 검사에도 사용됩니다. 특수 문자열 값 any를 사용하면 유효성 검사 제약이 해제되고 단계별 조정 시 1씩 증가하거나 감소합니다. |
trackColor |
string |
트랙 요소의 배경을 사용자 지정하는 CSS 색상 문자열입니다. |
withInputField |
boolean |
숫자 입력 필드를 RangeControl 옆에 렌더링할지 여부를 지정합니다. step을 특수 문자열 값 any로 설정하면 이 값은 false로 재정의됩니다. |
선택
하나 또는 여러 항목을 선택할 수 있는 선택 입력 필드를 렌더링합니다.
{
"type": "select",
"options": [
{
"value": "option1",
"label": "Option 1"
},
{
"value": "option2",
"label": "Option 2"
}
],
"multiple": false
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
array | string | number |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
array | string | number |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
multiple |
boolean |
true이면 여러 옵션을 선택할 수 있습니다. "stylisedUi"가 자동으로 활성화됩니다. |
options |
array |
선택할 수 있는 옵션입니다. |
returnFormat |
string |
반환 형식을 지정합니다. |
populate |
object |
|
stylisedUi |
boolean |
항목을 검색할 수 있는 스타일이 적용된 선택 필드를 렌더링합니다. |
allowNull |
boolean | string |
빈 선택 항목을 허용합니다. true이면 레이블이 비어 있고, false이면 지정된 문자열이 옵션으로 표시됩니다. |
allowReset |
boolean |
true이면 선택 항목을 초기화하는 버튼을 렌더링합니다. |
탭
필드를 그룹화하는 탭 인터페이스를 렌더링합니다.
{
"type": "tabs"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
tabs |
array |
표시할 탭입니다. |
텍스트
한 줄 텍스트 입력 필드를 렌더링합니다.
{
"type": "text",
"min": 0,
"max": 100
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
string |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
string |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
max |
number |
최대 값 길이입니다. |
min |
number |
최소 값 길이입니다. |
텍스트 영역
텍스트 영역 입력 필드를 렌더링합니다.
{
"type": "textarea",
"min": 0,
"max": 100,
"rows": 4
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
string |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
string |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
max |
number |
최대 값 길이입니다. |
min |
number |
최소 값 길이입니다. |
rows |
number |
텍스트 영역에 포함할 행 수입니다. |
토글
true/false 토글을 렌더링합니다.
{
"type": "toggle"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
boolean |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
boolean |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
반복기
반복할 수 있는 필드 집합을 렌더링합니다.
{
"type": "repeater",
"min": 0,
"max": 100
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
array |
새 블록이 시작할 행입니다. 각 행은 필드 값 객체입니다. min으로 생성한 행보다 우선 적용됩니다. |
min |
number |
최소 행 수입니다. |
max |
number |
최대 행 수입니다. |
minimized |
boolean |
편집기를 열 때 기존 행을 접습니다. 편집기에서 추가한 행은 펼쳐진 상태로 시작합니다. |
textButton |
string |
추가 버튼에 표시할 텍스트입니다. |
textMinimized |
string | object |
행을 최소화했을 때 표시할 텍스트입니다. |
textRemove |
string | boolean |
반복 필드 행을 삭제할 때 편집기에 표시되는 확인 질문입니다. 비어 있지 않은 문자열을 지정하면 질문이 바뀌고, false를 지정하면 대화상자 없이 바로 삭제합니다. 생략하거나 true 또는 빈 문자열을 지정하면 기본 질문을 사용합니다. |
attributes |
array |
다른 탭 필드를 제외한 모든 필드 유형을 허용합니다. |
리치 텍스트
리치 텍스트 필드용 속성 필드입니다.
{
"type": "richtext"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
string |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
string |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
단위
단위 드롭다운이 있는 숫자 입력 필드를 렌더링합니다.
{
"type": "unit"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
string |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
string |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
disableUnits |
boolean |
true이면 단위 선택 필드가 숨겨집니다. |
isPressEnterToChange |
boolean |
true이면 onChange를 트리거하려면 ENTER 키를 눌러야 합니다. 이 옵션을 사용하면 탭 키로 필드에서 벗어날 때도 변경이 트리거됩니다. |
isResetValueOnUnitChange |
boolean |
true이고 선택한 단위에 기본값이 있으면 단위를 변경할 때 이 값이 설정됩니다. |
isUnitSelectTabbable |
boolean |
단위 선택 필드에서 탭 키를 사용할 수 있는지 결정합니다. |
units |
array |
위지윅
위지윅 편집기를 렌더링합니다.
{
"type": "wysiwyg"
}
속성
| 속성 | 유형 | 설명 |
|---|---|---|
default |
string |
블록을 처음 추가할 때 적용할 기본값입니다. |
fallback |
string |
필드 값이 비어 있을 때 표시할 대체 값입니다. |
toolbar |
object |
편집기의 도구 모음 설정입니다. |
mode |
string |
code는 필드를 코드 보기로 엽니다. both는 시각적 보기와 코드 보기 사이를 전환하는 버튼을 추가합니다. |
아이콘 로드
편집기는 블록을 선택할 때가 아니라, 아이콘 선택기를 처음 포커스하거나 세트 또는 하위 세트를 변경할 때 아이콘 세트를 불러옵니다. 같은 세트를 요청하는 필드는 진행 중인 요청을 공유합니다. 불러오기 전에도 저장된 아이콘 이름은 표시되며, 요청에 실패하면 선택기에 다시 포커스해 재시도할 수 있습니다.
tabler-icons은 outline 및 filled를 지원합니다. 선택한 세트에 명시적으로 설정된 하위 세트가 우선 적용됩니다. 그렇지 않으면 선택기에서 사용 가능한 경우 solid을 사용하고, 없으면 세트의 첫 번째 하위 세트를 사용합니다. 하위 세트가 없는 세트에는 subSet가 포함되지 않습니다. 세트 이름은 번들 파일에 대해서만 확인됩니다. 프런트엔드 렌더링은 전체 아이콘 세트를 데이터베이스 transient에 저장하는 대신 개별 아이콘을 캐시합니다.
가져온 옵션 값
"multiple": true이 있는 체크박스와 선택 필드는 일반적으로 { "value": "...", "label": "..." } 객체의 배열을 저장합니다. 또한 단일 옵션 객체, 스칼라 문자열 또는 숫자, REST API 또는 콘텐츠 도구를 통해 가져온 스칼라 값의 배열도 허용합니다. 반복 필드 행 안에서도 사용할 수 있습니다.
편집기는 변경 없이 저장할 때 저장된 형태를 다시 쓰지 않고 이 값들을 선택 항목으로 표시합니다. 선택 항목을 추가하거나 제거하면 일반적인 옵션 객체 배열로 저장됩니다. 숫자 0과 문자열 "0"은 유효한 선택 항목입니다. 템플릿은 편집기에서 선택한 값과 마찬가지로 필드에 설정된 returnFormat를 받습니다. 옵션은 여전히 필드에 선언되었거나 채워진 선택 항목과 일치해야 합니다.
저장된 값이나 기본값이 없는 기본 단일 선택 필드는 첫 번째 옵션이 아니라 비활성화된 빈 자리표시자를 표시합니다. 첫 번째 옵션을 직접 선택하면 해당 값이 저장됩니다. 선택 항목이 저장되면 자리표시자는 사라집니다. 편집기에서도 선택 항목을 지울 수 있어야 한다면 allowNull을 사용하세요. 빈 자리표시자만으로는 그 외에 필수인 선택 항목을 지울 수 없습니다.
반복 필드의 초기 행
편집기에서 기본값에는 삽입 전에 생성되는 중첩 최소 행이 포함됩니다. 해당 행을 초기화하기 위해 블록 설정을 열 필요가 없으며, 블록을 삽입해도 해당 행에 대해 실행 취소 단계가 추가되지 않습니다.
반복 필드에 min가 있지만 저장된 값이나 명시적인 default가 없으면, 서버는 해당 개수만큼 행을 초기화하고 각 행 필드의 기본값을 사용합니다. 이는 PHP 임베드, 블록 태그, 편집기에서 한 번도 열지 않은 파일 기반 페이지 소스에도 적용됩니다. 예를 들어, 텍스트 필드의 기본값이 "New item"인 "min": 2는 해당 값이 포함된 두 행을 렌더링합니다.
저장된 행과 명시적인 반복 필드 default가 우선 적용됩니다. 명시적으로 저장된 빈 목록인 false 또는 null는 제거된 행을 다시 만들지 않습니다. 렌더링 과정에서 생성된 기본값은 글에 저장되지 않습니다. min 및 max는 편집기 컨트롤을 제한할 뿐, 렌더링 시 저장된 목록을 자르거나 채우지 않습니다. 가져온 콘텐츠에서 행 수 제한 위반을 보고하려면 bs_validate_block()를 사용하세요.
default가 없는 행 필드는 생성된 행에서 false 상태이므로 해당 행에는 콘텐츠가 없습니다. 편집기에서 추가한 뒤 비워 둔 행도 같은 모습입니다. 모든 행에 카드, 제목 또는 목록 항목을 출력하는 템플릿은 편집기 밖에서는 콘텐츠가 없는 행을 건너뛰고, 편집기에서는 필드를 계속 편집할 수 있도록 해당 행을 유지해야 합니다:
<?php foreach ( $a['items'] as $item ) : ?>
<?php if ( ! $isEditor && ! $item['title'] && ! $item['text'] ) continue; ?>
<div class="item">
<h3><?php echo $item['title']; ?></h3>
<p><?php echo $item['text']; ?></p>
</div>
<?php endforeach; ?>
반복 필드 행 삭제
행을 제거하면 편집기의 확인 대화 상자에 삭제 및 취소 버튼이 표시됩니다. 취소를 선택하거나 Escape를 누르면 행은 변경되지 않습니다. 중첩된 반복 필드에서도 확인한 뒤에만 행이 제거됩니다.
textRemove는 모든 반복 필드에서 동일한 동작을 제어합니다:
| 값 | 동작 |
|---|---|
생략, true 또는 "" |
기본 확인 질문을 표시합니다. |
| 비어 있지 않은 문자열 | 기존 사용자 지정 텍스트 번역 메커니즘을 사용해 사용자 지정 질문을 표시합니다. |
false |
대화 상자 없이 행을 즉시 제거합니다. |
예를 들어, "textRemove": "Remove this team member?"는 질문을 변경합니다.
기존 min 제한은 최소 행 수보다 적게 행을 제거하지 못하도록 계속 방지합니다.
반복 필드 중첩
반복 필드 행에는 tabs를 제외한 모든 필드 유형을 사용할 수 있습니다. 행 안의 tabs 필드가 id가 없는 그룹 내부에 있어도, 편집기에서는 해당 필드 대신 알림이 표시됩니다. PHPStan 확장 프로그램은 block.json 및 field.json에서 이를 보고합니다. 행의 필드는 평면 구조로 유지하거나 탭을 반복 필드 바깥으로 옮기세요.
WYSIWYG 링크
WYSIWYG 링크 도구 모음은 기본적으로 target 또는 rel를 추가하지 않고 같은 탭에서 여는 링크를 삽입합니다. 새 탭 옵션은 toolbar.formats.link.opensInNewTab로 활성화하세요:
{
"id": "content",
"type": "wysiwyg",
"toolbar": {
"formats": {
"link": {
"opensInNewTab": true
}
}
}
}
새 탭을 선택하면 target="_blank" 및 rel="noreferrer noopener"가 추가됩니다.
이 옵션을 끄면 자동 속성이 제거됩니다. 해당 필드의 모든 링크에 속성을 적용하려면 toolbar.formats.link.attributes를 설정하세요. 예: { "class": "content-link", "rel": "nofollow" }. 명시적 설정은 유지되며, 새 탭의 보안 토큰은 설정된 rel에 추가됩니다.
URL를 입력해도 자동으로 링크가 되지 않으며, 필드의 기존 링크를 클릭해도 편집기에서 벗어나지 않습니다. 이전에 저장된 링크 속성은 기존 콘텐츠에 남아 있으며 자동으로 변환되지 않습니다.