Elementor 自定义块开发

He1955012026-04-10 15:10

Elementor 自定义块开发：add_control 全参数详解

在 WordPress 主题内嵌 Elementor 自定义块（Widget）开发中，add_control() 是核心方法------它决定了后台控制面板的所有交互和配置项。很多开发者只用到基础参数，却忽略了其强大的高级参数（如 condition、options 等），导致控件灵活性不足、适配性差。

本文将以主题路径 wp-content/themes/ele-themes/src/Elementor/Widgets/Services.php 为例，手把手拆解 add_control() 所有常用参数，每个 key 后面直接备注用途，全程实战可复制，新手也能轻松上手，适合收藏备用、直接发表学习。

先明确前提：本文所有示例均适配 Elementor 免费版，基于主题内嵌开发（非独立插件），命名空间、文件路径完全贴合 ele-themes 主题，复制到你的 Services.php 【Services.php是块名称】即可直接使用。

一、核心基础：add_control() 整体结构

先看 add_control() 的通用结构，后续所有参数均围绕这个结构展开，每个部分的作用直接备注在后面：

Plain 复制代码 
$this->add_control(
    'control_id', // 【必选】控件唯一标识（英文，后续前端渲染、样式控制需用到，不可重复）
    [
        'label' => '控件名称', // 【必选】后台显示的控件标题，直观告诉用户这个控件的作用
        'type' => Controls_Manager::TEXT, // 【必选】控件类型（文本、开关、下拉等，决定控件形态）
        // 以下是所有常用高级参数，每个均带备注
        'default' => '默认值', // 【可选】控件的默认显示值，减少用户输入成本
        'label_block' => true, // 【可选】是否让控件占满后台编辑区整行，提升美观度和操作便捷性
        'label_on' => '开启', // 【可选】仅适用于开关（SWITCHER）控件，开启状态显示的文字
        'label_off' => '关闭', // 【可选】仅适用于开关（SWITCHER）控件，关闭状态显示的文字
        'rows' => 4, // 【可选】仅适用于多行文本（TEXTAREA），设置输入框的高度（行数）
        'options' => [], // 【可选】适用于下拉（SELECT）、选择按钮（CHOOSE）等，设置可选选项列表
        'condition' => [], // 【可选】条件显示，根据其他控件的取值，决定当前控件是否显示
        'show_external' => true, // 【可选】仅适用于链接（URL）控件，是否显示"在新窗口打开"的勾选框
        'prevent_empty' => false, // 【可选】仅适用于链接（URL）控件，是否禁止用户留空（true=必须填写）
        'placeholder' => '请输入内容', // 【可选】输入类控件的提示文本，引导用户正确输入
        'description' => '控件说明', // 【可选】控件下方的辅助说明，解释该控件的用途、注意事项
        'min' => 0, // 【可选】仅适用于数字（NUMBER）、滑块（SLIDER），设置最小值
        'max' => 100, // 【可选】仅适用于数字（NUMBER）、滑块（SLIDER），设置最大值
        'step' => 1, // 【可选】仅适用于数字（NUMBER）、滑块（SLIDER），设置每次增减的步长
        'suffix' => 'px', // 【可选】仅适用于数字（NUMBER）、滑块（SLIDER），设置单位（如px、%）
        'multiple' => false, // 【可选】仅适用于SELECT2控件，是否允许多选
    ]
);

二、实战示例：全覆盖所有参数的add_control用法

以下示例均嵌入 Services.php 的 register_controls() 方法中，完全贴合的主题（ele-themes），每个控件都对应服务块的实际需求，参数备注清晰，可直接复制使用。

先给出完整的类结构（确保和你的主题路径、命名空间一致），再逐个展示控件示例：

Plain 复制代码 
<?php
namespace Travel_Agent\Elementor\Widgets; // 【主题专属命名空间】贴合ele-themes主题

use Elementor\Widget_Base;
use Elementor\Controls_Manager;
use Elementor\Repeater;

if (!defined('ABSPATH')) exit; // 禁止直接访问文件

/**
 * 主题服务块（Services）- Elementor自定义控件实战
 */
class Services extends Widget_Base {

    // 小工具基础信息（必写，和add_control无关，仅保证代码可运行）
    public function get_name() {
        return 'agent_services'; // 小工具唯一标识
    }

