云策 WordPress 开发者社区

REST API 文档

Widgets

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

概述

本文档详细介绍了 WordPress REST API 中 Widgets 端点的数据结构和操作。核心内容包括 Widget 记录的字段定义（Schema）以及通过 REST API 进行检索、创建、更新和删除 Widget 的方法。

关键要点

  • Widget 记录包含多个字段，如 id（唯一标识符）、id_base（对应 widget-types 端点的 ID）、sidebar（所属侧边栏）、rendered（HTML 表示）、rendered_form（管理表单 HTML）、instance（实例设置）和 form_data（URL 编码的表单数据）。
  • 支持通过 GET /wp/v2/widgets 检索所有 Widget 或 GET /wp/v2/widgets/<id> 检索特定 Widget，可使用 context 和 sidebar 参数。
  • 创建 Widget 使用 POST /wp/v2/widgets，需提供 id、id_base、sidebar（必需）、instance 或 form_data 等参数。
  • 更新 Widget 使用 POST /wp/v2/widgets/<id>，参数与创建类似，用于修改现有 Widget。
  • 删除 Widget 使用 DELETE /wp/v2/widgets/<id>，可通过 force 参数强制移除或移至非活动侧边栏。

代码示例

GET /wp/v2/widgets
$ curl https://example.com/wp-json/wp/v2/widgets

GET /wp/v2/widgets/<id>
$ curl https://example.com/wp-json/wp/v2/widgets/<id>

DELETE /wp/v2/widgets/<id>
$ curl -X DELETE https://example.com/wp-json/wp/v2/widgets/<id>
📄 原文内容

Schema

The schema defines all the fields that exist within a widget 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.

id Unique identifier for the widget.

JSON data type: string

Context: view, edit, embed
id_base The type of the widget. Corresponds to ID in widget-types endpoint.

JSON data type: string

Context: view, edit, embed
sidebar The sidebar the widget belongs to.

JSON data type: string

Context: view, edit, embed
rendered HTML representation of the widget.

JSON data type: string

Read only

Context: view, edit, embed
rendered_form HTML representation of the widget admin form.

JSON data type: string

Read only

Context: edit
instance Instance settings of the widget, if supported.

JSON data type: object

Context: edit
form_data URL-encoded form data from the widget admin form. Used to update a widget that does not support instance. Write only.

JSON data type: string

Context:

Retrieve a Widget

Definition & Example Request

GET /wp/v2/widgets

Query this endpoint to retrieve a specific widget record.

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

Arguments

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

Default: view

One of: view, embed, edit

sidebar The sidebar to return widgets for.

Create a Widget

Arguments

<a href="#schema-id">id</a> Unique identifier for the widget.
<a href="#schema-id_base">id_base</a> The type of the widget. Corresponds to ID in widget-types endpoint.
<a href="#schema-sidebar">sidebar</a> The sidebar the widget belongs to.

Required: 1

Default: wp_inactive_widgets

<a href="#schema-instance">instance</a> Instance settings of the widget, if supported.
<a href="#schema-form_data">form_data</a> URL-encoded form data from the widget admin form. Used to update a widget that does not support instance. Write only.

Definition

POST /wp/v2/widgets

Retrieve a Widget

Definition & Example Request

GET /wp/v2/widgets/<id>

Query this endpoint to retrieve a specific widget record.

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

Arguments

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

Default: view

One of: view, embed, edit

Update a Widget

Arguments

<a href="#schema-id">id</a> Unique identifier for the widget.
<a href="#schema-id_base">id_base</a> The type of the widget. Corresponds to ID in widget-types endpoint.
<a href="#schema-sidebar">sidebar</a> The sidebar the widget belongs to.
<a href="#schema-instance">instance</a> Instance settings of the widget, if supported.
<a href="#schema-form_data">form_data</a> URL-encoded form data from the widget admin form. Used to update a widget that does not support instance. Write only.

Definition

POST /wp/v2/widgets/<id>

Example Request

Delete a Widget

Arguments

force Whether to force removal of the widget, or move it to the inactive sidebar.

Definition

DELETE /wp/v2/widgets/<id>

Example Request

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