自定义内容类型

最后更新于:2021-11-29 13:02:13

Adding REST API Support For Custom Content Types

REST API可以使用与默认文章类型或分类术语控制器相同的控制器,为gc/v2namespace内的自定义文章类型和自定义分类创建路由。或者,您可以使用自己的控制器和命名空间。本文将涵盖使用自定义内容类型API路由的默认控制器。这是最简单的方法,并确保与第三方兼容的几率最高。

使用REST API支持注册自定义文章类型

When registering a custom post type, if you want it to be available via the REST API you should set 'show_in_rest' => true in the arguments passed to register_post_type. Setting this argument to true will add a route in the gc/v2 namespace.

/**
 * Register a book post type, with REST API support
 *
 * Based on example at: https://docs.gechiui.com/codex/Function_Reference/register_post_type
 */
add_action( 'init', 'my_book_cpt' );
function my_book_cpt() {
    $args = array(
      'public'       => true,
      'show_in_rest' => true,
      'label'        => 'Books'
    );
    register_post_type( 'book', $args );
}

您可以选择设置rest_base参数来更改基本网址,否则该网址将默认为文章类型的名称。在下面的示例中,“书籍”用作rest_base的值。这将使路由gc-json/gc/v2/books的URL成为默认的,而不是gc-json/gc/v2/book/,这将是默认的。

此外,您可以传递rest_controller_class的参数。此类必须是GC_REST_Controller的子类。默认情况下,GC_REST_Posts_Controller用作控制器。如果您使用的是自定义控制器,那么您可能不在gc/v2命名空间内。

以下是注册文章类型的示例,带有完整标签、对REST API的支持、自定义rest_base和默认控制器的显式注册表:

/**
 * Register a book post type, with REST API support
 *
 * Based on example at: https://docs.gechiui.com/codex/Function_Reference/register_post_type
 */
add_action( 'init', 'my_book_cpt' );
function my_book_cpt() {
  $labels = array(
    'name'               => _x( 'Books', 'post type general name', 'your-plugin-textdomain' ),
    'singular_name'      => _x( 'Book', 'post type singular name', 'your-plugin-textdomain' ),
    'menu_name'          => _x( 'Books', 'admin menu', 'your-plugin-textdomain' ),
    'name_admin_bar'     => _x( 'Book', 'add new on admin bar', 'your-plugin-textdomain' ),
    'add_new'            => _x( 'Add New', 'book', 'your-plugin-textdomain' ),
    'add_new_item'       => __( 'Add New Book', 'your-plugin-textdomain' ),
    'new_item'           => __( 'New Book', 'your-plugin-textdomain' ),
    'edit_item'          => __( 'Edit Book', 'your-plugin-textdomain' ),
    'view_item'          => __( 'View Book', 'your-plugin-textdomain' ),
    'all_items'          => __( 'All Books', 'your-plugin-textdomain' ),
    'search_items'       => __( 'Search Books', 'your-plugin-textdomain' ),
    'parent_item_colon'  => __( 'Parent Books:', 'your-plugin-textdomain' ),
    'not_found'          => __( 'No books found.', 'your-plugin-textdomain' ),
    'not_found_in_trash' => __( 'No books found in Trash.', 'your-plugin-textdomain' )
  );

  $args = array(
    'labels'             => $labels,
    'description'        => __( 'Description.', 'your-plugin-textdomain' ),
    'public'             => true,
    'publicly_queryable' => true,
    'show_ui'            => true,
    'show_in_menu'       => true,
    'query_var'          => true,
    'rewrite'            => array( 'slug' => 'book' ),
    'capability_type'    => 'post',
    'has_archive'        => true,
    'hierarchical'       => false,
    'menu_position'      => null,
    'show_in_rest'       => true,
    'rest_base'          => 'books',
    'rest_controller_class' => 'GC_REST_Posts_Controller',
    'supports'           => array( 'title', 'editor', 'author', 'thumbnail', 'excerpt', 'comments' )
  );

  register_post_type( 'book', $args );
}

If you are using a custom rest_controller_class, then the REST API is unable to automatically determine the route for a given post. In this case, you can use the rest_route_for_post filter to provide this information. This allows for your custom post type to be properly formatted in the Search endpoint and enables automated discovery links.

