云策 WordPress 开发者社区

REST API 文档

Nav_Menu_Items

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

概述

本文档详细介绍了 WordPress REST API 中 Nav_Menu_Items 端点的数据结构和操作。它定义了导航菜单项（nav_menu_item）记录的字段模式，并提供了列表、创建、检索、更新和删除菜单项的端点定义、参数和示例。

关键要点

  • Nav_Menu_Items 端点用于管理 WordPress 导航菜单项，支持 CRUD 操作（创建、读取、更新、删除）。
  • 每个菜单项包含多个字段，如 id、title、type、status、url 等，部分字段为只读（如 id、type_label、invalid）。
  • 字段具有 JSON 数据类型（如 string、integer、array、boolean）和上下文（view、edit、embed），影响 API 响应中的字段可见性。
  • 列表端点（GET /wp/v2/menu-items）支持多种查询参数，如 context、page、per_page、search、orderby 等，用于过滤和排序结果。
  • 创建（POST /wp/v2/menu-items）、检索（GET /wp/v2/menu-items/<id>）、更新（POST /wp/v2/menu-items/<id>）和删除（DELETE /wp/v2/menu-items/<id>）端点各有特定参数，如 title、type、menus 等。
  • type 字段指定菜单项来源类型，可选值包括 taxonomy、post_type、post_type_archive、custom。
  • status 字段表示菜单项状态，可选值包括 publish、future、draft、pending、private。
  • 使用 _filter 查询参数可自定义响应字段，但默认情况下响应包含所有模式定义的字段。

代码示例

// 列出所有菜单项
$ curl https://example.com/wp-json/wp/v2/menu-items

// 创建新菜单项
POST /wp/v2/menu-items
参数示例：{
  "title": "示例菜单项",
  "type": "custom",
  "url": "https://example.com"
}

// 检索特定菜单项
$ curl https://example.com/wp-json/wp/v2/menu-items/<id>

// 删除菜单项
$ curl -X DELETE https://example.com/wp-json/wp/v2/menu-items/<id>

注意事项

  • id、type_label、invalid 字段为只读，不能在创建或更新操作中设置。
  • context 参数控制响应字段，view 为默认值，embed 和 edit 可能包含额外字段。
  • 在创建和更新操作中，需确保参数如 type、status 使用有效值，否则可能导致错误。
  • 删除操作支持 force 参数，用于绕过回收站直接删除菜单项。
  • API 端点基于 WordPress REST API v2，确保站点已启用 REST API 功能。
📄 原文内容

Schema

The schema defines all the fields that exist within a nav_menu_item record. Any response from these endpoints can be expected to contain the fields below unless the `_filter` query parameter is used or the schema field only appears in a specific context.

title The title for the object.

JSON data type: string or object

Context: view, edit, embed
id Unique identifier for the object.

JSON data type: integer

Read only

Context: view, edit, embed
type_label The singular label used to describe this type of menu item.

JSON data type: string

Read only

Context: view, edit, embed
type The family of objects originally represented, such as "post_type" or "taxonomy".

JSON data type: string

Context: view, edit, embed

One of: taxonomy, post_type, post_type_archive, custom

status A named status for the object.

JSON data type: string

Context: view, edit, embed

One of: publish, future, draft, pending, private

parent The ID for the parent of the object.

JSON data type: integer

Context: view, edit, embed
attr_title Text for the title attribute of the link element for this menu item.

JSON data type: string

Context: view, edit, embed
classes Class names for the link element of this menu item.

JSON data type: array

Context: view, edit, embed
description The description of this menu item.

JSON data type: string

Context: view, edit, embed
menu_order The DB ID of the nav_menu_item that is this item's menu parent, if any, otherwise 0.

JSON data type: integer

Context: view, edit, embed
object The type of object originally represented, such as "category", "post", or "attachment".

JSON data type: string

Context: view, edit, embed
object_id The database ID of the original object this menu item represents, for example the ID for posts or the term_id for categories.

JSON data type: integer

Context: view, edit, embed
target The target attribute of the link element for this menu item.

JSON data type: string

Context: view, edit, embed

One of: _blank,

url The URL to which this menu item points.

JSON data type: string,
Format: uri

Context: view, edit, embed
xfn The XFN relationship expressed in the link of this menu item.

JSON data type: array

Context: view, edit, embed
invalid Whether the menu item represents an object that no longer exists.

JSON data type: boolean

Read only

Context: view, edit, embed
menus The terms assigned to the object in the nav_menu taxonomy.

JSON data type: integer

Context: view, edit
meta Meta fields.

JSON data type: object

Context: view, edit

List Nav_Menu_Items

Query this endpoint to retrieve a collection of nav_menu_items. The response you receive can be controlled and filtered using the URL query parameters below.

Definition

GET /wp/v2/menu-items

Example Request

$ curl https://example.com/wp-json/wp/v2/menu-items

Arguments

context Scope under which the request is made; determines fields present in response.

Default: view

One of: view, embed, edit

