elementor-themes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

1. Theme Builder Locations

1. Theme Builder 位置

Registering Locations

注册位置

php

function theme_prefix_register_elementor_locations( $elementor_theme_manager ) {
    $elementor_theme_manager->register_all_core_location();
}
add_action( 'elementor/theme/register_locations', 'theme_prefix_register_elementor_locations' );

php

$elementor_theme_manager->register_location( 'header' );
$elementor_theme_manager->register_location( 'footer' );
$elementor_theme_manager->register_location( 'main-sidebar', [
    'label' => esc_html__( 'Main Sidebar', 'theme-name' ),
    'multiple' => true,        // allow multiple templates (default: false)
    'edit_in_content' => false, // edit in content area (default: true)
] );

一次性注册所有核心位置：

php

function theme_prefix_register_elementor_locations( $elementor_theme_manager ) {
    $elementor_theme_manager->register_all_core_location();
}
add_action( 'elementor/theme/register_locations', 'theme_prefix_register_elementor_locations' );

注册特定位置或自定义位置：

php

$elementor_theme_manager->register_location( 'header' );
$elementor_theme_manager->register_location( 'footer' );
$elementor_theme_manager->register_location( 'main-sidebar', [
    'label' => esc_html__( 'Main Sidebar', 'theme-name' ),
    'multiple' => true,        // 允许多个模板（默认：false）
    'edit_in_content' => false, // 在内容区域编辑（默认：true）
] );

Location Types

位置类型

Location	Replaces
`header`	header.php
`footer`	footer.php
`single`	singular.php, single.php, page.php, attachment.php, 404.php
`archive`	archive.php, taxonomy.php, author.php, date.php, search.php

位置	替代文件
`header`	header.php
`footer`	footer.php
`single`	singular.php, single.php, page.php, attachment.php, 404.php
`archive`	archive.php, taxonomy.php, author.php, date.php, search.php

Displaying Locations with Fallback

带降级方案的位置展示

php

<?php
if ( ! function_exists( 'elementor_theme_do_location' ) || ! elementor_theme_do_location( 'archive' ) ) {
    get_template_part( 'template-parts/archive' );
}
?>

elementor_theme_do_location()

returns

true

if a template was displayed,

false

otherwise.

php

<?php
if ( ! function_exists( 'elementor_theme_do_location' ) || ! elementor_theme_do_location( 'archive' ) ) {
    get_template_part( 'template-parts/archive' );
}
?>

elementor_theme_do_location()

若成功展示模板则返回

true

，否则返回

false

。

Migration: Functions Method

迁移：函数法

Use

elementor_theme_do_location()

with fallback in header.php, footer.php, single.php, archive.php:

php

<!-- header.php -->
<!doctype html>
<html <?php language_attributes(); ?>>
<head>
    <meta charset="<?php bloginfo( 'charset' ); ?>">
    <?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<?php
if ( ! function_exists( 'elementor_theme_do_location' ) || ! elementor_theme_do_location( 'header' ) ) {
    get_template_part( 'template-parts/header' );
}
?>

在header.php、footer.php、single.php、archive.php中结合降级方案使用

elementor_theme_do_location()

：

php

<!-- header.php -->
<!doctype html>
<html <?php language_attributes(); ?>>
<head>
    <meta charset="<?php bloginfo( 'charset' ); ?>">
    <?php wp_head(); ?>
</head>
<body <?php body_class(); ?>>
<?php
if ( ! function_exists( 'elementor_theme_do_location' ) || ! elementor_theme_do_location( 'header' ) ) {
    get_template_part( 'template-parts/header' );
}
?>

Migration: Hooks Method

迁移：钩子法

hook

and

remove_hooks

parameters to auto-replace theme output:

php

$elementor_theme_manager->register_location( 'header', [
    'hook' => 'theme_prefix_header',
    'remove_hooks' => [ 'theme_prefix_print_elementor_header' ],
] );

通过

hook

和

remove_hooks

参数注册位置，自动替换主题输出：

php