    public function get_title() {
        return esc_html__('服务展示块', 'travel-agent'); // 后台显示标题
    }

    public function get_icon() {
        return 'eicon-icon-box'; // 小工具图标
    }

    public function get_categories() {
        return ['general', 'travel-agent']; // 小工具分类（主题专属分类更规范）
    }

    // 核心：注册所有控件（重点看这里的add_control示例）
    protected function register_controls() {
        // 第一个控件组：服务基础设置（方便后台分类管理）
        $this->start_controls_section(
            'section_service_basic',
            [
                'label' => esc_html__('基础设置', 'travel-agent'),
                'tab' => Controls_Manager::TAB_CONTENT, // 放在"内容"选项卡
            ]
        );

        // 1. 文本输入框（TEXT）- 服务标题（覆盖label_block、default、placeholder、description）
        $this->add_control(
            'service_main_title', // 【控件唯一标识】后续渲染用，英文无空格
            [
                'label' => esc_html__('服务主标题', 'travel-agent'), // 【控件显示名称】后台直观看到
                'type' => Controls_Manager::TEXT, // 【控件类型】文本输入框
                'default' => esc_html__('我们的核心服务', 'travel-agent'), // 【默认值】用户无需手动输入，直接显示
                'label_block' => true, // 【占满整行】让控件在后台编辑区占满一行，更美观
                'placeholder' => esc_html__('请输入服务主标题（如：我们的核心服务）', 'travel-agent'), // 【提示文本】引导用户输入
                'description' => esc_html__('该标题将显示在服务块顶部，建议控制在15字以内', 'travel-agent'), // 【辅助说明】告诉用户注意事项
            ]
        );

        // 2. 开关控件（SWITCHER）- 是否显示主标题（覆盖label_on、label_off、return_value）
        $this->add_control(
            'show_main_title', // 【控件唯一标识】用于后续condition判断
            [
                'label' => esc_html__('显示主标题', 'travel-agent'), // 【控件显示名称】
                'type' => Controls_Manager::SWITCHER, // 【控件类型】开关控件（yes/no）
                'label_on' => esc_html__('显示', 'travel-agent'), // 【开启状态文字】开关打开时显示"显示"
                'label_off' => esc_html__('隐藏', 'travel-agent'), // 【关闭状态文字】开关关闭时显示"隐藏"
                'return_value' => 'yes', // 【返回值】开启时返回yes，关闭时返回false（可自定义）
                'default' => 'yes', // 【默认值】默认开启显示
            ]
        );

        // 3. 下拉选择器（SELECT）- 服务布局样式（覆盖options、condition）
        $this->add_control(
            'service_layout', // 【控件唯一标识】后续前端渲染布局用
            [
                'label' => esc_html__('服务布局样式', 'travel-agent'), // 【控件显示名称】
                'type' => Controls_Manager::SELECT, // 【控件类型】下拉选择器
                'options' => [ // 【可选选项】下拉列表的选项，key是存储值，value是显示文本
                    'grid' => esc_html__('网格布局（推荐）', 'travel-agent'),
                    'list' => esc_html__('列表布局', 'travel-agent'),
                    'slider' => esc_html__('轮播布局', 'travel-agent'),
                ],
                'default' => 'grid', // 【默认值】默认选择网格布局
                'condition' => [ // 【条件显示】只有当show_main_title为yes时，才显示这个控件
                    'show_main_title' => 'yes'
                ],
                'description' => esc_html__('选择服务块的展示布局，网格布局适配移动端', 'travel-agent'),
            ]
        );

        // 4. 多行文本框（TEXTAREA）- 服务简介（覆盖rows）
        $this->add_control(
            'service_intro', // 【控件唯一标识】后续渲染服务简介用
            [
                'label' => esc_html__('服务简介', 'travel-agent'), // 【控件显示名称】
                'type' => Controls_Manager::TEXTAREA, // 【控件类型】多行文本框
                'rows' => 4, // 【输入框行数】设置文本框高度，4行足够输入简介（可调整）
                'default' => esc_html__('专注提供高品质旅游服务，涵盖酒店预订、景点门票、定制行程等一站式服务，让您的旅行更省心。', 'travel-agent'),
                'label_block' => true,
                'placeholder' => esc_html__('请输入服务简介，简要介绍服务内容', 'travel-agent'),
            ]
        );

        // 5. 链接控件（URL）- 更多服务链接（覆盖show_external、prevent_empty）
        $this->add_control(
            'more_service_link', // 【控件唯一标识】后续渲染链接用
            [
                'label' => esc_html__('更多服务链接', 'travel-agent'), // 【控件显示名称】
                'type' => Controls_Manager::URL, // 【控件类型】链接输入控件
                'show_external' => true, // 【显示新窗口选项】显示"在新窗口打开"的勾选框，用户可选择
                'prevent_empty' => false, // 【允许留空】false=可留空（不强制用户填写），true=必须填写
                'placeholder' => esc_html__('https://www.example.com/services', 'travel-agent'),
                'description' => esc_html__('点击"更多服务"按钮跳转的地址，留空则不显示该按钮', 'travel-agent'),
            ]
        );

        // 6. 数字输入框（NUMBER）- 服务卡片间距（覆盖min、max、step、suffix）
        $this->add_control(
            'card_spacing', // 【控件唯一标识】后续控制样式用
            [
                'label' => esc_html__('服务卡片间距', 'travel-agent'), // 【控件显示名称】
                'type' => Controls_Manager::NUMBER, // 【控件类型】数字输入框
                'default' => 20, // 【默认值】默认间距20px
                'min' => 0, // 【最小值】间距不能小于0px
                'max' => 50, // 【最大值】间距不能大于50px
                'step' => 2, // 【步长】每次增减2px，更精准
                'suffix' => 'px', // 【单位】显示px，告诉用户输入的是像素值
                'condition' => [ // 【条件显示】只有布局为网格时，才显示间距设置
                    'service_layout' => 'grid'
                ],
            ]
        );

        // 7. 选择按钮（CHOOSE）- 文字对齐方式（覆盖options）
        $this->add_control(
            'text_align', // 【控件唯一标识】后续控制文字对齐样式用
            [
                'label' => esc_html__('文字对齐方式', 'travel-agent'), // 【控件显示名称】
                'type' => Controls_Manager::CHOOSE, // 【控件类型】选择按钮（直观易懂）
                'options' => [ // 【可选选项】每个选项带标题和图标，更直观
                    'left' => [
                        'title' => esc_html__('左对齐', 'travel-agent'),
                        'icon' => 'eicon-text-align-left' // Elementor内置图标
                    ],
                    'center' => [
                        'title' => esc_html__('居中对齐', 'travel-agent'),
                        'icon' => 'eicon-text-align-center'
                    ],
                    'right' => [
                        'title' => esc_html__('右对齐', 'travel-agent'),
                        'icon' => 'eicon-text-align-right'
                    ],
                ],
                'default' => 'center', // 【默认值】默认居中对齐
                'label_block' => true,
            ]
        );

        // 8. 多选下拉（SELECT2）- 显示的服务类型（覆盖multiple、options）
        $this->add_control(
            'service_types', // 【控件唯一标识】后续筛选服务用
            [
                'label' => esc_html__('显示的服务类型', 'travel-agent'), // 【控件显示名称】
                'type' => Controls_Manager::SELECT2, // 【控件类型】支持搜索的下拉控件
                'label_block' => true,
                'multiple' => true, // 【允许多选】用户可选择多个服务类型
                'options' => [ // 【可选选项】旅游主题常用服务类型
                    'hotel' => esc_html__('酒店预订', 'travel-agent'),
                    'ticket' => esc_html__('景点门票', 'travel-agent'),
                    'custom' => esc_html__('定制行程', 'travel-agent'),
                    'transfer' => esc_html__('接送服务', 'travel-agent'),
                    'guide' => esc_html__('导游服务', 'travel-agent'),
                ],
                'default' => ['hotel', 'ticket'], // 【默认值】默认显示酒店和门票服务
            ]
        );

        $this->end_controls_section(); // 结束基础设置控件组

        // 第二个控件组：服务项设置（用Repeater，可添加多个服务，顺带演示Repeater中的add_control）
        $this->start_controls_section(
            'section_service_items',
            [
                'label' => esc_html__('服务项设置', 'travel-agent'),
                'tab' => Controls_Manager::TAB_CONTENT,
            ]
        );

        // 重复器（Repeater）- 可添加多个服务项
        $repeater = new Repeater();

        // Repeater中的文本控件（复用前面的参数，重点演示condition）
        $repeater->add_control(
            'item_title', // 【Repeater控件唯一标识】每个服务项的标题
            [
                'label' => esc_html__('服务项标题', 'travel-agent'),
                'type' => Controls_Manager::TEXT,
                'default' => esc_html__('酒店预订', 'travel-agent'),
                'label_block' => true,
                'placeholder' => esc_html__('请输入单个服务项标题', 'travel-agent'),
            ]
        );

        // Repeater中的图标控件（新增，演示基础用法）
        $repeater->add_control(
            'item_icon', // 【Repeater控件唯一标识】每个服务项的图标
            [
                'label' => esc_html__('服务项图标', 'travel-agent'),
                'type' => Controls_Manager::ICONS, // 【控件类型】图标选择器
                'default' => [
                    'value' => 'fas fa-hotel', // 默认图标
                    'library' => 'fa-solid',
                ],
            ]
        );

        // Repeater中的链接控件（覆盖prevent_empty=true）
        $repeater->add_control(
            'item_link', // 【Repeater控件唯一标识】每个服务项的链接
            [
                'label' => esc_html__('服务项链接', 'travel-agent'),
                'type' => Controls_Manager::URL,
                'show_external' => true,
                'prevent_empty' => true, // 【禁止留空】每个服务项必须填写链接
                'placeholder' => esc_html__('https://www.example.com/hotel', 'travel-agent'),
                'condition' => [ // 【条件显示】只有服务类型包含酒店时，才显示该链接控件
                    'service_types' => 'hotel'
                ],
            ]
        );

        // 将Repeater添加到主控件中
        $this->add_control(
            'service_items', // 【Repeater唯一标识】后续渲染所有服务项用
            [
                'label' => esc_html__('服务项列表', 'travel-agent'),
                'type' => Controls_Manager::REPEATER,
                'fields' => $repeater->get_controls(), // 引入Repeater中的所有控件
                'default' => [ // 默认添加2个服务项
                    [
                        'item_title' => esc_html__('酒店预订', 'travel-agent'),
                        'item_icon' => ['value' => 'fas fa-hotel', 'library' => 'fa-solid'],
                    ],
                    [
                        'item_title' => esc_html__('景点门票', 'travel-agent'),
                        'item_icon' => ['value' => 'fas fa-ticket-alt', 'library' => 'fa-solid'],
                    ],
                ],
                'title_field' => '{{{ item_title }}}', // Repeater列表中显示的标题（用服务项标题）
            ]
        );

        $this->end_controls_section(); // 结束服务项控件组
    }

