README

为 WordPress 项目提供自定义文章类型和分类助手类。

通过数组表示法注册自定义文章类型和分类。标签将相应设置。目前支持英语、德语和荷兰语。
通过参数列表更改前后端文章的查询参数，例如，使用 query 选项设置自定义文章排序。
通过参数列表更改后端文章的管理列。
使用 page_for_archive 选项将特定页面设置为自定义文章类型的存档页面。
在保存文章时动态设置文章的 slug。

安装

您可以通过 Composer 安装此包。

composer require mindkomm/types

注册文章类型

<?php

/**
 * Register post types for your theme.
 *
 * Pass a an array of arrays to the registration function.
 */
add_action( 'init', function() {
    Types\Post_Type::register( [
        // Always use an English lowercase singular name to name a post type.
        'example' => [
            'name_singular' => 'Example',
            'name_plural'   => 'Examples',
            'args'          => [
                /**
                 * For a list of possible menu-icons see
                 * https://developer.wordpress.org/resource/dashicons/
                 */
                'menu_icon'    => 'dashicons-building',
                'hierarchical' => false,
                'has_archive'  => false,
                'supports'     => [
                    'title',
                    'editor',
                ],
                // Whether post is accessible in the frontend
                'public'       => false,
            ],
            'admin_columns' => [
                'date' => false,
            ],
        ],
    ] );
} );

使用 args 参数传递给 register_post_type 的参数。使用 name_singular 和 name_plural 参数生成后端中的标签。

您可以使用更多选项

查询

用于在前后端查询此文章类型的参数。您可以使用此选项定义排序顺序。以下是一个示例，对于文章类型 event，我们希望根据名为 date_start 的自定义字段的值对文章进行排序。

'query' => [
    'meta_key' => 'date_start',
    'orderby'  => 'meta_value_num',
    'order'    => 'DESC',
],

如果要在前后端使用不同的查询，可以使用单独的 frontend 和 backend 键。

'query' => [
    'frontend' => [
        'meta_key' => 'date_start',
        'orderby'  => 'meta_value_num',
        'order'    => 'ASC',
    ],
    'backend'  => [
        'meta_key' => 'date_start',
        'orderby'  => 'meta_value_num',
        'order'    => 'DESC',
    ],
],

如果只使用一个键并省略另一个，则查询将仅应用于您选择的内容。

管理列

用于在后台添加和删除管理列的参数。传递包含列名称和参数的关联数组。

以下是一个自定义文章类型 event 的示例。

'admin_columns' => [
    'date'       => false,
    'date_start' => [
        'title'     => 'Start Date',
        'transform' => function( $value ) {
            return date_i18n(
                get_option( 'date_format' ),
                DateTime::createFromFormat( 'Ymd', $value )->getTimeStamp()
            );
        },
    ],
    'location'   => [
        'title'      => 'Location',
        'sortable'   => true,
        'searchable' => true,
        'transform'  => function( $post_id ) {
            return get_the_title( $post_id );
        },
    ],
    'width' => [
        'title'    => 'Width',
        'sortable' => true,
        'orderby'  => 'meta_value_num',
    ],
],

以下是可以使用的参数

标题 – (字符串) 用于列的标题。默认为空。
transform – (可调用函数) 用于显示值的功能。这里定义的函数将接收一个 $value 参数，你可以对其进行转换。例如，如果你在文章元数据中保存了一个文章ID，你可以显示文章的标题。默认值为 null。
type – (字符串) 列的类型。可以是 meta、acf、thumbnail、image 或 custom 之一。默认值为 meta。
sortable – (布尔值) 是否可排序。默认值为 false。
orderby – (字符串) 当使用 sortable 参数时，根据什么排序。无需提供 meta_key 参数，因为它会自动设置。默认值为 meta_value。
searchable – (布尔值) 是否可搜索。在搜索文章列表时将包括元数据值。仅在默认类型为 meta 时应用。默认值为 false。
column_order – (整数) 用于排序的顺序号。你可以使用它来更改列的顺序。默认值为 10。