$elementor_theme_manager->register_location( 'header', [
    'hook' => 'theme_prefix_header',
    'remove_hooks' => [ 'theme_prefix_print_elementor_header' ],
] );

2. Theme Conditions

2. 主题条件

Class Structure

类结构

Extend

\ElementorPro\Modules\ThemeBuilder\Conditions\Condition_Base

Required methods:

Method	Returns	Purpose
`get_type()`	string	Condition group: `general` , `singular` , `archive`
`get_name()`	string	Unique condition identifier
`get_label()`	string	Display label
`check( $args )`	bool	Evaluate if condition matches
`get_all_label()`	string	Label for "All" option (parent conditions only)
`register_sub_conditions()`	void	Register child conditions

继承

\ElementorPro\Modules\ThemeBuilder\Conditions\Condition_Base

。

必填方法：

方法	返回值	用途
`get_type()`	string	条件组： `general` 、 `singular` 、 `archive`
`get_name()`	string	唯一条件标识符
`get_label()`	string	展示标签
`check( $args )`	bool	评估条件是否匹配
`get_all_label()`	string	“全部”选项的标签（仅父条件需要）
`register_sub_conditions()`	void	注册子条件

Registration

注册

php

function register_new_theme_conditions( $conditions_manager ) {
    require_once( __DIR__ . '/theme-conditions/my-condition.php' );
    $conditions_manager->get_condition( 'general' )->register_sub_condition( new \My_Condition() );
}
add_action( 'elementor/theme/register_conditions', 'register_new_theme_conditions' );

php

function register_new_theme_conditions( $conditions_manager ) {
    require_once( __DIR__ . '/theme-conditions/my-condition.php' );
    $conditions_manager->get_condition( 'general' )->register_sub_condition( new \My_Condition() );
}
add_action( 'elementor/theme/register_conditions', 'register_new_theme_conditions' );

Condition Groups

条件组

ID	Label	Description
`general`	General	Entire site conditions
`archive`	Archives	Archive page conditions
`singular`	Singular	Single page/post conditions

ID	标签	描述
`general`	通用	全站条件
`archive`	归档页	归档页面条件
`singular`	单页	单篇页面/文章条件

Simple Example: 404 / Front Page

简单示例：404 / 首页

php

class Front_Page_Condition extends \ElementorPro\Modules\ThemeBuilder\Conditions\Condition_Base {
    public static function get_type(): string { return 'general'; }
    public function get_name(): string { return 'front_page'; }
    public function get_label(): string { return esc_html__( 'Front Page', 'textdomain' ); }
    public function check( $args ): bool { return is_front_page(); }
}

class Not_Found_Condition extends \ElementorPro\Modules\ThemeBuilder\Conditions\Condition_Base {
    public static function get_type(): string { return 'general'; }
    public function get_name(): string { return 'not_found_404'; }
    public function get_label(): string { return esc_html__( '404 Page', 'textdomain' ); }
    public function check( $args ): bool { return is_404(); }
}

php

class Front_Page_Condition extends \ElementorPro\Modules\ThemeBuilder\Conditions\Condition_Base {
    public static function get_type(): string { return 'general'; }
    public function get_name(): string { return 'front_page'; }
    public function get_label(): string { return esc_html__( 'Front Page', 'textdomain' ); }
    public function check( $args ): bool { return is_front_page(); }
}

class Not_Found_Condition extends \ElementorPro\Modules\ThemeBuilder\Conditions\Condition_Base {
    public static function get_type(): string { return 'general'; }
    public function get_name(): string { return 'not_found_404'; }
    public function get_label(): string { return esc_html__( '404 Page', 'textdomain' ); }
    public function check( $args ): bool { return is_404(); }
}

Advanced Example: Parent with Sub-Conditions

高级示例：带子条件的父条件

php

class Logged_In_User_Condition extends \ElementorPro\Modules\ThemeBuilder\Conditions\Condition_Base {
    public static function get_type(): string { return 'general'; }
    public function get_name(): string { return 'logged_in_user'; }
    public function get_label(): string { return esc_html__( 'Logged-in User', 'textdomain' ); }
    public function get_all_label(): string { return esc_html__( 'Any user role', 'textdomain' ); }

