acf-local-json（ACF 本地 JSON）

ACF Local JSON Builder

Generate complete ACF (Advanced Custom Fields) Local JSON configurations from images, designs, or HTML structures for WordPress development.

Core Workflow

1. Analyze Input: Examine the provided image, design, or HTML structure
2. Identify Components: Detect repeating patterns, content sections, and field relationships
3. Map Field Types: Determine appropriate ACF field types for each component
4. Generate JSON: Create the complete Local JSON configuration
5. Validate Structure: Ensure proper nesting, keys, and field relationships

Field Type Detection Guidelines

From Visual Analysis

• Text inputs/headings → text, textarea, or wysiwyg
• Images → image (consider gallery for multiple)
• Repeating cards/sections → repeater or flexible_content
• Toggle states → true_false or button_group
• Dropdowns/select boxes → select or radio
• Date displays → date_picker or date_time_picker
• Links/buttons → link or url
• Color variations → color_picker
• File downloads → file
• Numbered lists → number or range
• Tab interfaces → tab field type
• Accordions → flexible_content with layouts

From HTML Structure

<!-- Text Field -->
<h1>, <h2>, <p> → text/textarea/wysiwyg

<!-- Image Field -->
<img> → image field
<picture>, <source> → image with return format 'array'

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

<!-- Flexible Content Pattern -->
Secciones variadas (hero, features, cta) → flexible_content

<!-- Link Field -->
<a href=""> → link field

<!-- True/False -->
<input type="checkbox"> → true_false

JSON Structure Template

Every ACF Local JSON file follows this structure:

{
  "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": ""
}

Field Structure Patterns

Basic Field

{
  "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 Field

{
  "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": [...]
    }
  }
}

Image Field

{
  "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": ""
}

Key Generation Rules

1. Group Keys: group_ + descriptive_snake_case + random_hash

- Example: group_homepage_hero_5f8a2b

1. Field Keys: field_ + descriptive_snake_case + random_hash

- Example: field_hero_title_9c3d1e

1. Layout Keys: layout_ + layout_name + random_hash

- Example: layout_hero_section_4b7e9a

1. Uniqueness: Every key must be globally unique across all ACF installations

Location Rules

Common location patterns:

"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"
    }
  ]
]

Best Practices

1. Semantic Naming: Use clear, descriptive names that reflect content purpose
2. Proper Nesting: Maintain correct parent-child relationships in repeaters/flex
3. Return Formats: Choose appropriate return formats (ID, array, url for images)
4. Instructions: Add helpful instructions for content editors
5. Defaults: Set sensible default values where appropriate
6. Validation: Include min/max constraints where relevant
7. Layout Types: Use block, table, or row layouts appropriately
8. Clone Fields: Reference the clone fields documentation for reusable field sets

Output Format

Generate the complete JSON file ready to save as:

acf-json/group_[name].json

The file should be valid JSON and immediately usable in WordPress ACF Pro's Local JSON feature.

Advanced Features

For complex patterns like:

• Clone fields: See references/clone-fields.md
• Bidirectional relationships: See references/relationships.md
• Custom field types: See references/custom-types.md
• Conditional logic: See references/conditional-logic.md

Example Workflow

User provides: Screenshot of a hero section with title, subtitle, CTA button, and background image

Analysis:

1. Hero section = Field Group
2. Title = text field
3. Subtitle = textarea field
4. CTA = link field (text + URL)
5. Background = image field

Output: Complete JSON with all fields properly structured and nested