ServerSideRender 是一个组件，用于在服务器端渲染动态区块的预览，以显示在编辑器中。在区块的 edit 函数中使用服务器端渲染时，应仅限于严重依赖现有 PHP 渲染逻辑、且该逻辑与数据高度耦合的区块，尤其是在没有可用端点的情况下。

当旧版区块作为向后兼容措施提供时，也可以使用 ServerSideRender，而无需重写该区块可能依赖的已弃用代码。

ServerSideRender 应被视为一种回退或遗留机制，不适合基于它开发新功能。

新区块应与任何必要的 REST API 端点一起构建，以便可以在 edit 函数中使用 JavaScript 进行客户端渲染。这能提供最佳用户体验，而不是依赖使用 PHP render_callback。渲染所需的逻辑应包含在端点中，从而使客户端 JavaScript 与服务器端 PHP 逻辑之间的差异最小。

此包仅用于 WordPress 核心。欢迎在你自己的项目中使用它，但请注意它可能永远不会拥有完整文档。

安装

安装模块

npm install @wordpress/server-side-render --save

此包假定你的代码将在 ES2015+ 环境中运行。如果你使用的环境对此类语言特性和 API 的支持有限或完全不支持，则应在你的代码中包含 @wordpress/babel-preset-default 附带的 polyfill。

API

default

已弃用 请改用 ServerSideRender 非默认导出。

用于在使用 wp 全局命名空间时兼容 ServerSideRender 组件的兼容层。

用法

import ServerSideRender from '@wordpress/server-side-render';

ServerSideRender

一个为区块渲染服务器端内容的组件。

注意：在适用时，URL 查询将包含当前文章 ID。这对于依赖当前文章上下文进行渲染的区块很有用。

用法

import { ServerSideRender } from '@wordpress/server-side-render';
// WordPress 6.8 及更早版本的旧版导入
// import { default as ServerSideRender } from '@wordpress/server-side-render';

function Example() {
    return (
        <ServerSideRender
            block="core/archives"
            attributes={ { showPostCounts: true } }
            urlQueryArgs={ { customArg: 'value' } }
            className="custom-class"
        />
    );
}

参数

  • props ServerSideRenderWithPostIdProps：组件属性。
  • props.urlQueryArgs ServerSideRenderWithPostIdProps[ 'urlQueryArgs' ]：要附加到请求 URL 的额外查询参数。

返回值

  • 已渲染的服务器端内容。

useServerSideRender

一个用于在服务器端渲染动态区块预览以显示在编辑器中的 Hook。

处理获取区块的服务器端渲染预览、管理加载状态，并自动对请求进行防抖，以防止过多的 API 调用。它支持 GET 和 POST 请求，其中 POST 请求用于较大的属性负载。

用法

基本用法：

import { RawHTML } from '@wordpress/element';
import { useServerSideRender } from '@wordpress/server-side-render';

function MyServerSideRender( { attributes, block } ) {
    const { content, status, error } = useServerSideRender( {
        attributes,
        block,
    } );

    if ( status === 'loading' ) {
        return <div>Loading...</div>;
    }

    if ( status === 'error' ) {
        return <div>Error: { error }</div>;
    }

    return <RawHTML>{ content }</RawHTML>;
}

参数

  • args UseServerSideRenderArgs：Hook 配置对象。

返回值

  • ServerSideRenderResponse：服务器端渲染响应对象。

输出

输出使用在定义区块时设置的区块 render_callback 函数。

API 端点

用于获取 ServerSideRender 输出的 API 端点是 /wp/v2/block-renderer/:block。它会使用区块的 render_callback 方法。

如果你向 ServerSideRender 传递 attributes，则该区块还必须已注册，并且其属性已在 PHP 中定义。

register_block_type(
    'core/archives',
    array(
        'api_version' => 3,
        'attributes'      => array(
            'showPostCounts'    => array(
                'type'      => 'boolean',
                'default'   => false,
            ),
            'displayAsDropdown' => array(
                'type'      => 'boolean',
                'default'   => false,
            ),
        ),
        'render_callback' => 'render_block_core_archives',
    )
);

为此包做出贡献

这是 Gutenberg 项目中的一个独立包。该项目以 monorepo 形式组织，由多个自包含的包组成，每个包都有特定用途。此 monorepo 中的包发布到 npm，并由 WordPress 以及其他软件项目使用。

要了解有关为此包或整个 Gutenberg 做出贡献的更多信息，请阅读项目的主要 贡献者指南。