云策 WordPress 开发者社区

函数文档

get_theme_starter_content()

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

概述

get_theme_starter_content() 函数用于扩展主题的 starter content 配置，通过整合 WordPress 核心提供的数据，返回一个包含小工具、导航菜单、文章等内容的数组。该函数支持主题通过 'starter-content' 主题支持参数自定义配置，并允许开发者使用过滤器进行修改。

关键要点

  • 函数通过 get_theme_support('starter-content') 获取主题的 starter content 配置，若未设置则返回空数组。
  • 核心提供默认的 starter content，包括小工具（如文本、归档、日历等）、导航菜单项（如主页链接、社交媒体链接）和文章（如主页、关于、联系页面）。
  • 函数处理配置中的不同类型（如 options、theme_mods、widgets、nav_menus、attachments、posts），并支持扩展核心内容或直接引用核心项。
  • 使用 apply_filters('get_theme_starter_content', $content, $config) 过滤器，允许开发者修改返回的 starter content 数组。
  • 相关函数包括 get_theme_support()、wp_array_slice_assoc()、_x()、home_url() 和 apply_filters()。

代码示例

function get_theme_starter_content() {
    $theme_support = get_theme_support( 'starter-content' );
    if ( is_array( $theme_support ) && ! empty( $theme_support[0] ) && is_array( $theme_support[0] ) ) {
        $config = $theme_support[0];
    } else {
        $config = array();
    }

    $core_content = array(
        'widgets'   => array(
            'text_business_info' => array(
                'text',
                array(
                    'title'  => _x( 'Find Us', 'Theme starter content' ),
                    'text'   => implode(
                        '',
                        array(
                            '' . _x( 'Address', 'Theme starter content' ) . "n",
                            _x( '123 Main Street', 'Theme starter content' ) . "n",
                            _x( 'New York, NY 10001', 'Theme starter content' ) . "nn",
                            '' . _x( 'Hours', 'Theme starter content' ) . "n",
                            _x( 'Monday–Friday: 9:00AM–5:00PM', 'Theme starter content' ) . "n",
                            _x( 'Saturday & Sunday: 11:00AM–3:00PM', 'Theme starter content' ),
                        )
                    ),
                    'filter' => true,
                    'visual' => true,
                ),
            ),
            // 更多小工具定义...
        ),
        'nav_menus' => array(
            'link_home' => array(
                'type'  => 'custom',
                'title' => _x( 'Home', 'Theme starter content' ),
                'url'   => home_url( '/' ),
            ),
            // 更多导航菜单项定义...
        ),
        'posts'     => array(
            'home' => array(
                'post_type'    => 'page',
                'post_title'   => _x( 'Home', 'Theme starter content' ),
                'post_content' => sprintf(
                    "n%sn",
                    _x( 'Welcome to your site! This is your homepage, which is what most visitors will see when they come to your site for the first time.', 'Theme starter content' )
                ),
            ),
            // 更多文章定义...
        ),
    );

    $content = array();
    foreach ( $config as $type => $args ) {
        switch ( $type ) {
            case 'options':
            case 'theme_mods':
                $content[$type] = $config[$type];
                break;
            case 'widgets':
                // 处理小工具配置...
                break;
            case 'nav_menus':
                // 处理导航菜单配置...
                break;
            case 'attachments':
                // 处理附件配置...
                break;
            case 'posts':
                // 处理文章配置...
                break;
        }
    }
    return apply_filters( 'get_theme_starter_content', $content, $config );
}

注意事项

  • 主题可以通过 add_theme_support('starter-content', $config) 注册自定义 starter content，配置数组可包含 widgets、nav_menus、posts 等键。
  • 在配置中，可以使用字符串引用核心内容（如 'text_business_info'），或使用数组扩展核心内容。
  • 函数返回的数组可直接用于主题定制器或其他导入功能，如 WP_Customize_Manager::import_theme_starter_content()。
  • 自 WordPress 4.7.0 版本引入此函数，确保在兼容版本中使用。
