云策 WordPress 开发者社区

函数文档

wp_print_plugin_file_tree()

查看官方原文 ↗
💡 云策文档标注

概述

wp_print_plugin_file_tree() 函数用于在插件文件编辑器中输出格式化的文件列表。它递归处理文件/文件夹路径数组，生成带有 ARIA 属性的 HTML 结构，以增强可访问性。

关键要点

  • 函数输出插件文件编辑器的格式化文件列表，支持递归处理数组结构。
  • 参数包括 $tree（文件/文件夹路径列表或文件名）、$label（文件或文件夹名称）、$level（aria-level，默认 2）、$size（aria-setsize，默认 1）和 $index（aria-posinset，默认 1）。
  • 内部逻辑：如果 $tree 是数组，则遍历每个元素，递归调用自身处理文件；否则生成链接到 plugin-editor.php 的 HTML 项。
  • 使用相关函数如 self_admin_url()、esc_html() 等确保 URL 和文本的安全性。
  • 自 WordPress 4.9.0 版本引入，位于 wp-admin/includes/misc.php 文件中。

代码示例

function wp_print_plugin_file_tree( $tree, $label = '', $level = 2, $size = 1, $index = 1 ) {
    global $file, $plugin;

    if ( is_array( $tree ) ) {
        $index = 0;
        $size  = count( $tree );

        foreach ( $tree as $label => $plugin_file ) :
            ++$index;

            if ( ! is_array( $plugin_file ) ) {
                wp_print_plugin_file_tree( $plugin_file, $label, $level, $index, $size );
                continue;
            }
            ?>
            <li role="treeitem" aria-expanded="false" aria-setsize="" aria-posinset="">
                <span class="folder-label"><?php echo esc_html( $label ); ?></span>
                <ul role="group"><?php wp_print_plugin_file_tree( $plugin_file, '', $level + 1 ); ?></ul>
            </li>
            <?php
        endforeach;
    } else {
        $url = add_query_arg(
            array(
                'file'   => rawurlencode( $tree ),
                'plugin' => rawurlencode( $plugin ),
            ),
            self_admin_url( 'plugin-editor.php' )
        );
        ?>
        <li role="none">
            <a role="treeitem" href="<?php echo esc_url( $url ); ?>" aria-level="<?php echo esc_attr( $level ); ?>" aria-setsize="<?php echo esc_attr( $size ); ?>" aria-posinset="<?php echo esc_attr( $index ); ?>">
                <?php
                if ( $label ) {
                    echo '<strong>' . esc_html( $label ) . '</strong>';
                } else {
                    echo esc_html( $label );
                }
                ?>
            </a>
        </li>
        <?php
    }
}

注意事项

  • 函数依赖于全局变量 $file 和 $plugin，调用前需确保这些变量已正确设置。
  • 递归调用时，注意参数传递以避免无限循环，特别是处理嵌套数组结构。
  • 生成的 HTML 包含 ARIA 属性（如 aria-level、aria-setsize、aria-posinset），以支持辅助技术，确保可访问性。
  • 使用 esc_html()、esc_url() 等函数对输出进行转义，防止 XSS 攻击。
📄 原文内容

Outputs the formatted file list for the plugin file editor.

Parameters

$treearray|stringrequired
List of file/folder paths, or filename.
$labelstringrequired
Name of file or folder to print.
$levelintoptional
The aria-level for the current iteration.

Default:2

$sizeintoptional
The aria-setsize for the current iteration.

Default:1

$indexintoptional
The aria-posinset for the current iteration.

Default:1

Source

function wp_print_plugin_file_tree( $tree, $label = '', $level = 2, $size = 1, $index = 1 ) {

	global $file, $plugin;


	if ( is_array( $tree ) ) {

		$index = 0;

		$size  = count( $tree );


		foreach ( $tree as $label => $plugin_file ) :

			++$index;


			if ( ! is_array( $plugin_file ) ) {

				wp_print_plugin_file_tree( $plugin_file, $label, $level, $index, $size );

				continue;

			}

			?>

			<li role="treeitem" aria-expanded="true" tabindex="-1"

				aria-level="<?php echo esc_attr( $level ); ?>"

				aria-setsize="<?php echo esc_attr( $size ); ?>"

				aria-posinset="<?php echo esc_attr( $index ); ?>">

				<span class="folder-label"> <span class="screen-reader-text">


				</span><span aria-hidden="true" class="icon"></span></span>

				<ul role="group" class="tree-folder"></ul>

			</li>

			 rawurlencode( $tree ),

				'plugin' => rawurlencode( $plugin ),

			),

			self_admin_url( 'plugin-editor.php' )

		);

		?>

		<li role="none" class="<?php echo esc_attr( $file === $tree ? 'current-file' : '' ); ?>">

			<a role="treeitem" tabindex="<?php echo esc_attr( $file === $tree ? '0' : '-1' ); ?>"

				href="<?php echo esc_url( $url ); ?>"

				aria-level="<?php echo esc_attr( $level ); ?>"

				aria-setsize="<?php echo esc_attr( $size ); ?>"

				aria-posinset="<?php echo esc_attr( $index ); ?>">

				' . esc_html( $label ) . '</span>';

				} else {

					echo esc_html( $label );

				}

				?>

			</a>

		</li>

		</pre><p class="wporg-dot-link-list"><a href="https://developer.wordpress.org/reference/files/wp-admin/includes/misc.php/">View all references</a> <a href="https://core.trac.wordpress.org/browser/tags/6.9.4/src/wp-admin/includes/misc.php#L501">View on Trac</a> <a href="https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-admin/includes/misc.php#L501-L556">View on GitHub</a></p></section>


		<section class="wp-block-wporg-code-reference-related" data-nosnippet="true"><h2 id="related" class="is-toc-heading wp-block-heading has-heading-5-font-size" tabindex="-1" ><a href="#related">Related</a></h2> <section style="margin-top:var(--wp--preset--spacing--20)" class="wp-block-wporg-code-table" id="uses"><figure class="wp-block-table "><table><thead><tr><th scope="col">Uses</th><th scope="col">Description</th></tr></thead><tbody><tr class=""><td><a href="https://developer.wordpress.org/reference/functions/wp_print_plugin_file_tree/">wp_print_plugin_file_tree()</a><code>wp-admin/includes/misc.php


Outputs the formatted file list for the plugin file editor.




self_admin_url()wp-includes/link-template.php


Retrieves the URL to the admin area for either the current site or the network depending on context.




_e()wp-includes/l10n.php


Displays translated text.




esc_attr()wp-includes/formatting.php


Escaping for HTML attributes.




esc_html()wp-includes/formatting.php


Escaping for HTML blocks.




esc_url()wp-includes/formatting.php


Checks and cleans a URL.




add_query_arg()wp-includes/functions.php


Retrieves a modified URL query string.







Show 5 moreShow less
Used by Description
wp_print_plugin_file_tree()wp-admin/includes/misc.php

Outputs the formatted file list for the plugin file editor.

Changelog

Version Description
4.9.0 Introduced.