function my_plugin_rest_route_for_post( $route, $post ) {
    if ( $post->post_type === 'book' ) {
        $route = '/gc/v2/books/' . $post->ID;
    }

    return $route;
}
add_filter( 'rest_route_for_post', 'my_plugin_rest_route_for_post', 10, 2 );

使用REST API支持注册自定义分类

Registering a custom taxonomy with REST API support is very similar to registering a custom post type: pass 'show_in_rest' => true in the arguments passed to register_taxonomy. You may optionally pass rest_base to change the base url for the taxonomy’s routes.

分类的默认控制器是GCGC_REST_Terms_Controller。如果您选择使用自定义控制器,您可以使用rest_controller_class修改此操作。

以下是如何在REST API支持下注册自定义分类的示例:

/**
 * Register a genre post type, with REST API support
 *
 * Based on example at: https://docs.gechiui.com/codex/Function_Reference/register_taxonomy
 */
add_action( 'init', 'my_book_taxonomy', 30 );
function my_book_taxonomy() {

  $labels = array(
    'name'              => _x( 'Genres', 'taxonomy general name' ),
    'singular_name'     => _x( 'Genre', 'taxonomy singular name' ),
    'search_items'      => __( 'Search Genres' ),
    'all_items'         => __( 'All Genres' ),
    'parent_item'       => __( 'Parent Genre' ),
    'parent_item_colon' => __( 'Parent Genre:' ),
    'edit_item'         => __( 'Edit Genre' ),
    'update_item'       => __( 'Update Genre' ),
    'add_new_item'      => __( 'Add New Genre' ),
    'new_item_name'     => __( 'New Genre Name' ),
    'menu_name'         => __( 'Genre' ),
  );

  $args = array(
    'hierarchical'          => true,
    'labels'                => $labels,
    'show_ui'               => true,
    'show_admin_column'     => true,
    'query_var'             => true,
    'rewrite'               => array( 'slug' => 'genre' ),
    'show_in_rest'          => true,
    'rest_base'             => 'genre',
    'rest_controller_class' => 'GC_REST_Terms_Controller',
  );

  register_taxonomy( 'genre', array( 'book' ), $args );

}

If you are using a custom rest_controller_class, then the REST API is unable to automatically determine the route for a given term. In this case, you can use the rest_route_for_term filter to provide this information. This allows for your custom taxonomy to be properly formatted in the Search endpoint and enables automated discovery links.

function my_plugin_rest_route_for_term( $route, $term ) {
    if ( $term->taxonomy === 'genre' ) {
        $route = '/gc/v2/genre/' . $term->term_id;
    }

    return $route;
}
add_filter( 'rest_route_for_term', 'my_plugin_rest_route_for_term', 10, 2 );

向现有内容类型添加REST API支持

如果您需要为您无法控制的自定义文章类型或自定义分类添加REST API支持,例如您正在使用的主题或插件,您可以使用自GeChiUI版本4.6.0以来存在的register_post_type_args过滤器钩子。

/**
 * Add REST API support to an already registered post type.
 */
add_filter( 'register_post_type_args', 'my_post_type_args', 10, 2 );

function my_post_type_args( $args, $post_type ) {

    if ( 'book' === $post_type ) {
        $args['show_in_rest'] = true;

        // Optionally customize the rest_base or rest_controller_class
        $args['rest_base']             = 'books';
        $args['rest_controller_class'] = 'GC_REST_Posts_Controller';
    }

    return $args;
}

对于自定义分类,它几乎是一样的。您可以使用自GeChiUI 4.4.0版本以来存在的register_taxonomy_args过滤器。

/**
 * Add REST API support to an already registered taxonomy.
 */
add_filter( 'register_taxonomy_args', 'my_taxonomy_args', 10, 2 );

function my_taxonomy_args( $args, $taxonomy_name ) {

    if ( 'genre' === $taxonomy_name ) {
        $args['show_in_rest'] = true;

        // Optionally customize the rest_base or rest_controller_class
        $args['rest_base']             = 'genres';
        $args['rest_controller_class'] = 'GC_REST_Terms_Controller';
    }

    return $args;
}

分类和自定义文章类型在GeChiUI中有一个内置关联,但如果您想在两种自定义文章类型之间建立联系怎么办?GeChiUI本身不正式支持这一点,但我们可以使用_link关系在任意内容类型之间创建自己的连接。