Sobird

允许WordPress主题或插件给当前正在使用的主题注册一些特色功能，如果在主题中使用，应该将该函数写入 function.php文件中，如果是在插件中使用该函数，那它必须挂在钩子上（HOOK），如果是挂在钩子上，那他必须挂在after_setup_theme这个钩子上，如果挂在init钩子上执行时机将会太晚，以致部分特色功能将失效。

用法

add_theme_support( string $feature, mixed $args )

示例：

add_theme_support( 'title-tag' );
add_theme_support( 'custom-logo', array(
    'height' => 480,
    'width'  => 720,
) );

参数

$feature (string) (Required) 

目前主题支持的功能列表：

• ‘post-formats’
• ‘post-thumbnails’
• ‘custom-header’
• ‘custom-background’
• ‘custom-logo’
• ‘menus’
• ‘automatic-feed-links’
• ‘html5’
• ‘title-tag’
• ‘customize-selective-refresh-widgets’
• ‘starter-content’
• ‘responsive-embeds’
• ‘align-wide’
• ‘dark-editor-style’
• ‘disable-custom-colors’
• ‘disable-custom-font-sizes’
• ‘editor-color-palette’
• ‘editor-font-sizes’
• ‘editor-styles’
• ‘wp-block-styles’
• ‘core-block-patterns’

$args (mixed) (Optional)

与某些特性一起传递的额外参数。

返回值 (void|bool)

失败时返回false, 否则返回void。

特色功能介绍

Post Formats

该功能让主题支持文章格式（Post Formats），在3.1版本中引入。当使用子主题（child themes）时，注意 add_theme_support( 'post-formats' )会覆盖父主题（parent themes）定义的 formats，而不是额外增加。

要让主题支持特定Post Formats，请使用：

add_theme_support( 'post-formats', array( 'aside', 'gallery' ) );

检查一个主题是否给 post 指定了 ‘quote’ 这类 post format，请使用 has_post_format()：

// In your theme single.php, page.php or custom post type
if ( has_post_format( 'quote' ) ) {
    echo 'This is a quote.';
}

Post Thumbnails

该功能让主题支持文章缩略图（Post Thumbnails），在2.9版本中引入，我们可以将文章类型（Post Type）数组传入第二个参数$args，来指定哪些文章类型要启用这个功能。

add_theme_support( 'post-thumbnails' );
add_theme_support( 'post-thumbnails', array( 'post' ) );          // Posts only
add_theme_support( 'post-thumbnails', array( 'page' ) );          // Pages only
add_theme_support( 'post-thumbnails', array( 'post', 'movie' ) ); // Posts and Movies

该功能必须在 init（Hook）之前调用，所以必须在主题的 functions.php 文件或者在 after_setup_theme （Hook）中调用。对于自定义文章类型（custom post types），我们可以在使用 register_post_type() 注册新的日志类型的时候，添加 post thumbnails 的支持。

在主题的index.php，single.php或自定义模板中显示文章略缩图，请使用：

the_post_thumbnail();

要在显示文章之前检查是否为文章指定了缩略图，请使用：

if ( has_post_thumbnail() ) {
    the_post_thumbnail();
}

Custom Header

该功能让主题支持自定义页头（Custom Header），在3.4版本中引入。

add_theme_support( 'custom-header' );

请注意，您可以使用以下方法添加默认参数：

$defaults = array(
    'default-image'          => '',
    'random-default'         => false,
    'width'                  => 0,
    'height'                 => 0,
    'flex-height'            => false,
    'flex-width'             => false,
    'default-text-color'     => '',
    'header-text'            => true,
    'uploads'                => true,
    'wp-head-callback'       => '',
    'admin-head-callback'    => '',
    'admin-preview-callback' => '',
    'video'                  => false,
    'video-active-callback'  => 'is_front_page',
);
add_theme_support( 'custom-header', $defaults );

Custom Background

该功能让主题支持自定义背景（Custom Background），在3.4版本中引入。替换原来的add_custom_background()方法。