    // 前端渲染（简化版，仅演示如何调用控件值，不影响add_control讲解）
    protected function render() {
        $settings = $this->get_settings_for_display(); // 获取所有控件的值
        // 渲染逻辑（可根据自己的需求扩展）
        echo '';
        if ($settings['show_main_title'] === 'yes') {
            echo '' . $settings['service_main_title'] . '';
        }
        echo '';
    }

    // 编辑器预览（可选，为空则使用前端渲染逻辑）
    protected function content_template() {}
}
?>

三、重点参数单独拆解（新手必看）

上面的示例已经覆盖了所有你要求的参数，这里单独把核心参数拎出来，再详细拆解一遍，方便快速查阅，发表时可作为"重点笔记"部分：

1. condition（条件显示，最常用高级参数）

作用：根据其他控件的取值，动态显示/隐藏当前控件，避免后台控件过多、杂乱。

核心逻辑：'condition' => ['其他控件id' => '目标值']，支持多条件（用数组嵌套），示例：

Plain 复制代码 
'condition' => [
    'show_main_title' => 'yes', // 主条件：显示主标题为开启
    'service_layout' => ['grid', 'list'] // 多值条件：布局为网格或列表
]

2. options（选项列表，下拉/选择按钮必备）

作用：定义下拉选择器（SELECT）、选择按钮（CHOOSE）等控件的可选内容，key是存储到数据库的值，value是后台显示的文本，建议key用英文，value用中文（适配多语言）。