如果你需要更多定义管理员列的可能性，可以使用出色的 Admin Columns 插件。

类型

type 参数定义了如何解释你的列。存在以下类型

meta
acf
thumbnail
image
custom

meta 和 acf 类型

使用 meta 类型时，列名是你想要显示的元数据字段的名称。

你还可以使用 acf 作为类型，如果你使用高级自定义字段（Advanced Custom Fields），并且想要将其过滤器应用到值上。

thumbnail 类型

使用此键来显示文章的特色图片缩略图。

'location' => [
    'thumbnail' => true,
],

你还可以设置宽度和高度。默认值为 80 × 80 像素。

'location' => [
    'thumbnail'    => [
        'width'  => 100,
        'height' => 100,
    ],
],

image 类型

此类型允许你显示除了特色图片之外的图片。此类型还将使用列的键从文章的元数据值中获取 附件ID。

'admin_columns' => [
    'profile_image' => [
        'title'  => 'Profile image',
        'type'   => 'image',
    ],
],

默认情况下，它将显示缩略图大小。如果你想要请求不同的大小，可以使用 image_size 参数。

'admin_columns' => [
    'profile_image' => [
        'title'      => 'Profile image',
        'type'       => 'image',
        'image_size' => 'medium',
    ],
],

如果你想要限制图片的宽度和高度，你可以为 width 和 height 提供像素值。

'admin_columns' => [
    'profile_image' => [
        'title'  => 'Profile image',
        'type'   => 'image',
        'width'  => 100,
        'height' => 100,
    ],
],

custom 类型

如果你想要进行自定义操作，可以使用 custom 类型。如果你使用 custom 类型，你需要提供一个 value，它是一个接收文章ID作为唯一参数的回调函数。

在这个例子中，我们调用一个函数，从文章的某个特定块中提取属性值。

'email' => [
    'title' => __( 'Email', 'theme-module-teammember' ),
    'type'  => 'custom',
    'value' => function( $post_id ) {
        return $this->get_block_attribute( $post_id, 'email' );
    },
],

现有列和列顺序

你也可以更新或隐藏现有列。可以使用 title 和 column_order 参数更新现有列。

如果你想要更改现有列的标题，请使用 title 属性。

'admin_columns' => [
    'title' => [
        'title' => 'Event title',
    ],
],

如果你想要移动列，你可以使用 column_order 参数。在这个例子中，我们将把 date 列移动到末尾。

'admin_columns' => [
    'date' => [
        'column_order' => 100,
    ],
],

默认顺序为 10。因此，如果您想将像缩略图这样的列移动到开头，可以使用 5。

'admin_columns' => [
    'thumbnail' => [
        'column_order' => 5,
    ],
],

要隐藏现有列，可以使用 false。

'admin_columns' => [
    'date' => false,
],

page_for_archive

page_for_archive 选项允许您为自定义文章类型设置特定的页面作为存档页面。

'event' => [
    'args' => [
        'public' => true,
    ],
    'page_for_archive' => [
        'post_id'            => get_option( 'page_for_event' ),
        'is_singular_public' => false,
    ],
],

在此示例中，存储在 page_for_event 选项中的页面 ID 将作为 event 文章类型的存档页面。

每次您更改此选项时，都需要 刷新您的永久链接。

幕后，Types 在注册文章类型时使用 has_archive 选项，并设置您在 page_for_archive 选项中传递的页面的 slug。

is_singular_public

is_singular_public 选项允许您设置是否应在前端访问此文章类型的单页模板。然后，单页模板请求将被重定向到存档页面。我们不能使用 public 或 publicly_queryable 选项，因为那样存档页面也不会工作。

customizer_section

如果您想使 Types 在自定义设置器中注册一个选项来选择用作存档的页面，可以使用 customizer_section 参数。

'event' => [
    'page_for_archive' => [
        'post_id'            => get_option( 'page_for_event' ),
        'customizer_section' => 'event',
    ],
],