📄 原文内容

Expands a theme’s starter content configuration using core-provided data.

Return

array Array of starter content.

Source

function get_theme_starter_content() {
	$theme_support = get_theme_support( 'starter-content' );
	if ( is_array( $theme_support ) && ! empty( $theme_support[0] ) && is_array( $theme_support[0] ) ) {
		$config = $theme_support[0];
	} else {
		$config = array();
	}

	$core_content = array(
		'widgets'   => array(
			'text_business_info' => array(
				'text',
				array(
					'title'  => _x( 'Find Us', 'Theme starter content' ),
					'text'   => implode(
						'',
						array(
							'<strong>' . _x( 'Address', 'Theme starter content' ) . "</strong>n",
							_x( '123 Main Street', 'Theme starter content' ) . "n",
							_x( 'New York, NY 10001', 'Theme starter content' ) . "nn",
							'<strong>' . _x( 'Hours', 'Theme starter content' ) . "</strong>n",
							_x( 'Monday–Friday: 9:00AM–5:00PM', 'Theme starter content' ) . "n",
							_x( 'Saturday & Sunday: 11:00AM–3:00PM', 'Theme starter content' ),
						)
					),
					'filter' => true,
					'visual' => true,
				),
			),
			'text_about'         => array(
				'text',
				array(
					'title'  => _x( 'About This Site', 'Theme starter content' ),
					'text'   => _x( 'This may be a good place to introduce yourself and your site or include some credits.', 'Theme starter content' ),
					'filter' => true,
					'visual' => true,
				),
			),
			'archives'           => array(
				'archives',
				array(
					'title' => _x( 'Archives', 'Theme starter content' ),
				),
			),
			'calendar'           => array(
				'calendar',
				array(
					'title' => _x( 'Calendar', 'Theme starter content' ),
				),
			),
			'categories'         => array(
				'categories',
				array(
					'title' => _x( 'Categories', 'Theme starter content' ),
				),
			),
			'meta'               => array(
				'meta',
				array(
					'title' => _x( 'Meta', 'Theme starter content' ),
				),
			),
			'recent-comments'    => array(
				'recent-comments',
				array(
					'title' => _x( 'Recent Comments', 'Theme starter content' ),
				),
			),
			'recent-posts'       => array(
				'recent-posts',
				array(
					'title' => _x( 'Recent Posts', 'Theme starter content' ),
				),
			),
			'search'             => array(
				'search',
				array(
					'title' => _x( 'Search', 'Theme starter content' ),
				),
			),
		),
		'nav_menus' => array(
			'link_home'       => array(
				'type'  => 'custom',
				'title' => _x( 'Home', 'Theme starter content' ),
				'url'   => home_url( '/' ),
			),
			'page_home'       => array( // Deprecated in favor of 'link_home'.
				'type'      => 'post_type',
				'object'    => 'page',
				'object_id' => '{{home}}',
			),
			'page_about'      => array(
				'type'      => 'post_type',
				'object'    => 'page',
				'object_id' => '{{about}}',
			),
			'page_blog'       => array(
				'type'      => 'post_type',
				'object'    => 'page',
				'object_id' => '{{blog}}',
			),
			'page_news'       => array(
				'type'      => 'post_type',
				'object'    => 'page',
				'object_id' => '{{news}}',
			),
			'page_contact'    => array(
				'type'      => 'post_type',
				'object'    => 'page',
				'object_id' => '{{contact}}',
			),

			'link_email'      => array(
				'title' => _x( 'Email', 'Theme starter content' ),
				'url'   => 'mailto:wordpress@example.com',
			),
			'link_facebook'   => array(
				'title' => _x( 'Facebook', 'Theme starter content' ),
				'url'   => 'https://www.facebook.com/wordpress',
			),
			'link_foursquare' => array(
				'title' => _x( 'Foursquare', 'Theme starter content' ),
				'url'   => 'https://foursquare.com/',
			),
			'link_github'     => array(
				'title' => _x( 'GitHub', 'Theme starter content' ),
				'url'   => 'https://github.com/wordpress/',
			),
			'link_instagram'  => array(
				'title' => _x( 'Instagram', 'Theme starter content' ),
				'url'   => 'https://www.instagram.com/explore/tags/wordcamp/',
			),
			'link_linkedin'   => array(
				'title' => _x( 'LinkedIn', 'Theme starter content' ),
				'url'   => 'https://www.linkedin.com/company/1089783',
			),
			'link_pinterest'  => array(
				'title' => _x( 'Pinterest', 'Theme starter content' ),
				'url'   => 'https://www.pinterest.com/',
			),
			'link_twitter'    => array(
				'title' => _x( 'Twitter', 'Theme starter content' ),
				'url'   => 'https://twitter.com/wordpress',
			),
			'link_yelp'       => array(
				'title' => _x( 'Yelp', 'Theme starter content' ),
				'url'   => 'https://www.yelp.com',
			),
			'link_youtube'    => array(
				'title' => _x( 'YouTube', 'Theme starter content' ),
				'url'   => 'https://www.youtube.com/channel/UCdof4Ju7amm1chz1gi1T2ZA',
			),
		),
		'posts'     => array(
			'home'             => array(
				'post_type'    => 'page',
				'post_title'   => _x( 'Home', 'Theme starter content' ),
				'post_content' => sprintf(
					"<!-- wp:paragraph -->n<p>%s</p>n<!-- /wp:paragraph -->",
					_x( 'Welcome to your site! This is your homepage, which is what most visitors will see when they come to your site for the first time.', 'Theme starter content' )
				),
			),
			'about'            => array(
				'post_type'    => 'page',
				'post_title'   => _x( 'About', 'Theme starter content' ),
				'post_content' => sprintf(
					"<!-- wp:paragraph -->n<p>%s</p>n<!-- /wp:paragraph -->",
					_x( 'You might be an artist who would like to introduce yourself and your work here or maybe you are a business with a mission to describe.', 'Theme starter content' )
				),
			),
			'contact'          => array(
				'post_type'    => 'page',
				'post_title'   => _x( 'Contact', 'Theme starter content' ),
				'post_content' => sprintf(
					"<!-- wp:paragraph -->n<p>%s</p>n<!-- /wp:paragraph -->",
					_x( 'This is a page with some basic contact information, such as an address and phone number. You might also try a plugin to add a contact form.', 'Theme starter content' )
				),
			),
			'blog'             => array(
				'post_type'  => 'page',
				'post_title' => _x( 'Blog', 'Theme starter content' ),
			),
			'news'             => array(
				'post_type'  => 'page',
				'post_title' => _x( 'News', 'Theme starter content' ),
			),

			'homepage-section' => array(
				'post_type'    => 'page',
				'post_title'   => _x( 'A homepage section', 'Theme starter content' ),
				'post_content' => sprintf(
					"<!-- wp:paragraph -->n<p>%s</p>n<!-- /wp:paragraph -->",
					_x( 'This is an example of a homepage section. Homepage sections can be any page other than the homepage itself, including the page that shows your latest blog posts.', 'Theme starter content' )
				),
			),
		),
	);

	$content = array();

	foreach ( $config as $type => $args ) {
		switch ( $type ) {
			// Use options and theme_mods as-is.
			case 'options':
			case 'theme_mods':
				$content[ $type ] = $config[ $type ];
				break;

			// Widgets are grouped into sidebars.
			case 'widgets':
				foreach ( $config[ $type ] as $sidebar_id => $widgets ) {
					foreach ( $widgets as $id => $widget ) {
						if ( is_array( $widget ) ) {

							// Item extends core content.
							if ( ! empty( $core_content[ $type ][ $id ] ) ) {
								$widget = array(
									$core_content[ $type ][ $id ][0],
									array_merge( $core_content[ $type ][ $id ][1], $widget ),
								);
							}

							$content[ $type ][ $sidebar_id ][] = $widget;
						} elseif ( is_string( $widget )
							&& ! empty( $core_content[ $type ] )
							&& ! empty( $core_content[ $type ][ $widget ] )
						) {
							$content[ $type ][ $sidebar_id ][] = $core_content[ $type ][ $widget ];
						}
					}
				}
				break;

			// And nav menu items are grouped into nav menus.
			case 'nav_menus':
				foreach ( $config[ $type ] as $nav_menu_location => $nav_menu ) {

					// Ensure nav menus get a name.
					if ( empty( $nav_menu['name'] ) ) {
						$nav_menu['name'] = $nav_menu_location;
					}

					$content[ $type ][ $nav_menu_location ]['name'] = $nav_menu['name'];

					foreach ( $nav_menu['items'] as $id => $nav_menu_item ) {
						if ( is_array( $nav_menu_item ) ) {

							// Item extends core content.
							if ( ! empty( $core_content[ $type ][ $id ] ) ) {
								$nav_menu_item = array_merge( $core_content[ $type ][ $id ], $nav_menu_item );
							}

							$content[ $type ][ $nav_menu_location ]['items'][] = $nav_menu_item;
						} elseif ( is_string( $nav_menu_item )
							&& ! empty( $core_content[ $type ] )
							&& ! empty( $core_content[ $type ][ $nav_menu_item ] )
						) {
							$content[ $type ][ $nav_menu_location ]['items'][] = $core_content[ $type ][ $nav_menu_item ];
						}
					}
				}
				break;

			// Attachments are posts but have special treatment.
			case 'attachments':
				foreach ( $config[ $type ] as $id => $item ) {
					if ( ! empty( $item['file'] ) ) {
						$content[ $type ][ $id ] = $item;
					}
				}
				break;

			/*
			 * All that's left now are posts (besides attachments).
			 * Not a default case for the sake of clarity and future work.
			 */
			case 'posts':
				foreach ( $config[ $type ] as $id => $item ) {
					if ( is_array( $item ) ) {

						// Item extends core content.
						if ( ! empty( $core_content[ $type ][ $id ] ) ) {
							$item = array_merge( $core_content[ $type ][ $id ], $item );
						}

						// Enforce a subset of fields.
						$content[ $type ][ $id ] = wp_array_slice_assoc(
							$item,
							array(
								'post_type',
								'post_title',
								'post_excerpt',
								'post_name',
								'post_content',
								'menu_order',
								'comment_status',
								'thumbnail',
								'template',
							)
						);
					} elseif ( is_string( $item ) && ! empty( $core_content[ $type ][ $item ] ) ) {
						$content[ $type ][ $item ] = $core_content[ $type ][ $item ];
					}
				}
				break;
		}
	}

	/**
	 * Filters the expanded array of starter content.
	 *
	 * @since 4.7.0
	 *
	 * @param array $content Array of starter content.
	 * @param array $config  Array of theme-specific starter content configuration.
	 */
	return apply_filters( 'get_theme_starter_content', $content, $config );
}

View all references View on Trac View on GitHub

Hooks

apply_filters( ‘get_theme_starter_content’, array $content, array $config )

Filters the expanded array of starter content.

Uses Description
get_theme_support()wp-includes/theme.php

Gets the theme support arguments passed when registering that support.
wp_array_slice_assoc()wp-includes/functions.php

Extracts a slice of an array, given a list of keys.
_x()wp-includes/l10n.php

Retrieves translated string with gettext context.
home_url()wp-includes/link-template.php

Retrieves the URL for the current site where the front end is accessible.
apply_filters()wp-includes/plugin.php

Calls the callback functions that have been added to a filter hook.

Show 3 moreShow less

Used by Description
WP_Customize_Manager::import_theme_starter_content()wp-includes/class-wp-customize-manager.php

Imports theme starter content into the customized state.

Changelog

Version Description
4.7.0 Introduced.