    public function register_sub_conditions(): void {
        global $wp_roles;
        if ( ! isset( $wp_roles ) ) { $wp_roles = new \WP_Roles(); }
        foreach ( $wp_roles->get_names() as $role ) {
            $this->register_sub_condition( new \User_Role_Condition( $role ) );
        }
    }

    public function check( $args ): bool { return is_user_logged_in(); }
}

class User_Role_Condition extends \ElementorPro\Modules\ThemeBuilder\Conditions\Condition_Base {
    private $user_role;
    public function __construct( $user_role ) { parent::__construct(); $this->user_role = $user_role; }
    public static function get_type(): string { return 'logged_in_user'; }
    public function get_name(): string { return strtolower( $this->user_role . '_role' ); }
    public function get_label(): string { return sprintf( esc_html__( '%s role', 'textdomain' ), $this->user_role ); }
    public function check( $args ): bool {
        $current_user = wp_get_current_user();
        return in_array( $this->user_role, (array) $current_user->roles );
    }
}

php

class Logged_In_User_Condition extends \ElementorPro\Modules\ThemeBuilder\Conditions\Condition_Base {
    public static function get_type(): string { return 'general'; }
    public function get_name(): string { return 'logged_in_user'; }
    public function get_label(): string { return esc_html__( 'Logged-in User', 'textdomain' ); }
    public function get_all_label(): string { return esc_html__( 'Any user role', 'textdomain' ); }

    public function register_sub_conditions(): void {
        global $wp_roles;
        if ( ! isset( $wp_roles ) ) { $wp_roles = new \WP_Roles(); }
        foreach ( $wp_roles->get_names() as $role ) {
            $this->register_sub_condition( new \User_Role_Condition( $role ) );
        }
    }

    public function check( $args ): bool { return is_user_logged_in(); }
}

class User_Role_Condition extends \ElementorPro\Modules\ThemeBuilder\Conditions\Condition_Base {
    private $user_role;
    public function __construct( $user_role ) { parent::__construct(); $this->user_role = $user_role; }
    public static function get_type(): string { return 'logged_in_user'; }
    public function get_name(): string { return strtolower( $this->user_role . '_role' ); }
    public function get_label(): string { return sprintf( esc_html__( '%s role', 'textdomain' ), $this->user_role ); }
    public function check( $args ): bool {
        $current_user = wp_get_current_user();
        return in_array( $this->user_role, (array) $current_user->roles );
    }
}

3. Dynamic Tags

3. 动态标签

Class Structure

类结构

Extend

\Elementor\Core\DynamicTags\Tag

Required methods:

Method	Returns	Purpose
`get_name()`	string	Unique tag identifier
`get_title()`	string	Display title
`get_group()`	array	Groups this tag belongs to
`get_categories()`	array	Data type categories
`render()`	void	Output the dynamic value (echo)
`register_controls()`	void	Optional: add tag settings

继承

\Elementor\Core\DynamicTags\Tag

。

必填方法：

方法	返回值	用途
`get_name()`	string	唯一标签标识符
`get_title()`	string	展示标题
`get_group()`	array	标签所属分组
`get_categories()`	array	数据类型分类
`render()`	void	输出动态值（使用echo）
`register_controls()`	void	可选：添加标签设置

Dynamic Tag Categories

动态标签分类

Constant	Value	Use For
`Module::NUMBER_CATEGORY`	`number`	Numeric values
`Module::TEXT_CATEGORY`	`text`	Text strings
`Module::URL_CATEGORY`	`url`	URLs
`Module::COLOR_CATEGORY`	`color`	Color values
`Module::IMAGE_CATEGORY`	`image`	Image data
`Module::MEDIA_CATEGORY`	`media`	Media files
`Module::GALLERY_CATEGORY`	`gallery`	Image galleries
`Module::POST_META_CATEGORY`	`post_meta`	Post meta fields

Full constant path:

\Elementor\Modules\DynamicTags\Module::CATEGORY_NAME

