动态表单只读字段（`readonly`）

xiaohui

发布于：2026-06-29

主题 整站设置（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。

典型用途

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

常见错误

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

延伸阅读（同一套主题开发文档）

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

提交反馈

模板变量 Markdown 输出