使用 customizer_section，您可以在自定义设置器中定义选项应显示的哪个部分。这需要是一个现有的部分。这样，您可以自己决定是否希望为每个自定义文章类型创建一个单独的自定义设置器部分，或者是否希望将所有自定义文章类型的页面列在同一个部分中。

show_post_state

Types 将在页面概览中为选定的页面显示文章状态。如果您想禁用此功能，请使用 show_post_state 选项。

'event' => [
    'page_for_archive' => [
        'post_id'    => get_option( 'page_for_event' ),
        'show_post_state' => false,
    ],
],

在模板中使用页面

要使用该页面，您将在存档页面中使用它，现在您可以将页面用作主要文章。

archive-event.php

$post = get_post( get_option( 'page_for_event' ) );

更新现有文章类型

更改文章类型的设置

使用 update() 函数更改现有文章类型的设置。以下是一个将文章设置更改为在前端不可直接访问的示例。

functions.php

Types\Post_Type::update( [
    'post' => [
        'args' => [
            'public'            => false,
            'show_ui'           => true,
            'show_in_nav_menus' => true,
        ],
        'admin_columns' => [
            'date' => false,
        ],
    ],
] );

update() 函数接受一个关联数组，包含文章类型及其参数。确保在使用此函数之前使用 init 钩子。

更改文章类型支持

请注意，无法通过 update() 函数更改文章类型支持功能。要删除现有功能的支持，您必须使用 remove_post_type_support 函数。

add_action( 'init', function() {
    remove_post_type_support( 'post', 'thumbnail' );
} );

同样，如果您想添加功能，应通过 add_post_type_support 函数来完成。

add_post_type_support( 'page', 'excerpt' );

重命名文章类型

有时您可能希望重命名现有的文章类型，以更好地反映其用途。

functions.php

Types\Post_Type::rename( 'post', 'Beispiel', 'Beispiele' );

rename() 函数接受一个文章类型作为第一个参数，新单数名称作为第二个参数，以及文章类型的多数形式名称作为第三个参数。如果您省略第三个参数，则第二个参数将用作复数形式。在使用此函数之前，请确保在 init 钩子之前使用。

这实际上是一个简写函数，用于

Types\Post_Type::update( [
    'post' => [
        'name_singular' => 'Beispiel',
        'name_plural'   => 'Beispiele',
    ],
] );

如果您只想重命名一个标签，例如菜单标签，则可以使用 post_type_labels_{$post_type} 过滤器。以下是一个更改帖子菜单名称的示例

add_filter( 'post_type_labels_post', function( $labels ) {
    $labels->menu_name = 'Aktuelles';

    return $labels;
}, 11 );

更改现有文章类型的行政列设置

要更改现有文章类型（如 post 或 page）的行政列设置，可以使用接受文章类型及其行政列设置关联数组的 admin_columns() 函数。

以下是一个示例，禁用了日期、评论和作者列，并添加了缩略图

Types\Post_Type::admin_columns( [
    'page' => [
        'date'         => false,
        'comments'     => false,
        'author'       => false,
        'thumbnail'    => [
            'width'  => 80,
            'height' => 80,
        ],
    ],
] );

注册分类法

<?php

use Types\Taxonomy;

/**
 * Register taxonomies for your theme.
 *
 * Pass a an array of arrays to the registration function.
 */
add_action( 'init', function() {
    Taxonomy::register( [
        // Always use an English lowercase singular name to name a taxonomy.
        'example_tax' => [
            'name_singular'  => 'Example Category',
            'name_plural'    => 'Example Categories',
            // For which post types do you want to register this taxonomy?
            'for_post_types' => [ 'example' ],
            'args'           => [
                // Hide the meta box from the edit view
                // 'meta_box_cb' => false,
                //
                // Make it selectable in the navigation menus
                // 'show_in_nav_menus' => true,
            ],
        ],
    ] );
} );

args 参数用于传递给 register_taxonomy 的参数。使用 for_post_types 参数将分类法分配给某些文章类型。使用 name_singular 和 name_plural 参数在后台生成标签。

更新现有分类法

更改分类法的设置