add_theme_support( 'custom-background' );

请注意，您可以使用以下方法添加默认参数：

$defaults = array(
	'default-color'          => '',
	'default-image'          => '',
	'wp-head-callback'       => '_custom_background_cb',
	'admin-head-callback'    => '',
	'admin-preview-callback' => ''
);
add_theme_support( 'custom-background', $defaults );

为了使它向后兼容，你可以使用这个检查来确定WordPress是否至少是3.4版本。因此，在过渡到3.4的过程中，您可以通过以下方式支持这两个函数：

global $wp_version;
if ( version_compare( $wp_version, '3.4', '>=' ) ) 
	add_theme_support( 'custom-background' ); 
else
	add_custom_background( $args );

custom-logo

这个特性是在4.5版中首次引入的，该特性让主题支持主题Logo（Theme_Logo）。

add_theme_support( 'custom-logo' );

您可以使用以下方法添加默认参数：

add_theme_support( 'custom-logo', array(
    'height'      => 100,
    'width'       => 400,
    'flex-height' => true,
    'flex-width'  => true,
    'header-text' => array( 'site-title', 'site-description' ),
) );

menus

用 register_nav_menu() or register_nav_menus() 替代。

Feed Links

该功能支持在文章和评论的头部添加Automatic Feed Links，该功能在3.0版本中引入，用它来替代已经不推荐使用的automatic_feed_links()方法。

add_theme_support( 'automatic-feed-links' );

HTML5

该特性允许对搜索表单（search forms）,评论表单（ comment forms）,评论列表（ comment lists）, 画廊（gallery）和大标题（ caption）使用HTML5标签（HTML5 markup）。

add_theme_support( 'html5', array( 'comment-list', 'comment-form', 'search-form', 'gallery', 'caption', 'style', 'script' ) );

Title Tag

该功能允许插件和主题管理文档的标题，用它来替代已经不推荐使用的wp_title()方法。

add_theme_support( 'title-tag' );

Customize Selective Refresh Widgets

该功能允许对自定义程序中管理的小部件进行选择性刷新。这个特性在WordPress4.5中可用。详情见： Implementing Selective Refresh Support for Widgets。

add_theme_support( 'customize-selective-refresh-widgets' );

Starter Content

add_theme_support( 'starter-content', array(
    // Place widgets in the desired locations (such as sidebar or footer).
    // Example widgets: archives, calendar, categories, meta, recent-comments, recent-posts, 
    //                  search, text_business_info, text_about
    'widgets'     => array( 'sidebar-1' => array( 'search', 'categories', 'meta'), ),
    // Specify pages to create, and optionally add custom thumbnails to them.
    // Note: For thumbnails, use attachment symbolic references in {{double-curly-braces}}.
    // Post options: post_type, post_title, post_excerpt, post_name (slug), post_content, 
    //               menu_order, comment_status, thumbnail (featured image ID), and template
    'posts'       => array( 'home', 'about', 'blog' => array( 'thumbnail' => '{{image-cafe}}' ), ),
    // Create custom image attachments used as post thumbnails for pages.
    // Note: You can reference these attachment IDs in the posts section above. Example: {{image-cafe}}
    'attachments' => array( 'image-cafe' => array( 'post_title' => 'Cafe', 'file' => 'assets/images/cafe.jpg' ), ),
    // Assign options defaults, such as front page settings.
    // The 'show_on_front' value can be 'page' to show a specified page, or 'posts' to show your latest posts.
    // Note: Use page ID symbolic references from the posts section above wrapped in {{double-curly-braces}}.
    'options'     => array( 'show_on_front'  => 'page', 'page_on_front' => '{{home}}', 'page_for_posts' => '{{blog}}', ),
    // Set the theme mods.
    'theme_mods'  => array( 'panel_1' => '{{about}}' ),
    // Set up nav menus.
    'nav_menus'   => array( 'top' => array( 'name' => 'Top Menu', 'items' => array( 'link_home', 'page_about', 'page_blog' )), ),
) );

Responsive Embeds

