본문으로 건너뛰기

필드 유형

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로 변환하지 않습니다. 자세한 내용은 이식 가능한 미디어 참조를 참조하세요.

선택기 요청, 재시도 및 아이콘 하위 집합은 아이콘 로딩을 참조하세요.

속성

데이터 속성 입력 필드를 렌더링합니다.

JSON
{
  "type": "attributes"
}

속성

속성 유형 설명
default array 블록을 처음 추가할 때 적용할 기본값입니다.
fallback array 필드 값이 비어 있을 때 표시할 대체 값입니다.
link boolean 드롭다운에서 링크를 선택할 수 있습니다.
media boolean 드롭다운에서 미디어를 선택할 수 있습니다.

블록

다른 Blockstudio 블록을 참조해 해당 필드를 인라인으로 확장합니다. 템플릿에서는 렌더링된 블록 출력이 값으로 반환됩니다.

JSON
{
  "type": "block"
}

속성

속성 유형 설명
block string 참조할 블록의 이름입니다(e.g., "mytheme/card").
returnFormat string 템플릿에서 값을 반환할 형식입니다.

체크박스

체크박스 입력 필드 집합을 렌더링합니다.

JSON
{
  "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 클래스를 선택하는 필드를 렌더링합니다.

JSON
{
  "type": "classes"
}

속성

속성 유형 설명
default string 블록을 처음 추가할 때 적용할 기본값입니다.
fallback string 필드 값이 비어 있을 때 표시할 대체 값입니다.
tailwind boolean 이 입력 필드에서 Tailwind 클래스를 사용할지 여부입니다.

코드

코드 편집기를 렌더링합니다.

JSON
{
  "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를 블록 에셋으로 렌더링하므로 템플릿에서 스타일 또는 스크립트 태그를 출력할 필요가 없습니다.

색상

색상 팔레트와 색상 선택기를 렌더링합니다.

JSON
{
  "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 사용자 지정 색상을 허용할지 여부입니다.

날짜

날짜 선택기를 렌더링합니다.

JSON
{
  "type": "date"
}

속성

속성 유형 설명
default string 블록을 처음 추가할 때 적용할 기본값입니다.
fallback string 필드 값이 비어 있을 때 표시할 대체 값입니다.
startOfWeek number 한 주가 시작되는 요일입니다. 일요일은 0, 월요일은 1이며, 그 이후 요일은 순서대로 지정됩니다.

날짜 및 시간

날짜 및 시간 선택기를 렌더링합니다.

JSON
{
  "type": "datetime"
}

속성

속성 유형 설명
default string 블록을 처음 추가할 때 적용할 기본값입니다.
fallback string 필드 값이 비어 있을 때 표시할 대체 값입니다.
is12Hour boolean 12시간제를 사용할지 여부입니다. 12시간제를 사용하면 AM/PM 위젯이 표시되며, 기본 형식 DD-MM-YYYY 대신 날짜 형식은 MM-DD-YYYY로 간주합니다.

파일

미디어 라이브러리를 여는 버튼을 렌더링합니다. 선택한 항목은 인라인으로 순서를 변경할 수 있습니다.

JSON
{
  "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 반환 형식을 사용할 때 반환할 미디어 크기입니다.

그라디언트

그라디언트 팔레트와 선택기를 렌더링합니다.

JSON
{
  "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 사용자 지정 색상을 허용할지 여부입니다.

그룹

필드를 (선택적으로) 접을 수 있는 컨테이너에 여러 개 렌더링합니다.

JSON
{
  "type": "group"
}

속성

속성 유형 설명
title string 제목 텍스트입니다. 구성 요소가 닫혀 있어도 표시됩니다.
opened boolean true로 설정하면 initialOpen 속성과 관계없이 구성 요소가 열린 상태로 유지됩니다.
initialOpen boolean 패널을 처음에 열어 둘지 여부입니다.
scrollAfterOpen boolean 콘텐츠가 표시될 때 해당 위치로 스크롤합니다.
class string 그룹에 적용할 사용자 지정 CSS 클래스입니다.
style object 그룹에 적용할 사용자 지정 CSS 스타일입니다.
attributes array 다른 탭을 제외한 모든 필드 유형을 허용합니다.

HTML 태그

HTML 태그 선택기를 렌더링합니다. 제목 수준이나 시맨틱 요소를 선택할 때 유용합니다.

JSON
{
  "type": "html-tag"
}

속성

속성 유형 설명
default string 블록을 처음 추가할 때 적용할 기본값입니다.
fallback string 필드 값이 비어 있을 때 표시할 대체 값입니다.
tags string | array 포함할 태그입니다. 프리셋 문자열이나 태그 이름 배열을 사용합니다.
exclude array 프리셋에서 제외할 태그입니다. tags에 프리셋 문자열을 사용할 때만 적용됩니다.

아이콘

아이콘 세트의 SVG 아이콘을 렌더링합니다.

JSON
{
  "type": "icon"
}

속성

속성 유형 설명
default object 블록을 처음 추가할 때 적용할 기본값입니다.
fallback object 필드 값이 비어 있을 때 표시할 대체 값입니다.
sets array | string 포함할 아이콘 세트입니다. 비워 두면 모두 포함합니다.
subSets array | string 포함할 하위 아이콘 세트입니다. 비워 두면 모두 포함합니다.
returnFormat string 아이콘의 반환 형식입니다.

내부 또는 외부 링크를 선택하는 링크 컨트롤을 렌더링합니다.

JSON
{
  "type": "link"
}

속성

속성 유형 설명
default object 블록을 처음 추가할 때 적용할 기본값입니다.
fallback object 필드 값이 비어 있을 때 표시할 대체 값입니다.
hasRichPreviews boolean URL을 추가할 때 서식 있는 미리보기를 표시할지 여부입니다.
noDirectEntry boolean URL와 유사한 검색어를 링크로 바로 변환할 수 있는지 여부입니다.
noURLSuggestion boolean 검색어를 URL로 처리하는 대체 제안을 추가할지 여부입니다.
opensInNewTab boolean 링크 모달에 토글 컨트롤을 추가합니다.
showSuggestions boolean URL 입력 시 제안을 표시할지 여부입니다.
textButton string 링크 버튼 안에 표시할 사용자 지정 텍스트입니다.
withCreateSuggestion boolean 일치하는 링크 검색 결과가 없을 때 새 임시 페이지 제안을 만들 수 있는지 여부입니다.

메시지

사용자 지정 콘텐츠가 포함된 메시지를 렌더링합니다.

JSON
{
  "type": "message"
}

속성

속성 유형 설명
default string 블록을 처음 추가할 때 적용할 기본값입니다.
fallback string 필드 값이 비어 있을 때 표시할 대체 값입니다.
value string 표시할 메시지입니다. 블록 및 속성 데이터는 대괄호 구문으로 사용할 수 있습니다. e.g: {block.title} 또는 {attributes.text}

숫자

숫자 입력 필드를 렌더링합니다.

JSON
{
  "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씩 증가하거나 감소합니다.

라디오

라디오 입력 필드 집합을 렌더링합니다.

JSON
{
  "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 선택된 라디오 입력을 다시 클릭해 값을 지울 수 있습니다.

범위

두 지점 사이의 숫자 값을 설정하는 범위 입력 필드를 렌더링합니다.

JSON
{
  "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로 재정의됩니다.

선택

하나 또는 여러 항목을 선택할 수 있는 선택 입력 필드를 렌더링합니다.

JSON
{
  "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이면 선택 항목을 초기화하는 버튼을 렌더링합니다.

탭

필드를 그룹화하는 탭 인터페이스를 렌더링합니다.

JSON
{
  "type": "tabs"
}

속성

속성 유형 설명
tabs array 표시할 탭입니다.

텍스트

한 줄 텍스트 입력 필드를 렌더링합니다.

JSON
{
  "type": "text",
  "min": 0,
  "max": 100
}

속성

속성 유형 설명
default string 블록을 처음 추가할 때 적용할 기본값입니다.
fallback string 필드 값이 비어 있을 때 표시할 대체 값입니다.
max number 최대 값 길이입니다.
min number 최소 값 길이입니다.

텍스트 영역

텍스트 영역 입력 필드를 렌더링합니다.

JSON
{
  "type": "textarea",
  "min": 0,
  "max": 100,
  "rows": 4
}

속성

속성 유형 설명
default string 블록을 처음 추가할 때 적용할 기본값입니다.
fallback string 필드 값이 비어 있을 때 표시할 대체 값입니다.
max number 최대 값 길이입니다.
min number 최소 값 길이입니다.
rows number 텍스트 영역에 포함할 행 수입니다.

토글

true/false 토글을 렌더링합니다.

JSON
{
  "type": "toggle"
}

속성

속성 유형 설명
default boolean 블록을 처음 추가할 때 적용할 기본값입니다.
fallback boolean 필드 값이 비어 있을 때 표시할 대체 값입니다.

반복기

반복할 수 있는 필드 집합을 렌더링합니다.

JSON
{
  "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 다른 탭 필드를 제외한 모든 필드 유형을 허용합니다.

리치 텍스트

리치 텍스트 필드용 속성 필드입니다.

JSON
{
  "type": "richtext"
}

속성

속성 유형 설명
default string 블록을 처음 추가할 때 적용할 기본값입니다.
fallback string 필드 값이 비어 있을 때 표시할 대체 값입니다.

단위

단위 드롭다운이 있는 숫자 입력 필드를 렌더링합니다.

JSON
{
  "type": "unit"
}

속성

속성 유형 설명
default string 블록을 처음 추가할 때 적용할 기본값입니다.
fallback string 필드 값이 비어 있을 때 표시할 대체 값입니다.
disableUnits boolean true이면 단위 선택 필드가 숨겨집니다.
isPressEnterToChange boolean true이면 onChange를 트리거하려면 ENTER 키를 눌러야 합니다. 이 옵션을 사용하면 탭 키로 필드에서 벗어날 때도 변경이 트리거됩니다.
isResetValueOnUnitChange boolean true이고 선택한 단위에 기본값이 있으면 단위를 변경할 때 이 값이 설정됩니다.
isUnitSelectTabbable boolean 단위 선택 필드에서 탭 키를 사용할 수 있는지 결정합니다.
units array

위지윅

위지윅 편집기를 렌더링합니다.

JSON
{
  "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
<?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 링크 도구 모음은 기본적으로 target 또는 rel를 추가하지 않고 같은 탭에서 여는 링크를 삽입합니다. 새 탭 옵션은 toolbar.formats.link.opensInNewTab로 활성화하세요:

JSON
{
  "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를 입력해도 자동으로 링크가 되지 않으며, 필드의 기존 링크를 클릭해도 편집기에서 벗어나지 않습니다. 이전에 저장된 링크 속성은 기존 콘텐츠에 남아 있으며 자동으로 변환되지 않습니다.