3. label_block（提升体验，必加参数）

作用：让控件在后台编辑区占满整行，默认情况下，控件标签和输入框在同一行，标签较长时会挤压输入框，设置为true后，标签在上、输入框在下，更美观、更好操作。

4. label_on / label_off（开关控件专属）

作用：自定义开关控件的显示文字，默认是"On/Off"，改成中文"显示/隐藏"更符合中文用户习惯，提升后台易用性。

5. rows（多行文本专属）

作用：控制多行文本框（TEXTAREA）的高度，根据输入内容的多少设置合适的行数（一般3-5行），避免文本框过高或过低，提升用户输入体验。

6. show_external（链接控件专属）

作用：显示"在新窗口打开"的勾选框，用户可自主选择链接是否在新窗口打开，无需开发者硬编码，更灵活。

7. prevent_empty（链接控件专属）

作用：控制链接是否允许留空，true表示必须填写，false表示可以留空，根据实际需求设置（如必填链接就设为true）。

四、实战注意事项（发表时补充，提升文章价值）

  1. 控件id必须唯一：每个add_control()的第一个参数（control_id），在整个类中不能重复，否则会覆盖之前的控件，建议用"前缀+功能"命名（如service_main_title）。

  2. 命名空间适配主题：本文示例的命名空间Travel_Agent\Elementor\Widgets，需和你主题的命名空间一致，若主题无自定义命名空间，可删除命名空间，直接使用全局类。

  3. 参数按需使用：不是所有参数都要加，比如文本控件不需要label_on，开关控件不需要rows，根据控件类型和实际需求选择参数。

  4. 多语言适配：所有显示文本（label、default、description等），建议用esc_html__()包裹，方便后续做主题多语言翻译。

  5. 测试验证：添加完控件后，进入Elementor编辑器，拖拽该服务块，检查每个控件是否正常显示、参数是否生效，避免语法错误。

