跳转到正文

字段类型

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。详情请参阅可移植媒体引用。

选择器请求、重试和图标子集请参阅图标加载。

属性

渲染数据属性输入控件。

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 控件,并假定时间格式为 MM-DD-YYYY(而非默认格式 DD-MM-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,则强制数值处于控件的最小值和最大值范围内。如果为 false,则允许空字符串作为有效值。
shiftStep number 按住 SHIFT 键时增加的数值。此偏移值是步长值的倍数。例如,步长值为 5、shiftStep 为 10 时,每次跳变会增加或减少 50。
step number 增加或减少时数值变化的量。它也是验证依据:值必须是步长的倍数(如果指定了 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 渲染步进刻度的可视化表示。可通过数组提供自定义标记指示器。
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。

选择框

渲染一个支持单选或多选的选择输入框。

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,标签将为空;否则,该选项会显示指定的字符串。
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 接受除另一个 tabs 字段以外的所有字段类型。

富文本

用于 RichText 字段的属性字段。

JSON
{
  "type": "richtext"
}

属性

属性 类型 说明
default string 首次添加区块时应用的默认值。
fallback string 字段值为空时显示的备用值。

单位

渲染一个带单位下拉菜单的数字输入框。

JSON
{
  "type": "unit"
}

属性

属性 类型 说明
default string 首次添加区块时应用的默认值。
fallback string 字段值为空时显示的备用值。
disableUnits boolean 如果为 true,则隐藏单位选择字段。
isPressEnterToChange boolean 如果为 true,则必须按 ENTER 键才会触发 onChange。启用后,切换焦点时也会触发变更。
isResetValueOnUnitChange boolean 如果为 true,且所选单位提供默认值,则切换单位时会设置该值。
isUnitSelectTabbable boolean 确定单位选择字段是否可通过 Tab 键聚焦。
units array

所见即所得

渲染一个 WYSIWYG 编辑器。

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 嵌入内容、区块标签和由文件提供的页面源。例如,"min": 2 中有一个默认值为 "New item" 的文本字段时,会渲染两行包含该值的内容。

已存储的行和显式设置的重复器 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 报告此问题。请将行内字段保持为平铺结构,或将选项卡移到重复器外。

默认情况下,所见即所得链接工具栏会插入在同一标签页打开的链接,不添加 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 不会自动将其转换为链接,点击字段中的现有链接也不会离开编辑器进行跳转。现有内容中已保存的链接属性会保留;系统不会自动迁移这些属性。