使用 update() 函数更改现有分类法的设置。以下是一个将分类法的设置更改为不让它们在前端直接访问的示例。

functions.php

Types\Taxonomy::update( [
    'category' => [
        'args' => [
            'public'            => false,
            'show_ui'           => true,
            'show_in_nav_menus' => true,
        ],
    ],
] );

update() 函数接受一个包含分类法和它们的参数的关联数组。确保在使用此函数之前，在 init 钩子之前使用。

重命名分类法

有时您可能希望重命名现有的分类法，以更好地反映其用途。

functions.php

Types\Taxonomy::rename( 'category', 'Topic', 'Topics' );

rename() 函数接受一个分类法作为第一个参数，分类法的新单数名称作为第二个参数，以及分类法的新多数形式名称作为第三个参数。如果您省略第三个参数，则第二个参数将用作复数形式。在使用此函数之前，请确保在 init 钩子之前使用。

这实际上是一个简写函数，用于

Types\Taxonomy::update( [
    'category' => [
        'name_singular' => 'Topic',
        'name_plural'   => 'Topics,
    ],
] );

如果您只想重命名一个标签，例如菜单标签，则可以使用 taxonomy_labels_{$post_type} 过滤器。以下是一个更改帖子菜单名称的示例

add_filter( 'taxonomy_labels_category', function( $labels ) {
    $labels->menu_name = 'Topics';

    return $labels;
}, 11 );

注销分类法

如果您想注销某些文章类型的分类法，最好通过 unregister_taxonomy_for_object_type() 函数来完成。

/**
 * Unregister post categories and post tags.
 */
add_action( 'init', function() {
    unregister_taxonomy_for_object_type( 'category', 'post' );
    unregister_taxonomy_for_object_type( 'post_tag', 'post' );
} );

自定义帖子别名

有时在保存帖子时您可能想覆盖帖子别名。可能的用例

常见的帖子复制插件通常只将 -copy 或 -2 作为后缀添加到帖子别名中。您想使用自己的模式。
多个帖子具有相同的名称，但它们的元数据不同。例如，活动帖子可能有不同的日期。您想自动将活动的日期添加到帖子别名中。

要初始化，您需要创建 Post_Slug 的实例并调用 init() 函数

$post_slugs = new Types\Post_Slug();
$post_slugs->init();

以下是一个自定义文章短链接的示例，适用于文章类型 course，其中您希望链接永久地址由文章标题构建。在这种情况下，文章标题将是课程编号。

$post_slugs = new Types\Post_Slug();
$post_slugs->init();

$post_slugs->register( [
    'course' => function( $post_slug, $post_data, $post_id ) {
        return $post_data['post_title'];
    },
] );

在回调中不需要使用 sanitize_title，因为该类内部已经使用了该函数。

这是前面提到的活动文章的另一个示例。

$post_slugs->register_suffix_date( [
    'event' => [
        'meta_key' => 'date_start',
    ],
] );

register_suffix_date 函数是一个特殊函数，它使得从文章的元数据中提取日期并将其附加到短链接中变得更容易。该函数接受一个包含文章类型及其函数参数的关联数组。

meta_key – 用于定义使用的元键名称。默认 date_start。
input_format – 定义元值的日期格式。默认 Ymd。
output_format – 定义用于后缀的输出日期格式。默认 Y-m-d。

支持

这是我们在 MIND 开发 WordPress 主题时使用的库。您可以使用它，但目前在技术上我们不提供任何支持。

mindkomm / theme-lib-custom-types

维护者

详细信息

README

目录

安装

注册文章类型

查询

管理列

类型

meta 和 acf 类型

thumbnail 类型

image 类型

custom 类型

现有列和列顺序

page_for_archive

is_singular_public

customizer_section

show_post_state

在模板中使用页面

更新现有文章类型

更改文章类型的设置

更改文章类型支持

重命名文章类型

更改现有文章类型的行政列设置

注册分类法

更新现有分类法

更改分类法的设置

重命名分类法

注销分类法

自定义帖子别名

支持