acf-local-json

ACF 本地 JSON 构建器

根据图片、设计稿或 HTML 结构生成完整的 ACF（Advanced Custom Fields）本地 JSON 配置，用于 WordPress 开发。

核心工作流

1. 分析输入：检查提供的图片、设计稿或 HTML 结构
2. 识别组件：检测重复模式、内容区块和字段关系
3. 映射字段类型：为每个组件确定合适的 ACF 字段类型
4. 生成 JSON：创建完整的本地 JSON 配置
5. 验证结构：确保嵌套、键和字段关系正确

字段类型检测指南

根据视觉分析

• 文本输入框/标题 → text、textarea 或 wysiwyg
• 图片 → image（多张图片可考虑使用 gallery）
• 重复卡片/区块 → repeater 或 flexible_content
• 切换状态 → true_false 或 button_group
• 下拉菜单/选择框 → select 或 radio
• 日期显示 → date_picker 或 date_time_picker
• 链接/按钮 → link 或 url
• 颜色变化 → color_picker
• 文件下载 → file
• 编号列表 → number 或 range
• 标签页界面 → tab 字段类型
• 折叠面板 → 使用包含布局的 flexible_content

根据 HTML 结构

<h1>, <h2>, <p> → text/textarea/wysiwyg


<img> → image field
<picture>, <source> → image with return format 'array'


<div class="card"> (múltiples) → repeater
<ul><li> (dinámicos) → repeater


Secciones variadas (hero, features, cta) → flexible_content


<a href=""> → link field


<input type="checkbox"> → true_false

JSON 结构模板

每个 ACF 本地 JSON 文件都遵循以下结构：

{
  "key": "group_unique_identifier",
  "title": "Field Group Name",
  "fields": [...],
  "location": [...],
  "menu_order": 0,
  "position": "normal",
  "style": "default",
  "label_placement": "top",
  "instruction_placement": "label",
  "hide_on_screen": "",
  "active": true,
  "description": ""
}

字段结构模式

基本字段

{
  "key": "field_unique_key",
  "label": "Field Label",
  "name": "field_name",
  "type": "text",
  "instructions": "",
  "required": 0,
  "conditional_logic": 0,
  "wrapper": {
    "width": "",
    "class": "",
    "id": ""
  },
  "default_value": "",
  "placeholder": "",
  "prepend": "",
  "append": "",
  "maxlength": ""
}

Repeater 字段

{
  "key": "field_repeater_key",
  "label": "Items",
  "name": "items",
  "type": "repeater",
  "instructions": "",
  "required": 0,
  "layout": "block",
  "button_label": "Add Item",
  "min": 0,
  "max": 0,
  "sub_fields": [
    {
      "key": "field_subfield_key",
      "label": "Title",
      "name": "title",
      "type": "text",
      "parent": "field_repeater_key"
    }
  ]
}

Flexible Content

{
  "key": "field_flexible_key",
  "label": "Page Builder",
  "name": "page_builder",
  "type": "flexible_content",
  "instructions": "",
  "button_label": "Add Section",
  "min": "",
  "max": "",
  "layouts": {
    "layout_hero": {
      "key": "layout_hero_key",
      "name": "hero",
      "label": "Hero Section",
      "display": "block",
      "sub_fields": [...]
    },
    "layout_features": {
      "key": "layout_features_key",
      "name": "features",
      "label": "Features Section",
      "display": "block",
      "sub_fields": [...]
    }
  }
}

图片字段

{
  "key": "field_image_key",
  "label": "Image",
  "name": "image",
  "type": "image",
  "return_format": "array",
  "preview_size": "medium",
  "library": "all",
  "min_width": "",
  "min_height": "",
  "min_size": "",
  "max_width": "",
  "max_height": "",
  "max_size": "",
  "mime_types": ""
}

键生成规则

1. 分组键：group_ + 描述性蛇形命名 + 随机哈希

   • 示例：group_homepage_hero_5f8a2b

2. 字段键：field_ + 描述性蛇形命名 + 随机哈希

   • 示例：field_hero_title_9c3d1e

3. 布局键：layout_ + layout_name + 随机哈希

   • 示例：layout_hero_section_4b7e9a

4. 唯一性：每个键在所有 ACF 安装中都必须全局唯一

位置规则

常见的位置模式：

"location": [
  [
    {
      "param": "post_type",
      "operator": "==",
      "value": "page"
    }
  ]
]

"location": [
  [
    {
      "param": "page_template",
      "operator": "==",
      "value": "template-homepage.php"
    }
  ]
]

"location": [
  [
    {
      "param": "post_type",
      "operator": "==",
      "value": "post"
    },
    {
      "param": "post_category",
      "operator": "==",
      "value": "category:news"
    }
  ]
]

最佳实践

1. 语义化命名：使用清晰且描述性强的名称，体现内容用途
2. 正确嵌套：在 repeater/flex 中保持正确的父子关系
3. 返回格式：选择合适的返回格式（图片可选 ID、array、url）
4. 说明：为内容编辑者添加实用说明
5. 默认值：在适当情况下设置合理的默认值
6. 验证：在相关情况下添加最小值/最大值限制
7. 布局类型：根据需要使用 block、table 或 row 布局
8. Clone 字段：参考 Clone 字段文档，了解可复用字段集

输出格式

生成完整的 JSON 文件，可直接保存为：

acf-json/group_[name].json

该文件应为有效 JSON，可立即用于 WordPress ACF Pro 的本地 JSON 功能。

高级功能

对于以下复杂模式：

• Clone 字段：参见 references/clone-fields.md
• 双向关系：参见 references/relationships.md
• 自定义字段类型：参见 references/custom-types.md
• 条件逻辑：参见 references/conditional-logic.md

示例工作流

用户提供：一个 Hero 区块的屏幕截图，包含标题、副标题、CTA 按钮和背景图片

分析：

1. Hero 区块 = 字段组
2. 标题 = text 字段
3. 副标题 = textarea 字段
4. CTA = link 字段（文本 + URL）
5. 背景 = image 字段

输出：包含所有字段且结构和嵌套正确的完整 JSON