常量	值	适用场景
`Module::NUMBER_CATEGORY`	`number`	数值类型
`Module::TEXT_CATEGORY`	`text`	文本字符串
`Module::URL_CATEGORY`	`url`	网址
`Module::COLOR_CATEGORY`	`color`	颜色值
`Module::IMAGE_CATEGORY`	`image`	图片数据
`Module::MEDIA_CATEGORY`	`media`	媒体文件
`Module::GALLERY_CATEGORY`	`gallery`	图片相册
`Module::POST_META_CATEGORY`	`post_meta`	文章元字段

完整常量路径：

\Elementor\Modules\DynamicTags\Module::CATEGORY_NAME

。

Registration

注册

php

function register_dynamic_tags( $dynamic_tags_manager ) {
    require_once( __DIR__ . '/dynamic-tags/my-tag.php' );
    $dynamic_tags_manager->register( new \My_Dynamic_Tag() );
}
add_action( 'elementor/dynamic_tags/register', 'register_dynamic_tags' );

php

function register_dynamic_tags( $dynamic_tags_manager ) {
    require_once( __DIR__ . '/dynamic-tags/my-tag.php' );
    $dynamic_tags_manager->register( new \My_Dynamic_Tag() );
}
add_action( 'elementor/dynamic_tags/register', 'register_dynamic_tags' );

Register Custom Group

注册自定义分组

php

function register_custom_dynamic_tag_group( $dynamic_tags_manager ) {
    $dynamic_tags_manager->register_group( 'my-group', [
        'title' => esc_html__( 'My Group', 'textdomain' ),
    ] );
}
add_action( 'elementor/dynamic_tags/register', 'register_custom_dynamic_tag_group' );

php

function register_custom_dynamic_tag_group( $dynamic_tags_manager ) {
    $dynamic_tags_manager->register_group( 'my-group', [
        'title' => esc_html__( 'My Group', 'textdomain' ),
    ] );
}
add_action( 'elementor/dynamic_tags/register', 'register_custom_dynamic_tag_group' );

Controls in Dynamic Tags

动态标签中的控件

Use

$this->add_control()

register_controls()

and

$this->get_settings( 'key' )

render()

在

register_controls()

中使用

$this->add_control()

，在

render()

中使用

$this->get_settings( 'key' )

。

Code Examples

代码示例

See resources/dynamic-tags.md for complete examples: Simple tag (Random Number), Advanced tag with controls (ACF Average), Complex tag with SELECT control (Server Variables), and unregistering tags.

完整示例请查看 resources/dynamic-tags.md：简单标签（随机数）、带控件的高级标签（ACF平均值）、带选择控件的复杂标签（服务器变量）以及注销标签。

4. Finder

Class Structure

类结构

Extend

\Elementor\Core\Common\Modules\Finder\Base_Category

Method	Returns	Purpose
`get_id()`	string	Unique category identifier
`get_title()`	string	Display title
`get_category_items( array $options = [] )`	array	Items in this category
`is_dynamic()`	bool	If true, items loaded via AJAX on search

继承

\Elementor\Core\Common\Modules\Finder\Base_Category

。

方法	返回值	用途
`get_id()`	string	唯一分类标识符
`get_title()`	string	展示标题
`get_category_items( array $options = [] )`	array	该分类下的项目
`is_dynamic()`	bool	若为true，项目将在搜索时通过AJAX加载

Item Properties

项目属性

Property	Type	Required	Description
`title`	string	Yes	Displayed to user
`icon`	string	No	Icon before title
`url`	string	Yes	Link URL
`keywords`	array	No	Search keywords

属性	类型	必填	描述
`title`	string	是	向用户展示的文本
`icon`	string	否	标题前的图标
`url`	string	是	链接地址
`keywords`	array	否	搜索关键词

Registration

注册

php

function register_finder_category( $finder_categories_manager ) {
    require_once( __DIR__ . '/finder/my-category.php' );
    $finder_categories_manager->register( new \My_Finder_Category() );
}
add_action( 'elementor/finder/register', 'register_finder_category' );

