README

在创建主题时，我们发现我们不得不重复使用大量的结构化代码。因此，我们创建了此主题基类，其中包含我们所有的“通用”功能。

主要来说，这是一个抽象类集，处理了大量常见的逻辑，您可以轻松地启用/禁用一系列功能。它还与我们在常用第三方插件中使用的常用插件进行交互。

尽可能模块化，尽量不加载我们实际上不需要的更多代码。

如何操作

启动可挂钩类

主题基础包含一个合约，Hookable，要求类实现hooks()方法。这使得我们可以标准化调用add_action和add_filter的类。

要启动主题中的这些类，只需将类名添加到主主题类中的boot数组中。

/**
 * Boot the theme. 
 */
protected static array $boot = [
    Asset::class
];

声明WooCommerce支持

如果主题应支持WooCommerce，则在基础主题类中设置以启用WooCommerce支持

/**
 * Support WooCommerce
 */
public static bool $supports_woocommece = true;

支持自动Feed URL

默认情况下，我们禁用自动Feed URL。在我们的构建中，许多网站不需要它们。启用支持很容易。在主主题类中，只需设置

/**
 * Include automatic feed links
 */
public static bool $supports_feeds = true;

支持帖子缩略图

默认情况下，我们只为帖子设置了帖子缩略图支持。您可以选择包含其他帖子类型，或者完全禁用支持。在主主题类中，您可以将$supports_thumbnails属性设置为空数组以禁用，或添加其他键。

要完全禁用

/**
 * Disable post thumbnail support.
 */
public static array $supports_thumbnails = [];

要同时添加对页面的支持

/**
 * Add thumbnail support for specified post types.
 */
public static array $supports_thumbnails = [
    'post',
    'page'
];

要添加对所有自定义帖子类型的支持

/**
 * Allow thumbnail support for all post types.
 */
public static array $supports_thumbnails = ['*'];

更改自定义Logo支持

默认情况下，我们支持自定义Logo。您可能想要更改尺寸或完全禁用。在主主题类中，将$custom_logo设置为空数组或false以完全禁用，或更改选项以调整。

/**
 * Add support for a custom logo.
 */
public static array $custom_logo = [
	'width'       => 400,
	'height'      => 50,
	'flex-height' => true,
	'flex-width'  => true,
];

添加帖子格式支持

默认情况下，我们不提供对帖子格式的支持。添加它就像将您想要支持的格式添加到$post_formats数组中一样简单。

/**
 * Add support for post formats.
 *
 * @link https://developer.wordpress.org/themes/functionality/post-formats/
 *
 * @var array
 */
public static array $post_formats = [
    'aside',
    'status',
];

添加FacetWP Facets

通过在代码中注册Facets，我们可以本地化它们，并使它们在不同环境中加载变得容易。您需要创建一个Facet类，并将其包含在主主题类中。

我们建议您在主题中创建一个子文件夹Facets/来存储您的Facets。在UI界面中创建您的Facets很简单。获取导出代码并将其轻松移植到PHP中。

每个Facet将是一个独立的文件。要创建一个分类Facet，这可能看起来像

文件： Facets/Category.php

<?php

namespace Theme\Facets;

use BernskioldMedia\WP\ThemeBase\FacetWp\Facet;

class Category extends Facet {

    protected static function get_data(): array {
        return [
            // Facet details.
        ];
    }
}

然后，在主主题类中，加载该类

use Theme\Facets\Category;

/**
 * Include a list of facets in this plugin (For Facet WP) to
 * load them with the theme.
 */
public static array $facets = [
    Category::class,
];

添加自定义设置

该框架提供了一种简单的方法，通过一个抽象类和简化的加载来添加新的自定义设置。我们建议创建一个目录Customizer/来存放您的类。

抽象自定义设置类不在乎您是否添加了复杂的部分/设置设置，或者只是一个单独的设置。但为了保持整洁，请尽量按视觉部分表示将设置分组到类中。

文件： Customizer/My_Section.php

<?php

namespace Theme\Customizer;

use BernskioldMedia\WP\ThemeBase\Customizer\Customizer_Settings;

class My_Section extends Customizer_Settings {

    /**
	 * The prefix that we prefix all settings and sections with.
	 */
	protected static string $settings_prefix = 'my-theme';

    /**
	 * Extend this method where you'll add the
	 * sections, settings and controls.
	 */
    protected function setup(): void {
        //
    }

}

然后，在主主题类中，加载该类

use Theme\Customizer\My_Section;

/**
 * Include a list of customizer section classes to
 * load them with the theme.
 */
public static array $customizer_sections = [
    My_Section::class,
];

添加ACF字段分组

通过在代码中注册标签，我们不仅可以本地化它们，还可以在不同的环境之间轻松加载。您需要创建一个字段分组类，并将其包含在主主题类中。

我们建议您在主题中创建一个子文件夹 Field_Groups/ 来存储您的分组。在ACF UI界面中创建字段分组很简单。获取PHP导出代码，然后将其保存到主题中。

