wp_enqueue_code_editor()

💡 云策文档标注

概述

wp_enqueue_code_editor() 函数用于为代码编辑器加载必要的脚本和样式资源，基于给定的设置参数。它返回编辑器设置数组或 false（如果未加载）。

关键要点

函数根据用户语法高亮设置和参数验证决定是否加载编辑器资源。
支持多种文件类型（如 CSS、HTML、PHP、JavaScript），并自动加载相应的 lint 工具（如 CSSLint、JSHint、HTMLHint）。
通过 wp_add_inline_script() 将设置注入到全局 JavaScript 中，并触发 wp_enqueue_code_editor 钩子。
参数包括文件类型、主题/插件编辑上下文，以及 CodeMirror、CSSLint、JSHint、HTMLHint 的覆盖设置。

代码示例

function code_editor_enqueue_scripts() {
    if ( 'my_settings_page' !== get_current_screen()->id ) {
        return;
    }

    // Enqueue code editor and settings for manipulating HTML.
    $settings = wp_enqueue_code_editor( array( 'type' => 'text/html' ) );

    // Return if the editor was not enqueued.
    if ( false === $settings ) {
        return;
    }

    wp_add_inline_script(
        'code-editor',
        sprintf(
            'jQuery( function() { wp.codeEditor.initialize( "my_textarea_id", %s ); } );',
            wp_json_encode( $settings )
        )
    );
}
add_action( 'admin_enqueue_scripts', 'code_editor_enqueue_scripts' );

📄 原文内容

Enqueues assets needed by the code editor for the given settings.

Description

Parameters

$argsarrayrequired

Args.

type string
The MIME type of the file to be edited.
file string
Filename to be edited. Extension is used to sniff the type. Can be supplied as alternative to $type param.
theme WP_Theme
Theme being edited when on the theme file editor.
plugin string
Plugin being edited when on the plugin file editor.
codemirror array
Additional CodeMirror setting overrides.
csslint array
CSSLint rule overrides.
jshint array
JSHint rule overrides.
htmlhint array
HTMLHint rule overrides.

Return

array|false Settings for the enqueued code editor, or false if the editor was not enqueued.

Source

function wp_enqueue_code_editor( $args ) {
	if ( is_user_logged_in() && 'false' === wp_get_current_user()->syntax_highlighting ) {
		return false;
	}

	$settings = wp_get_code_editor_settings( $args );

	if ( empty( $settings ) || empty( $settings['codemirror'] ) ) {
		return false;
	}

	wp_enqueue_script( 'code-editor' );
	wp_enqueue_style( 'code-editor' );

	if ( isset( $settings['codemirror']['mode'] ) ) {
		$mode = $settings['codemirror']['mode'];
		if ( is_string( $mode ) ) {
			$mode = array(
				'name' => $mode,
			);
		}

		if ( ! empty( $settings['codemirror']['lint'] ) ) {
			switch ( $mode['name'] ) {
				case 'css':
				case 'text/css':
				case 'text/x-scss':
				case 'text/x-less':
					wp_enqueue_script( 'csslint' );
					break;
				case 'htmlmixed':
				case 'text/html':
				case 'php':
				case 'application/x-httpd-php':
				case 'text/x-php':
					wp_enqueue_script( 'htmlhint' );
					wp_enqueue_script( 'csslint' );
					wp_enqueue_script( 'jshint' );
					if ( ! current_user_can( 'unfiltered_html' ) ) {
						wp_enqueue_script( 'htmlhint-kses' );
					}
					break;
				case 'javascript':
				case 'application/ecmascript':
				case 'application/json':
				case 'application/javascript':
				case 'application/ld+json':
				case 'text/typescript':
				case 'application/typescript':
					wp_enqueue_script( 'jshint' );
					wp_enqueue_script( 'jsonlint' );
					break;
			}
		}
	}

	wp_add_inline_script( 'code-editor', sprintf( 'jQuery.extend( wp.codeEditor.defaultSettings, %s );', wp_json_encode( $settings, JSON_HEX_TAG | JSON_UNESCAPED_SLASHES ) ) );

	/**
	 * Fires when scripts and styles are enqueued for the code editor.
	 *
	 * @since 4.9.0
	 *
	 * @param array $settings Settings for the enqueued code editor.
	 */
	do_action( 'wp_enqueue_code_editor', $settings );

	return $settings;
}

View all references View on Trac View on GitHub

Hooks

do_action( ‘wp_enqueue_code_editor’, array $settings ): Fires when scripts and styles are enqueued for the code editor.

Uses	Description
wp_get_code_editor_settings()`wp-includes/general-template.php`	Generates and returns code editor settings.
wp_add_inline_script()`wp-includes/functions.wp-scripts.php`	Adds extra code to a registered script.
wp_get_current_user()`wp-includes/pluggable.php`	Retrieves the current user object.
wp_enqueue_script()`wp-includes/functions.wp-scripts.php`	Enqueues a script.
wp_enqueue_style()`wp-includes/functions.wp-styles.php`	Enqueues a CSS stylesheet.
wp_json_encode()`wp-includes/functions.php`	Encodes a variable into JSON, with some confidence checks.
current_user_can()`wp-includes/capabilities.php`	Returns whether the current user has the specified capability.
is_user_logged_in()`wp-includes/pluggable.php`	Determines whether the current visitor is a logged in user.
do_action()`wp-includes/plugin.php`	Calls the callback functions that have been added to an action hook.

Show 4 more Show less

Used by	Description
WP_Widget_Custom_HTML::enqueue_admin_scripts()`wp-includes/widgets/class-wp-widget-custom-html.php`	Loads the required scripts and styles for the widget control.
WP_Customize_Code_Editor_Control::enqueue()`wp-includes/customize/class-wp-customize-code-editor-control.php`	Enqueue control related scripts/styles.

Changelog

Version	Description
4.9.0	Introduced.

User Contributed Notes

Skip to note 2 content

Kevin

5 years ago

Example of how to get code highlighting set on a custom settings textarea.

function code_editor_enqueue_scripts() {
	if ( 'my_settings_page' !== get_current_screen()->id ) {
		return;
	}

	// Enqueue code editor and settings for manipulating HTML.
	$settings = wp_enqueue_code_editor( array( 'type' => 'text/html' ) );

	// Return if the editor was not enqueued.
	if ( false === $settings ) {
		return;
	}

	wp_add_inline_script(
		'code-editor',
		sprintf(
			'jQuery( function() { wp.codeEditor.initialize( "my_textarea_id", %s ); } );',
			wp_json_encode( $settings )
		)
	);
}
add_action( 'admin_enqueue_scripts', 'code_editor_enqueue_scripts' );

云策 WordPress 开发者社区

函数文档