php

function register_finder_category( $finder_categories_manager ) {
    require_once( __DIR__ . '/finder/my-category.php' );
    $finder_categories_manager->register( new \My_Finder_Category() );
}
add_action( 'elementor/finder/register', 'register_finder_category' );

Default Categories

默认分类

ID	Description
`create`	Create posts, pages, templates
`edit`	Edit posts, pages, templates
`general`	General Elementor links
`settings`	Elementor settings pages
`tools`	Elementor tools
`site`	Site links

ID	描述
`create`	创建文章、页面、模板
`edit`	编辑文章、页面、模板
`general`	Elementor通用链接
`settings`	Elementor设置页面
`tools`	Elementor工具
`site`	站点链接

Add Items to Existing Category

向现有分类添加项目

php

function add_finder_items( array $categories ) {
    $categories['create']['items']['theme-template'] = [
        'title' => esc_html__( 'Add New Theme Template', 'textdomain' ),
        'icon' => 'plus-circle-o',
        'url' => admin_url( 'edit.php?post_type=elementor_library#add_new' ),
        'keywords' => [ 'template', 'theme', 'new', 'create' ],
    ];
    return $categories;
}
add_filter( 'elementor/finder/categories', 'add_finder_items' );

php

function add_finder_items( array $categories ) {
    $categories['create']['items']['theme-template'] = [
        'title' => esc_html__( 'Add New Theme Template', 'textdomain' ),
        'icon' => 'plus-circle-o',
        'url' => admin_url( 'edit.php?post_type=elementor_library#add_new' ),
        'keywords' => [ 'template', 'theme', 'new', 'create' ],
    ];
    return $categories;
}
add_filter( 'elementor/finder/categories', 'add_finder_items' );

Remove Categories / Items

删除分类/项目

php

// Remove entire category
function remove_finder_category( array $categories ) {
    unset( $categories['edit'] );
    return $categories;
}
add_filter( 'elementor/finder/categories', 'remove_finder_category' );

// Remove specific item
function remove_finder_item( array $categories ) {
    unset( $categories['create']['items']['post'] );
    return $categories;
}
add_filter( 'elementor/finder/categories', 'remove_finder_item' );

php

// 删除整个分类
function remove_finder_category( array $categories ) {
    unset( $categories['edit'] );
    return $categories;
}
add_filter( 'elementor/finder/categories', 'remove_finder_category' );

// 删除特定项目
function remove_finder_item( array $categories ) {
    unset( $categories['create']['items']['post'] );
    return $categories;
}
add_filter( 'elementor/finder/categories', 'remove_finder_item' );

Simple Example: Social Media Links

简单示例：社交媒体链接

See resources/context-menu-finder.md for a complete Finder category implementation.

完整的Finder分类实现请查看 resources/context-menu-finder.md。

5. Context Menu (JavaScript)

5. 上下文菜单（JavaScript）

Context Menu Types

上下文菜单类型

Element - right-click on Section, Column, or Widget
Empty Column - right-click on empty column area
Add New - right-click on add new section/template area

元素 - 右键点击区块、列或组件
空列 - 右键点击空列区域
添加新内容 - 右键点击添加新区块/模板的区域

Available Groups by Element Type

按元素类型划分的可用分组

Group	Section	Column	Widget
`general`	Yes	Yes	Yes
`addNew`	No	Yes	No
`clipboard`	Yes	Yes	Yes
`save`	Yes	No	Yes
`tools`	Yes	Yes	Yes
`delete`	Yes	Yes	Yes

分组	区块	列	组件
`general`	是	是	是
`addNew`	否	是	否
`clipboard`	是	是	是
`save`	是	否	是
`tools`	是	是	是
`delete`	是	是	是

PHP: Enqueue Editor Script

PHP：加载编辑器脚本

php

function my_context_menu_scripts() {
    wp_enqueue_script(
        'my-context-menus',
        plugins_url( 'assets/js/context-menus.js', __FILE__ ),
        [],
        '1.0.0',
        false
    );
}
add_action( 'elementor/editor/after_enqueue_scripts', 'my_context_menu_scripts' );