page Current page of the collection.

Default: 1

per_page Maximum number of items to be returned in result set.

Default: 100

search Limit results to those matching a string.
after Limit response to posts published after a given ISO8601 compliant date.
modified_after Limit response to posts modified after a given ISO8601 compliant date.
before Limit response to posts published before a given ISO8601 compliant date.
modified_before Limit response to posts modified before a given ISO8601 compliant date.
exclude Ensure result set excludes specific IDs.
include Limit result set to specific IDs.
offset Offset the result set by a specific number of items.
order Order sort attribute ascending or descending.

Default: asc

One of: asc, desc

orderby Sort collection by object attribute.

Default: menu_order

One of: author, date, id, include, modified, parent, relevance, slug, include_slugs, title, menu_order

search_columns Array of column names to be searched.
slug Limit result set to posts with one or more specific slugs.
status Limit result set to posts assigned one or more statuses.

Default: publish

tax_relation Limit result set based on relationship between multiple taxonomies.
One of: AND, OR
menus Limit result set to items with specific terms assigned in the menus taxonomy.
menus_exclude Limit result set to items except those with specific terms assigned in the menus taxonomy.
menu_order Limit result set to posts with a specific menu_order value.

Create a Nav_Menu_Item

Arguments

<a href="#schema-title">title</a> The title for the object.
<a href="#schema-type">type</a> The family of objects originally represented, such as "post_type" or "taxonomy".

Default: custom

One of: taxonomy, post_type, post_type_archive, custom

<a href="#schema-status">status</a> A named status for the object.

Default: publish

One of: publish, future, draft, pending, private

<a href="#schema-parent">parent</a> The ID for the parent of the object.
<a href="#schema-attr_title">attr_title</a> Text for the title attribute of the link element for this menu item.
<a href="#schema-classes">classes</a> Class names for the link element of this menu item.
<a href="#schema-description">description</a> The description of this menu item.
<a href="#schema-menu_order">menu_order</a> The DB ID of the nav_menu_item that is this item's menu parent, if any, otherwise 0.

Default: 1

<a href="#schema-object">object</a> The type of object originally represented, such as "category", "post", or "attachment".
<a href="#schema-object_id">object_id</a> The database ID of the original object this menu item represents, for example the ID for posts or the term_id for categories.
<a href="#schema-target">target</a> The target attribute of the link element for this menu item.
One of: _blank,
<a href="#schema-url">url</a> The URL to which this menu item points.
<a href="#schema-xfn">xfn</a> The XFN relationship expressed in the link of this menu item.
<a href="#schema-menus">menus</a> The terms assigned to the object in the nav_menu taxonomy.
<a href="#schema-meta">meta</a> Meta fields.

Definition

POST /wp/v2/menu-items

Retrieve a Nav_Menu_Item

Definition & Example Request

GET /wp/v2/menu-items/<id>

Query this endpoint to retrieve a specific nav_menu_item record.

$ curl https://example.com/wp-json/wp/v2/menu-items/<id>

Arguments

id Unique identifier for the post.
context Scope under which the request is made; determines fields present in response.

Default: view

One of: view, embed, edit

Update a Nav_Menu_Item

Arguments

<a href="#schema-id">id</a> Unique identifier for the post.
<a href="#schema-title">title</a> The title for the object.
<a href="#schema-type">type</a> The family of objects originally represented, such as "post_type" or "taxonomy".
One of: taxonomy, post_type, post_type_archive, custom
<a href="#schema-status">status</a> A named status for the object.
One of: publish, future, draft, pending, private
<a href="#schema-parent">parent</a> The ID for the parent of the object.
<a href="#schema-attr_title">attr_title</a> Text for the title attribute of the link element for this menu item.
<a href="#schema-classes">classes</a> Class names for the link element of this menu item.
<a href="#schema-description">description</a> The description of this menu item.
<a href="#schema-menu_order">menu_order</a> The DB ID of the nav_menu_item that is this item's menu parent, if any, otherwise 0.
<a href="#schema-object">object</a> The type of object originally represented, such as "category", "post", or "attachment".
<a href="#schema-object_id">object_id</a> The database ID of the original object this menu item represents, for example the ID for posts or the term_id for categories.
<a href="#schema-target">target</a> The target attribute of the link element for this menu item.
One of: _blank,
<a href="#schema-url">url</a> The URL to which this menu item points.
<a href="#schema-xfn">xfn</a> The XFN relationship expressed in the link of this menu item.
<a href="#schema-menus">menus</a> The terms assigned to the object in the nav_menu taxonomy.
<a href="#schema-meta">meta</a> Meta fields.

Definition

POST /wp/v2/menu-items/<id>

Example Request

Delete a Nav_Menu_Item

Arguments

id Unique identifier for the post.
force Whether to bypass Trash and force deletion.

Definition

DELETE /wp/v2/menu-items/<id>

Example Request

$ curl -X DELETE https://example.com/wp-json/wp/v2/menu-items/<id>