字段类型
Blockstudio 提供多种字段类型,用于构建区块界面。
项目还可以通过 blockstudio/field_types 注册自己的带命名空间字段类型。当你需要新的编辑器控件或结构化值时,请使用这种方式。如果只需复用一组现有字段,请使用 custom/{name} 字段。
实用配方:条件组、智能选择框、Repeater 和可查询存储。
常规属性
下表列出了共享属性和常见的值选项。各字段类型的“属性”表中列出的default和fallback均受支持。
| 属性 | 类型 | 说明 |
|---|---|---|
id |
string | 属性的唯一标识符 |
type |
string | 字段类型 |
label |
string | 在编辑器中显示的标签 |
description |
string | 显示在字段下方的说明文本 |
default |
mixed | 字段的默认值 |
fallback |
mixed | 字段为空时使用的回退值 |
help |
string | 显示在标签旁工具提示中的帮助文本 |
hidden |
boolean | 在UI中隐藏该字段 |
switch |
boolean | 显示一个可禁用该字段的切换开关。默认值为false。 |
translate |
boolean | 设为false即可将该字段排除在WPML配置之外 |
conditions |
array | 条件逻辑规则 |
带有"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 控件,并假定时间格式为 MM-DD-YYYY(而非默认格式 DD-MM-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,则强制数值处于控件的最小值和最大值范围内。如果为 false,则允许空字符串作为有效值。 |
shiftStep |
number |
按住 SHIFT 键时增加的数值。此偏移值是步长值的倍数。例如,步长值为 5、shiftStep 为 10 时,每次跳变会增加或减少 50。 |
step |
number |
增加或减少时数值变化的量。它也是验证依据:值必须是步长的倍数(如果指定了 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 |
渲染步进刻度的可视化表示。可通过数组提供自定义标记指示器。 |
max |
number |
值的最大长度。 |
min |
number |
值的最小长度。 |
railColor |
string |
用于自定义轨道元素背景的 CSS 颜色字符串。 |
resetFallbackValue |
number |
点击重置按钮时恢复的值(由 allowReset 启用) |
separatorType |
string |
定义控件行下方或上方的分隔线是否禁用或占满宽度。默认情况下,分隔线位于下方,但不包含控件图标下方的部分。 |
shiftStep |
number |
按住 SHIFT 键时增加的数值。此偏移值是步长值的倍数。例如,步长值为 5、shiftStep 为 10 时,每次跳变会增加或减少 50。 |
showTooltip |
boolean |
强制显示或隐藏 Tooltip UI。如果 step 设置为特殊字符串值 any,则此设置会被覆盖为 false。 |
step |
number |
增加或减少时数值变化的量。它也是验证依据:值必须是步长的倍数(如果指定了 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,标签将为空;否则,该选项会显示指定的字符串。 |
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 |
接受除另一个 tabs 字段以外的所有字段类型。 |
富文本
用于 RichText 字段的属性字段。
{
"type": "richtext"
}
属性
| 属性 | 类型 | 说明 |
|---|---|---|
default |
string |
首次添加区块时应用的默认值。 |
fallback |
string |
字段值为空时显示的备用值。 |
单位
渲染一个带单位下拉菜单的数字输入框。
{
"type": "unit"
}
属性
| 属性 | 类型 | 说明 |
|---|---|---|
default |
string |
首次添加区块时应用的默认值。 |
fallback |
string |
字段值为空时显示的备用值。 |
disableUnits |
boolean |
如果为 true,则隐藏单位选择字段。 |
isPressEnterToChange |
boolean |
如果为 true,则必须按 ENTER 键才会触发 onChange。启用后,切换焦点时也会触发变更。 |
isResetValueOnUnitChange |
boolean |
如果为 true,且所选单位提供默认值,则切换单位时会设置该值。 |
isUnitSelectTabbable |
boolean |
确定单位选择字段是否可通过 Tab 键聚焦。 |
units |
array |
所见即所得
渲染一个 WYSIWYG 编辑器。
{
"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 嵌入内容、区块标签和由文件提供的页面源。例如,"min": 2 中有一个默认值为 "New item" 的文本字段时,会渲染两行包含该值的内容。
已存储的行和显式设置的重复器 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 报告此问题。请将行内字段保持为平铺结构,或将选项卡移到重复器外。
所见即所得链接
默认情况下,所见即所得链接工具栏会插入在同一标签页打开的链接,不添加 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 不会自动将其转换为链接,点击字段中的现有链接也不会离开编辑器进行跳转。现有内容中已保存的链接属性会保留;系统不会自动迁移这些属性。