php

function my_context_menu_scripts() {
    wp_enqueue_script(
        'my-context-menus',
        plugins_url( 'assets/js/context-menus.js', __FILE__ ),
        [],
        '1.0.0',
        false
    );
}
add_action( 'elementor/editor/after_enqueue_scripts', 'my_context_menu_scripts' );

JS: Add New Group with Actions

JS：添加带操作的新分组

window.addEventListener( 'elementor/init', () => {
    elementor.hooks.addFilter( 'elements/context-menu/groups', ( customGroups, elementType ) => {
        const newGroup = {
            name: 'my-custom-group',
            actions: [
                {
                    name: 'my-action-1',
                    icon: 'eicon-alert',
                    title: 'My Action',
                    isEnabled: () => true,
                    callback: () => console.log( 'Action triggered' ),
                },
            ],
        };
        if ( 'widget' === elementType ) {
            customGroups.push( newGroup );
        }
        return customGroups;
    } );
} );

window.addEventListener( 'elementor/init', () => {
    elementor.hooks.addFilter( 'elements/context-menu/groups', ( customGroups, elementType ) => {
        const newGroup = {
            name: 'my-custom-group',
            actions: [
                {
                    name: 'my-action-1',
                    icon: 'eicon-alert',
                    title: 'My Action',
                    isEnabled: () => true,
                    callback: () => console.log( 'Action triggered' ),
                },
            ],
        };
        if ( 'widget' === elementType ) {
            customGroups.push( newGroup );
        }
        return customGroups;
    } );
} );

JS: Modify Groups and Actions

JS：修改分组和操作

// Add action to existing group
customGroups.forEach( ( group ) => {
    if ( 'general' === group.name ) { group.actions.push( newAction ); }
} );

// Remove group
const idx = customGroups.findIndex( ( g ) => 'my-group' === g.name );
if ( idx > -1 ) { customGroups.splice( idx, 1 ); }

// Remove action from group
group.actions.splice( group.actions.findIndex( ( a ) => 'my-action' === a.name ), 1 );

// Update action property
group.actions.forEach( ( a ) => { if ( 'my-action' === a.name ) { a.icon = 'eicon-code'; } } );

// 向现有分组添加操作
customGroups.forEach( ( group ) => {
    if ( 'general' === group.name ) { group.actions.push( newAction ); }
} );

// 删除分组
const idx = customGroups.findIndex( ( g ) => 'my-group' === g.name );
if ( idx > -1 ) { customGroups.splice( idx, 1 ); }

// 从分组中删除操作
group.actions.splice( group.actions.findIndex( ( a ) => 'my-action' === a.name ), 1 );

// 更新操作属性
group.actions.forEach( ( a ) => { if ( 'my-action' === a.name ) { a.icon = 'eicon-code'; } } );

6. Hello Elementor Theme

6. Hello Elementor主题

All Theme Hooks

所有主题钩子

Hook (Filter)	Default	Purpose
`hello_elementor_post_type_support`	`true`	Register post type support
`hello_elementor_add_theme_support`	`true`	Register theme features (title-tag, thumbnails, etc.)
`hello_elementor_register_menus`	`true`	Register navigation menus
`hello_elementor_add_woocommerce_support`	`true`	Register WooCommerce support
`hello_elementor_register_elementor_locations`	`true`	Register Elementor theme locations
`hello_elementor_enqueue_style`	`true`	Load style.min.css
`hello_elementor_enqueue_theme_style`	`true`	Load theme.min.css
`hello_elementor_content_width`	`800`	Content width in pixels
`hello_elementor_page_title`	`true`	Show page title
`hello_elementor_viewport_content`	`width=device-width, initial-scale=1`	Viewport meta tag
`hello_elementor_enable_skip_link`	`true`	Enable accessibility skip link
`hello_elementor_skip_link_url`	`#content`	Skip link target URL

