云策 WordPress 开发者社区

函数文档

wp_print_theme_file_tree()

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

概述

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

关键要点

  • 函数接受参数：$tree（必需，文件/文件夹路径列表或文件名）、$level（可选，ARIA 级别，默认 2）、$size（可选，ARIA 集合大小，默认 1）、$index（可选，ARIA 位置索引，默认 1）。
  • 递归处理数组结构，如果是数组则遍历每个元素，否则直接输出文件链接。
  • 输出包含 ARIA 属性（如 aria-level、aria-setsize、aria-posinset）以支持辅助技术。
  • 使用相关函数如 get_file_description() 获取文件描述，self_admin_url() 生成管理 URL，并应用转义函数确保安全性。

代码示例

function wp_print_theme_file_tree( $tree, $level = 2, $size = 1, $index = 1 ) {
    global $relative_file, $stylesheet;

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

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

            if ( ! is_array( $theme_file ) ) {
                wp_print_theme_file_tree( $theme_file, $level, $index, $size );
                continue;
            }
            // 输出 HTML 结构，包括链接和 ARIA 属性
        endforeach;
    } else {
        // 输出单个文件链接
    }
}

注意事项

  • 函数在 WordPress 4.9.0 版本中引入，位于 wp-admin/includes/misc.php 文件中。
  • 依赖于全局变量 $relative_file 和 $stylesheet，需确保在调用前已正确设置。
  • 输出内容已通过 esc_attr()、esc_html() 等函数转义，以防止 XSS 攻击。
📄 原文内容

Outputs the formatted file list for the theme file editor.

Parameters

$treearray|stringrequired
List of file/folder paths, or filename.
$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_theme_file_tree( $tree, $level = 2, $size = 1, $index = 1 ) {

	global $relative_file, $stylesheet;


	if ( is_array( $tree ) ) {

		$index = 0;

		$size  = count( $tree );


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

			++$index;


			if ( ! is_array( $theme_file ) ) {

				wp_print_theme_file_tree( $theme_file, $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 ),

				'theme' => rawurlencode( $stylesheet ),

			),

			self_admin_url( 'theme-editor.php' )

		);

		?>

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

			<a role="treeitem" tabindex="<?php echo esc_attr( $relative_file === $filename ? '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 ); ?>">

				<span class="nonessential">(' . esc_html( $filename ) . ')</span>';

				}


				if ( $relative_file === $filename ) {

					echo '<span class="notice notice-info">' . $file_description . '</span>';

				} else {

					echo $file_description;

				}

				?>

			</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#L399">View on Trac</a> <a href="https://github.com/WordPress/wordpress-develop/blob/6.9.4/src/wp-admin/includes/misc.php#L399-L461">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_theme_file_tree/">wp_print_theme_file_tree()</a><code>wp-admin/includes/misc.php


Outputs the formatted file list for the theme file editor.




get_file_description()wp-admin/includes/file.php


Gets the description for standard WordPress theme files.




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.




wp_basename()wp-includes/formatting.php


i18n-friendly version of basename().




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 6 moreShow less
Used by Description
wp_print_theme_file_tree()wp-admin/includes/misc.php

Outputs the formatted file list for the theme file editor.

Changelog

Version Description
4.9.0 Introduced.