Baklib 文档中心

动态表单只读字段(`readonly`)

主题 整站设置(config/settings_schema.json)与 页面模板(templates/*.liquid 文件末尾的 {% schema %})中的动态表单项,均可使用通用属性 readonly,将字段设为只读。
只读字段在后台表单中不应被编辑;保存时忽略该字段的提交值;在 Liquid 中仍可读取当前值:
  • 整站设置 → site.settings.<id>
  • 页面模板变量 → page.settings.<id>
readonly 与 required、when、queryable 等一样,属于字段对象的通用属性;除 header、paragraph 外,凡带 id 的字段类型均可配置。

写法

readonly 为 布尔值,默认 false。
{
  "id": "fixed_slug",
  "type": "text",
  "label": "固定标识",
  "default": "article-001",
  "readonly": true
}
写法 是否推荐
"readonly": true 推荐
"readonly": false 可省略该键
"readonly": "true" 不推荐(类型为字符串,可能校验失败或行为不稳定)

主题整站设置示例

在 config/settings_schema.json 的某个分组 settings 数组中:
{
  "name": "t:settings_schema.general.name",
  "settings": [
    {
      "id": "site_code",
      "type": "text",
      "label": "站点编码",
      "default": "demo",
      "readonly": true,
      "info": "由初始化脚本写入,请勿在后台修改。"
    }
  ]
}
Liquid 读取:{{ site.settings.site_code }}

页面模板 schema 示例

在 templates/page.liquid 末尾:
{% schema %}
{
  "name": "文章页",
  "settings": [
    {
      "id": "source_url",
      "type": "text",
      "label": "来源链接",
      "default": "",
      "readonly": true
    }
  ]
}
{% endschema %}
Liquid 读取:{{ page.settings.source_url }}

行为说明

保存时

标记为 readonly: true 的字段,在从表单参数提取设置值时会被跳过,即使用户通过浏览器开发者工具改动了输入框并提交,也不会写入数据库。
适用于:由 seeds、迁移、API 或脚本预设,或由业务逻辑派生的字段——仅允许在 Liquid 展示,不允许在后台手改。

Liquid 读取

只读不隐藏变量。只要该页或站点上已有值,page.settings.<id>、site.settings.<id> 照常可用。

与 required、when 的关系

  • required:可与 readonly 同时使用;只读字段通常已有 default 或由初始化写入,一般不必再设 required。
  • when:只读字段也可参与条件显示,表达式引用同 schema 内其他字段的 id,规则与其它字段相同。

与前台用户编辑(user_permitted_attributes)

社区等场景下,页面模板 schema 可声明 user_permitted_attributes(字符串数组),列出前台用户允许编辑的字段 id 白名单。
  • 未列入白名单的字段:前台本就不能改。
  • readonly: true:主要约束后台(Desk)编辑与保存;与前台白名单是不同层面的限制,可按需组合使用。

各 type 在后台表单中的 UI 表现

schema 层面所有带 id 的字段类型都接受 readonly;但各类型在表单里是否视觉上禁用,实现程度不同:
type 后台 UI 是否禁用编辑 说明
text 是 输入框带 readonly
number 是 同 text
richtext 是 编辑器不可编辑、无工具栏
textarea 否(界面仍可输入) 保存时仍会忽略提交值
select、radio、checkbox 否 保存时仍会忽略提交值
image_picker、file_picker、video_picker、dam_picker 否 保存时仍会忽略提交值
其它类型 视实现而定 以保存层「忽略只读字段」为准
若需要在后台界面上也灰掉某类型,而当前 UI 未支持,可向产品反馈;数据安全已由保存逻辑保证。
header、paragraph 无 id,仅作表单内标题或说明段落,不是数据字段,不使用 readonly。

典型用途

  1. 展示系统写入的元数据 如外部同步的来源 URL、外部 ID、初始化时固定的模板版本号。
  2. 防止误改 由 seeds 或迁移脚本写入的标识,允许在设置页查看但不允许手改。
  3. 配合 info 说明用途 在字段说明中注明「只读,由 xxx 流程维护」,减少运营困惑。

常见错误

  • 使用 "readonly": "true" 字符串而非布尔 true。
  • 期望只读后 Liquid 读不到值——只读只限制编辑与保存,不限制读取。
  • 在 textarea 等 UI 未禁用的类型上,误以为界面灰掉才算只读——以保存时是否忽略为准。
  • 给 header / paragraph 加 readonly(无效,二者无 id)。

延伸阅读(同一套主题开发文档)

如需了解字段 type 的完整列表与各类型专属参数,请查阅帮助中心中关于 config/settings_schema.json 主题配置 与 页面模板 {% schema %} 的说明;二者 settings 数组里每个字段对象的结构相同,只是运行时分别对应 site.settings.* 与 page.settings.*。