钩子（过滤器）	默认值	用途
`hello_elementor_post_type_support`	`true`	注册文章类型支持
`hello_elementor_add_theme_support`	`true`	注册主题功能（title-tag、缩略图等）
`hello_elementor_register_menus`	`true`	注册导航菜单
`hello_elementor_add_woocommerce_support`	`true`	注册WooCommerce支持
`hello_elementor_register_elementor_locations`	`true`	注册Elementor主题位置
`hello_elementor_enqueue_style`	`true`	加载style.min.css
`hello_elementor_enqueue_theme_style`	`true`	加载theme.min.css
`hello_elementor_content_width`	`800`	内容宽度（像素）
`hello_elementor_page_title`	`true`	显示页面标题
`hello_elementor_viewport_content`	`width=device-width, initial-scale=1`	视口元标签
`hello_elementor_enable_skip_link`	`true`	启用无障碍跳转链接
`hello_elementor_skip_link_url`	`#content`	跳转链接目标地址

Disable a Feature

禁用功能

php

add_filter( 'hello_elementor_register_menus', '__return_false' );
add_filter( 'hello_elementor_enqueue_theme_style', '__return_false' );
add_filter( 'hello_elementor_page_title', '__return_false' );

php

add_filter( 'hello_elementor_register_menus', '__return_false' );
add_filter( 'hello_elementor_enqueue_theme_style', '__return_false' );
add_filter( 'hello_elementor_page_title', '__return_false' );

Custom Content Width

自定义内容宽度

php

function custom_content_width() {
    return 1024;
}
add_filter( 'hello_elementor_content_width', 'custom_content_width' );

php

function custom_content_width() {
    return 1024;
}
add_filter( 'hello_elementor_content_width', 'custom_content_width' );

Other Customizations

其他自定义

php

// Custom viewport
add_filter( 'hello_elementor_viewport_content', fn() => 'width=100vw, height=100vh, user-scalable=no' );

// Custom skip link by page type
add_filter( 'hello_elementor_skip_link_url', function() {
    if ( is_404() ) { return '#404-content'; }
    return is_page() ? '#page-content' : '#main-content';
} );

// Override navigation menus
add_filter( 'hello_elementor_register_menus', '__return_false' );
register_nav_menus( [ 'my-header-menu' => esc_html__( 'Header Menu', 'textdomain' ) ] );

// Remove description meta tag
add_action( 'after_setup_theme', function() {
    remove_action( 'wp_head', 'hello_elementor_add_description_meta_tag' );
} );

php

// 自定义视口
add_filter( 'hello_elementor_viewport_content', fn() => 'width=100vw, height=100vh, user-scalable=no' );

// 按页面类型自定义跳转链接
add_filter( 'hello_elementor_skip_link_url', function() {
    if ( is_404() ) { return '#404-content'; }
    return is_page() ? '#page-content' : '#main-content';
} );

// 覆盖导航菜单
add_filter( 'hello_elementor_register_menus', '__return_false' );
register_nav_menus( [ 'my-header-menu' => esc_html__( 'Header Menu', 'textdomain' ) ] );

// 删除描述元标签
add_action( 'after_setup_theme', function() {
    remove_action( 'wp_head', 'hello_elementor_add_description_meta_tag' );
} );

7. Hosting Cache Integration

7. 托管缓存集成

Purge Everything

清除全部缓存

Action hook with no parameters. Clears all page cache.

php

do_action( 'elementor/hosting/page_cache/purge_everything' );

无参数的动作钩子，清除所有页面缓存。

php

do_action( 'elementor/hosting/page_cache/purge_everything' );

Allow Page Cache Filter

允许页面缓存过滤器

php

function custom_page_cache( $allow ) {
    if ( ! $allow ) { return $allow; }
    return is_my_special_page();
}
add_filter( 'elementor/hosting/page_cache/allow_page_cache', 'custom_page_cache', 20 );

php

function custom_page_cache( $allow ) {
    if ( ! $allow ) { return $allow; }
    return is_my_special_page();
}
add_filter( 'elementor/hosting/page_cache/allow_page_cache', 'custom_page_cache', 20 );

Changed URLs Filter

已更改URL过滤器

