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.*。