自适应嵌入内容

Wide Alignment

该功能支持主题编辑器中启用“完全对齐”和“宽对齐”选项

add_theme_support( 'align-wide' );

Dark backgrounds

如果编辑器样式依赖于深色背景，则可以添加以下内容来调整UI的颜色，使其适用于深色背景：

add_theme_support( 'editor-styles' );
add_theme_support( 'dark-editor-style' );

注意，您不需要添加add_theme_support('editor styles');两次，但是需要存在该规则才能使暗色编辑器样式规则生效。

Disabling custom colors in block Color Palettes

add_theme_support( 'disable-custom-colors' );

Disabling custom font sizes

add_theme_support( 'disable-custom-font-sizes' );

Block Color Palettes

add_theme_support( 'editor-color-palette', array(
    array(
        'name' => __( 'strong magenta', 'themeLangDomain' ),
        'slug' => 'strong-magenta',
        'color' => '#a156b4',
    ),
    array(
        'name' => __( 'light grayish magenta', 'themeLangDomain' ),
        'slug' => 'light-grayish-magenta',
        'color' => '#d0a5db',
    ),
    array(
        'name' => __( 'very light gray', 'themeLangDomain' ),
        'slug' => 'very-light-gray',
        'color' => '#eee',
    ),
    array(
        'name' => __( 'very dark gray', 'themeLangDomain' ),
        'slug' => 'very-dark-gray',
        'color' => '#444',
    ),
) );

Block Font Sizes

add_theme_support( 'editor-font-sizes', array(
    array(
        'name' => __( 'Small', 'themeLangDomain' ),
        'size' => 12,
        'slug' => 'small'
    ),
    array(
        'name' => __( 'Regular', 'themeLangDomain' ),
        'size' => 16,
        'slug' => 'regular'
    ),
    array(
        'name' => __( 'Large', 'themeLangDomain' ),
        'size' => 36,
        'slug' => 'large'
    ),
    array(
        'name' => __( 'Huge', 'themeLangDomain' ),
        'size' => 50,
        'slug' => 'huge'
    )
) );

Editor styles

支持最新基于Block Editor的Gutenberg编辑器样式，它与经典编辑器（classic editor）中的工作方式略有不同。

在经典编辑器中，编辑器样式表直接加载到所见即所得编辑器的iframe中，没有任何更改。但是，块编辑器不使用iframes。为了确保您的样式只应用于编辑器的内容，我们通过有选择地重写或调整某些CSS选择器来自动转换编辑器样式。

例如, 如果你把 body { ... } 写在编辑器样式文件中, 它会被重写成 .editor-styles-wrapper { ... }。This also means that you should not target any of the editor class names directly.

Because it works a little differently, you need to opt-in to this by adding an extra snippet to your theme, in addition to the add_editor_style function:

add_theme_support( 'editor-styles' );

您无需过多更改编辑器样式； 大多数主题可以在经典编辑器和块编辑器中添加上面的代码片段并获得相似的结果。

Default block styles

核心块包括默认的结构样式。默认情况下，这些都加载在编辑器和前端中。这些样式的一个示例是为列块提供基本的CSS布局支持，没有这些CSS规则，编辑器的块布局将会错乱。

The block editor allows themes to opt-in to slightly more opinionated styles for the front end. An example of these styles is the default color bar to the left of blockquotes. If you’d like to use these opinionated styles in your theme, add theme support for wp-block-styles:

add_theme_support( 'wp-block-styles' );

Disabling the default block patterns.

WordPress comes with a number of block patterns built-in, themes can opt-out of the bundled patterns and provide their own set using the following code:

remove_theme_support( 'core-block-patterns' );

Enqueuing the editor style

使用add_editor_style函数将CSS放入队列并在编辑器屏幕上加载CSS。 对于经典编辑器，这是向编辑器添加样式所需的唯一功能。 对于新的块编辑器，您首先需要add_theme_support('editor-styles');。

add_editor_style( 'style-editor.css' );

参考

• theme-support
• add_theme_support