Hook:

elementor/hosting/page_cache/{$content_type}_changed_urls

$content_type

values:

post

comment

woocommerce_product

, etc.

Parameters:

$urls

(array),

$content_id

(int).

php

function clear_cache_on_product_update( $urls, $product_id ) {
    if ( ! is_array( $urls ) || empty( $urls ) ) { $urls = []; }
    $urls[] = site_url( '/my-path' );
    return $urls;
}
add_filter(
    'elementor/hosting/page_cache/woocommerce_product_changed_urls',
    'clear_cache_on_product_update', 10, 2
);

钩子：

elementor/hosting/page_cache/{$content_type}_changed_urls

$content_type

取值：

post

、

comment

、

woocommerce_product

等。

参数：

$urls

（数组）、

$content_id

（整数）。

php

function clear_cache_on_product_update( $urls, $product_id ) {
    if ( ! is_array( $urls ) || empty( $urls ) ) { $urls = []; }
    $urls[] = site_url( '/my-path' );
    return $urls;
}
add_filter(
    'elementor/hosting/page_cache/woocommerce_product_changed_urls',
    'clear_cache_on_product_update', 10, 2
);

8. Common Mistakes

8. 常见错误

Mistake	Consequence	Fix
Not checking `function_exists( 'elementor_theme_do_location' )`	Fatal error if Elementor not active	Always wrap in function_exists check with fallback
Using `get_type()` value that does not match parent condition name	Sub-condition not displayed	`get_type()` must return the parent condition's `get_name()` value
Returning wrong category constant in dynamic tags	Tag not shown for matching controls	Use `\Elementor\Modules\DynamicTags\Module::*_CATEGORY` constants
Missing `echo` in dynamic tag `render()`	Empty output	`render()` must `echo` , not `return`
Not escaping dynamic tag output	XSS vulnerability	Use `wp_kses_post()` , `esc_html()` , or `esc_url()`
Forgetting `elementor/init` listener in context menu JS	Filter runs before Elementor ready	Wrap in `window.addEventListener( 'elementor/init', ... )`
Using `elementor/editor/after_enqueue_scripts` for frontend JS	Script only loads in editor	Use `wp_enqueue_scripts` for frontend, editor hook for editor-only
Not validating `$allow` parameter in cache filter	Overrides other filters	Check `if ( ! $allow ) { return $allow; }` first
Registering location without Elementor Pro active	Theme Builder requires Pro	Check if Elementor Pro is active before registering conditions
Calling `register_all_core_location()` and individual locations	Duplicate registrations	Use one or the other, not both

错误	后果	修复方案
未检查 `function_exists( 'elementor_theme_do_location' )`	若Elementor未激活会导致致命错误	始终用function_exists检查并添加降级方案
`get_type()` 返回值与父条件名称不匹配	子条件无法显示	`get_type()` 必须返回父条件的 `get_name()` 值
动态标签中返回错误的分类常量	标签无法在匹配的控件中显示	使用 `\Elementor\Modules\DynamicTags\Module::*_CATEGORY` 常量
动态标签的 `render()` 中缺少 `echo`	输出为空	`render()` 必须使用 `echo` ，而非 `return`
未转义动态标签输出	存在XSS漏洞	使用 `wp_kses_post()` 、 `esc_html()` 或 `esc_url()`
上下文菜单JS中遗漏 `elementor/init` 监听器	过滤器在Elementor就绪前执行	包裹在 `window.addEventListener( 'elementor/init', ... )` 中
为前端JS使用 `elementor/editor/after_enqueue_scripts`	脚本仅在编辑器中加载	前端使用 `wp_enqueue_scripts` ，仅编辑器使用的脚本用编辑器钩子
缓存过滤器中未验证 `$allow` 参数	覆盖其他过滤器	先检查 `if ( ! $allow ) { return $allow; }`
未激活Elementor Pro时注册位置	Theme Builder需要Pro版本	注册条件前先检查Elementor Pro是否激活
同时调用 `register_all_core_location()` 和单独注册位置	重复注册	二选一，不要同时使用