自定义WordPress嵌入以匹配您的主题
您是否曾想过定制您的 WordPress 嵌入内容？
默认设置本身并无不妥。WordPress 提供了一个中性、适应性强的设计，可以无缝融入几乎任何布局。这也是许多人保持默认设置不变的原因。
然而，只需稍加努力，您就可以让您的嵌入内容反映您的品牌、匹配您网站的设计，甚至显示标题和摘要之外的额外信息。
在本文中，您将看到几种调整 WordPress 嵌入内容外观和内容的方法。让我们开始吧！
什么是嵌入内容？
嵌入内容允许您在文章中包含外部内容，包括视频、投票、社交媒体帖子，甚至来自其他 WordPress 网站的内容。
您在不同网站上看到的 YouTube 视频几乎都是嵌入内容，除了少数使用自定义播放器的。同样，正如您可以在网站上包含 YouTube 视频一样，其他人也可以在其网站上嵌入您的 WordPress 文章。
如果服务受支持，您只需将 URL 粘贴到嵌入块中即可嵌入资源。如果不支持，您将需要使用自定义 HTML 块来插入嵌入代码。嵌入代码几乎总是包含一个 iframe 标签。
在这两种情况下，前端都会显示一个指向规范 URL 内容的简化、适合嵌入版本的 iframe。
例如，本文的规范 URL 就是您浏览器地址栏中的那个。如果您在 URL 后附加 /embed/，您将看到这篇文章在嵌入时的样子。
本质上，WordPress 的 /embed/ 端点提供的是同一篇文章的略微不同的视图。
YouTube 的工作方式相同，您有主要的规范视频 URL，例如 https://www.youtube.com/watch?v=KLybH5YvIPQ，以及位于 https://www.youtube.com/embed/KLybH5YvIPQ 的嵌入版本。两者加载相同的视频，但使用不同的模板。
WordPress 中嵌入内容的简史
自版本 2.9起，WordPress 就使用oEmbed 协议来简化从各种服务嵌入内容。此功能在版本 4.0中通过为编辑器中的嵌入内容添加实时预览而得到进一步改进。
在版本 4.4中，WordPress 成为了一个 oEmbed 提供者，允许其他网站嵌入来自 WordPress 的文章。版本 4.5进一步改进了嵌入模板。
版本 5.0引入了块编辑器，它附带了一个专用的嵌入块。此后，WordPress 不断添加和移除服务，并进行幕后调整。
默认视图
在开始定制嵌入内容之前，让我们先分解一下默认布局。
WordPress 嵌入内容看起来像一个卡片组件，在主区域呈现文章的标题和摘要。
在嵌入页脚的一侧，您会找到网站的图标和名称。如果未设置网站图标，则会显示 WordPress 徽标作为后备。
在另一侧，如果启用了讨论，评论数会与一个分享按钮一起出现。点击分享按钮会打开一个包含文章 URL 和 HTML 嵌入代码的覆盖层。
摘要要么是您手动添加的，要么是自动生成的。如果是自动生成的，它会受到字数限制，并后跟一个“继续阅读”的行动号召。
如果文章有特色图片，它可以作为大图出现在标题上方，或者根据图片的宽高比作为浮动图片出现在标题下方。
最后，当嵌入一个不存在的 URL 时，嵌入内容会显示一个 404 未找到错误，并带有相关的标题和消息。
调整样式
既然您已经看到了 WordPress 呈现嵌入内容的多种方式，那么让我们开始使用自定义样式添加一些个性。
首先，在您的主题文件夹中创建一个专用的 CSS 文件 assets/css/embed.css。然后使用 enqueue_embed_scripts 钩子将该文件入队，将以下代码添加到您的 functions.php 中：
function devblog_embed_enqueue_style() {
wp_enqueue_style(
'devblog-embed',
get_theme_file_uri( 'assets/css/embed.css' ),
array( 'wp-embed-template' )
);
}
add_action( 'enqueue_embed_scripts', 'devblog_embed_enqueue_style' );如果向主题的 functions.php 文件添加代码不适合您的项目，请随意将其包含在最适合您的自定义插件或代码片段插件中。
通过指定 wp-embed-template 作为依赖项，您可以确保您的样式在默认样式之后加载，从而更容易覆盖它们，而无需诉诸过多的 CSS 特异性。
现在，将此代码添加到 CSS 文件中，以微调间距并为页脚应用柔和的背景：
.wp-embed-featured-image.rectangular {
margin: -25px -25px 25px;
}
/* 需要此特异性来覆盖默认值。 */
p.wp-embed-heading {
/* 默认嵌入样式表未使用 CSS 逻辑属性。 */
margin-bottom: 10px;
}
.wp-embed-footer {
margin: 25px -25px -25px;
padding: 25px;
background: #fafafa;
}
使用内联样式
如果您只需要更改一项内容并且不想创建单独的 CSS 文件，可以使用内联样式：
function devblog_embed_inline_style() {
wp_add_inline_style(
'wp-embed-template',
<<<CSS
.wp-embed-featured-image.rectangular {
margin: -25px -25px 25px;
}
CSS
);
}
add_action( 'embed_head', 'devblog_embed_inline_style' );对于内联样式，您必须使用 embed_head 钩子，因为 enqueue_embed_scripts 钩子在过程中加载得太晚。
强制使用一致的图片格式
除了添加您自己的样式外，您还可以修改更多内容。例如，如果您不希望以两种不同的方式显示图片（标题上方和浮动），您可以强制使用单一选项。
假设您希望图片始终出现在标题上方。您可以使用 embed_thumbnail_image_shape 过滤器来覆盖确定的图片形状：
function devblog_embed_enforce_rectangular_image_shape() {
return 'rectangular';
}
add_filter( 'embed_thumbnail_image_shape', 'devblog_embed_enforce_rectangular_image_shape' );这个更改有一个缺点：之前浮动的方形图片可能会占用太多空间，使您的嵌入内容过高。这就是 WordPress 默认以两种方式显示图片的原因。
您可以通过为嵌入内容强制使用特定的图片尺寸来解决这个问题。首先，检查您是否已经注册了合适的图片尺寸（高度较窄的尺寸）。
如果没有，注册一个新的图片尺寸，并使用 embed_thumbnail_image_size 过滤器强制使用它：
function devblog_register_embed_narrow_image_size() {
add_image_size( 'devblog-embed-narrow', 640, 360, true );
}
add_action( 'after_setup_theme', 'devblog_register_embed_narrow_image_size' );
function devblog_embed_enforce_embed_narrow_thumbnail_image_size() {
return 'devblog-embed-narrow';
}
add_filter( 'embed_thumbnail_image_size', 'devblog_embed_enforce_embed_narrow_thumbnail_image_size' );
当您注册一个新的图片尺寸时，必须重新生成图片，因为 WordPress 默认不会动态创建它们。您可以使用 WP CLI 或插件重新生成图片。
有条件地修改摘要
虽然 WordPress 为图片尺寸和形状提供了过滤器，但并非每个方面都有专用的过滤器。例如，没有针对标题或摘要长度的嵌入特定过滤器。
但是，您可以通过使用 excerpt_length 过滤器以及 is_embed 函数来专门缩短嵌入内容的摘要：
function devblog_embed_shorter_excerpt_length( $length ) {
return is_embed() ? 25 : $length;
}
add_filter( 'excerpt_length', 'devblog_embed_shorter_excerpt_length' );这是一个微小的改变，但可能正是您所需要的。
移除或更改摘要的行动号召
除了调整摘要的长度，您还可以移除末尾的“继续阅读”行动号召。因为 WordPress 使用过滤器附加了该 CTA，您可以用一行代码移除它：
remove_filter( 'excerpt_more', 'wp_embed_excerpt_more', 20 );如果您想更改文本而不是移除它，可以钩入 excerpt_more 并使用 HTML API 将其设置为“继续探索”：
function devblog_embed_excerpt_call_to_action( $more_string ) {
if ( ! is_embed() ) {
return $more_string;
}
$processor = new WP_HTML_Tag_Processor( $more_string );
if ( $processor->next_tag( 'a' ) ) {
$processor->next_token();
$processor->set_modifiable_text(
__( 'Keep exploring', 'devblog' )
);
}
return $processor->get_updated_html();
}
add_filter( 'excerpt_more', 'devblog_embed_excerpt_call_to_action', 21 );
更改网站标题
另一个可以定制的区域是网站的标题及其徽标。
假设您的个人博客没有徽标，并且希望在不显示 WordPress 后备徽标的情况下显示网站标题。在这种情况下，可以钩入 embed_site_title_html：
function devblog_embed_only_site_title() {
return sprintf(
'<div class="wp-embed-site-title">%s</div>',
esc_html( get_bloginfo( 'name' ) )
);
}
add_filter( 'embed_site_title_html', 'devblog_embed_only_site_title' );
添加额外内容
除了样式化嵌入内容和修改其元素外，您还可以添加额外的内容片段。
您可以使用两个钩子：一个紧接在摘要之后（embed_content），另一个在包含评论和分享图标的行中（embed_content_meta）。
添加发布日期
您可能选择仅对文章显示发布日期，因为页面是相当静态的。
由于每种文章类型都使用相同的嵌入模板，因此使用条件标签通过 embed_content 操作附加日期：
function devblog_embed_post_posted_on() {
if ( ! is_single() ) {
return;
}
$time = sprintf(
'<time datetime="%1$s">%2$s</time>',
esc_attr( get_the_date( DATE_W3C ) ),
esc_html( get_the_date() )
);
printf(
'<p class="wp-embed-posted-on">%s</p>',
sprintf(
/* translators: %s: Publish date. */
esc_html__( 'Posted on %s', 'devblog' ),
$time // phpcs:ignore WordPress.Security.EscapeOutput
)
);
}
add_action( 'embed_content', 'devblog_embed_post_posted_on' );然后，将这些样式添加到之前创建的 CSS 文件中，以在发布日期和摘要之间创建间距：
/* 需要此特异性来覆盖默认值。 */
p.wp-embed-posted-on {
margin-top: 10px;
}
添加点赞按钮
扩展包含评论和分享图标的行的例子不多，但这里有一个想法：如果您的网站包含点赞文章的功能，您可以在嵌入内容中添加一个点赞按钮。
您可以钩入 embed_content_meta 操作来渲染标记：
function devblog_embed_like_button() {
if ( is_404() ) {
return;
}
?>
<div class="wp-embed-like">
<button class="wp-embed-like-button"
aria-label="<?php esc_attr_e( 'Like', 'devblog' ); ?>">
<span class="dashicons dashicons-heart"></span>
</button>
</div>
<?php
}
add_action( 'embed_content_meta', 'devblog_embed_like_button', 9 );此 HTML 遵循与 WordPress 已经在嵌入内容中提供的分享按钮类似的结构。
同样，为了尽可能接近现有的 WordPress 代码，您可以添加这些样式：
.wp-embed-like {
display: inline;
margin-right: 10px;
}
.wp-embed-like-button {
margin: -8px 0 0;
padding: 0;
background: transparent;
border: none;
cursor: pointer;
outline: none;
}
.wp-embed-like-button .dashicons {
padding: 4px;
top: 8px;
}
.wp-embed-like-button:focus .dashicons,
.wp-embed-like-button:focus .dashicons {
box-shadow: 0 0 0 2px #2271b1;
outline: 2px solid transparent;
border-radius: 100%;
}
.wp-embed-like-button:hover .dashicons-heart {
background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'%3E%3Crect x='0' fill='none' width='20' height='20'/%3E%3Cg%3E%3Cpath fill='%232271b1' d='M10 17.12c3.33-1.4 5.74-3.79 7.04-6.21 1.28-2.41 1.46-4.81.32-6.25-1.03-1.29-2.37-1.78-3.73-1.74s-2.68.63-3.63 1.46c-.95-.83-2.27-1.42-3.63-1.46s-2.7.45-3.73 1.74c-1.14 1.44-.96 3.84.34 6.25 1.28 2.42 3.69 4.81 7.02 6.21z'/%3E%3C/g%3E%3C/svg%3E");
}
.dashicons-heart {
background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 20 20'%3E%3Crect x='0' fill='none' width='20' height='20'/%3E%3Cg%3E%3Cpath fill='%238c8f94' d='M10 17.12c3.33-1.4 5.74-3.79 7.04-6.21 1.28-2.41 1.46-4.81.32-6.25-1.03-1.29-2.37-1.78-3.73-1.74s-2.68.63-3.63 1.46c-.95-.83-2.27-1.42-3.63-1.46s-2.7.45-3.73 1.74c-1.14 1.44-.96 3.84.34 6.25 1.28 2.42 3.69 4.81 7.02 6.21z'/%3E%3C/g%3E%3C/svg%3E");
}这不是最现代的 CSS，但它与WordPress 核心用于嵌入内容的样式保持一致。
实现实际的点赞按钮功能超出了本文的范围，但这是您如何为按钮添加样式的方法。
移除现有元素
除了添加元素，您还可以移除不需要的现有元素。
例如，以下是移除 WordPress 通过 embed_content_meta 操作添加的评论和分享按钮的方法：
remove_action( 'embed_content_meta', 'print_embed_comments_button' );
remove_action( 'embed_content_meta', 'print_embed_sharing_button' );