注意：在可能的情况下，我们真的希望将逻辑保存到插件而不是主题中。但是，有一些有效的用例是将设置存储在主题中。这是少数但有效的情况之一。

加载字段分组时，我们会自动检查ACF是否可用和激活。

每个字段分组将是一个独立的文件。要创建字段分组，它可能看起来像

文件： Field_Groups/My_Group.php

<?php

namespace Theme\Field_Groups;

use BernskioldMedia\WP\ThemeBase\Acf\Field_Group;

class My_Group extends Field_Group {

    protected static function get_data(): array {
        return [
            // array from the acf_add_local_field_group() function in the export code.
        ];
    }
}

然后，在主主题类中，加载该类

use Theme\Field_Groups\My_Group;

/**
 * Include a list of ACF Field Group classes to
 * load them with the theme.
 */
public static array $field_groups = [
    My_Group::class,
];

添加自定义图片尺寸

要将自定义图片尺寸添加到主题中，请将其追加到主主题类中的 $sizes 数组。参数取自 add_image_size 文档。

/**
 * Custom Image Sizes
 */
protected static array $sizes = [
    'xlarge' => [
		'width'  => 2048,
		'height' => '',
		'crop'   => true,
	],
];

注册菜单位置

通过一个辅助函数来处理主要逻辑，添加新菜单位置变得很简单。您只需要提供一个包含位置 => 人名对的数组。为了支持本地化，这是在函数中完成的。

/**
 * Get the navigation menus locations to register on the site.
 * Leave empty not to register any.
 *
 * Takes a key => value format of: location-key => Human Label
 */
protected static function get_menu_locations(): array {
	return [
	    'primary-menu' => __( 'Primary Menu', 'TEXTDOMAIN' ),
	];
}

自定义登录样式

要添加自定义登录样式，请将 Has_Custom_Login 特质包含在主主题类中，该类继承自 Base_Theme 或 Child_Theme_Base。

use \BernskioldMedia\WP\ThemeBase;

class MyTheme extends Base_Theme {
    use Login\Has_Custom_Login;

    //...
}

这将加载来自 assets/styles/dist/login.css 文件夹的样式表，以及默认加载为网站设置的定制徽标。

您可以通过以下方式在主主题类中禁用加载自定义徽标

use \BernskioldMedia\WP\ThemeBase;

class MyTheme extends Base_Theme {
    use Login\Has_Custom_Login;
    
    protected static bool $disable_custom_login_logo = true;

    // ... my code

}

注册资源

多亏了资源管理器类，注册资源变得很容易。您可以使用三种方法之一，具体取决于您想要将资源排队的位置。

• public() - 用于公共页面。
• admin() - 用于管理页面。
• block_editor() - 特别是在块编辑器中。

这些都返回一个 Asset 兼容对象数组。这可以是 Style 或 Script（或见下文中的块编辑器）。

全局资源方法

脚本和样式都继承的资源类包括以下全局方法

::make(string $name) - 创建资源并将其句柄/名称分配给它。 ->file(string $file_name) - 指定资源相对于基本脚本/样式文件夹的位置。 ->version(string $version) - 允许您为资源传递一个版本。默认情况下，如果没有显式设置，它使用主题版本。 ->dependencies(array $dependencies = []) - 允许您传递必须在资源之前加载的依赖项名称。 ->if(callable $function) - 允许您传递一个带有条件匿名函数，以确定何时排队此资源。

加载样式

Style 类有一个额外的方法，可用于自定义

->media(string $media_type) - 允许您设置应加载样式的CSS媒体。如果未设置，默认为 "all"。

加载脚本

Script 类有一个额外的方法，可用于自定义

->in_footer(bool $in_footer = true) - 允许您指定是否在页脚中加载脚本。如果未设置，默认在页脚中加载。

资源加载示例

在本质上，这就是您需要加载脚本或样式的内容。

use BernskioldMedia\WP\ThemeBase\Assets\Style;
use BernskioldMedia\WP\ThemeBase\Assets\Script;

public static function public(): array {
    return [
        Style::make('theme-screen')->file('screen.css'),
        Script::make('theme-scripts')->file('theme.js'),
        // ...
    ];
}

根据规则有条件地加载，您可以这样做。请注意，资产将被始终注册，但只有当条件满足时才会入队。

use BernskioldMedia\WP\ThemeBase\Assets\Style;

public static function public(): array {
    return [
        Style::make('post-template')
            ->file('templates/post.css')
            ->if(function() {
                return in_post_type_archive('post');
            }),
        // ...
    ];
}

以下是一个加载使用大多数可用方法的脚本的示例

use BernskioldMedia\WP\ThemeBase\Assets\Script;

public static function public(): array {
    return [
        Script::make('alpinejs')
            ->file('vendor/alpinejs.js')
            ->version('3.7.1')
            ->dependencies(['theme-scripts']),
        // ...
    ];
}

加载块编辑器脚本

在块编辑器中加载脚本时，需要将 in_footer 参数设置为 false。在 block_editor 方法中，使用 Block_Editor_Script 类而不是 Script 来确保这一点始终满足。