五、总结

Elementor 的 add_control() 看似简单，实则包含很多实用的高级参数，合理运用这些参数（尤其是condition、options），能让你的自定义块更灵活、更易用，适配更多场景。

本文所有示例均基于 ele-themes 主题，路径、命名空间完全匹配，复制到 src/Elementor/Widgets/Services.php 即可直接使用，新手也能快速上手。

如果需要扩展更多控件（如颜色选择、图片上传、富文本等），可在评论区留言，后续将补充更多实战示例。

相关推荐
syjy213 小时前
Polylang Pro WordPress多语言插件使用教程（含下载）
wordpress·wordpress插件
WordPress学习笔记1 天前
镌刻中式美学的高端WordPress主题
大数据·人工智能·wordpress
北漂的老猿1 天前
SEO&网络营销服务WordPress主题
wordpress
WordPress学习笔记1 天前
WordPress多语言外贸独立站
wordpress·wordpress多语言·wordpress独立站
北漂的老猿1 天前
响应式金融企业网站WordPress主题
金融·wordpress
syjy22 天前
WooCommerce Variation Swatches Pro WordPress插件使用教程（含下载）
wordpress·wordpress插件
WordPress学习笔记2 天前
模板业(mobanye)各行各业的网站模板
wordpress
syjy23 天前
（含下载）All in One SEO Pack Pro WordPress插件使用教程
wordpress·wordpress插件
syjy24 天前
WP Smush Pro WordPress插件使用教程(含下载）
wordpress·wordpress插件
代龙涛4 天前
WordPress archive.php 分类与归档页面开发指南
开发语言·后端·php·wordpress
热门推荐
01GitHub 镜像站点02要裂开了！ChatGPT要手机号验证了？注册Codex要求验证电话号码怎么办？2026年登陆Codex要手机号验证的解决办法03Codex 接入 DeepSeek API 完整配置文档04裂开！ChatGPT 居然开始要手机号验证，附详细解决方法05【AI】2026 年具身智能模型和世界模型总结062026年4月AI大事件深度解读：大模型竞争进入“深水区“07实测可用｜小米 MiMo 百万亿 Token 免费领，开发者速冲08近期有什么ai的新消息，新动态？ 2026.4月092026年AI编程工具终极横评：Cursor vs Claude Code vs Copilot10在Windows 11上安装Docker的踩坑记录