云策 WordPress 开发者社区

主题开发文档

Lightbox

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

概述

本文档介绍了 WordPress 6.4 中引入的 Lightbox 设置，该设置专用于核心 Image 块，允许启用点击展开图像的灯箱功能。文档详细说明了如何在 theme.json 中配置相关属性，以全局启用或禁用此功能，并控制用户编辑权限。

关键要点

  • Lightbox 设置仅适用于 WordPress 6.4 及以上版本的核心 Image 块（core/image），用于实现点击图像时全屏展开的灯箱效果。
  • lightbox 属性是一个对象，包含 enabled 和 allowEditing 两个嵌套属性：enabled 控制是否启用灯箱功能（默认 undefined，即禁用），allowEditing 控制是否在界面中显示“Expand on click”选项供用户编辑（默认 true）。
  • 通过修改 theme.json 中的 settings.blocks.core/image.lightbox.enabled 为 true，可以全局启用 Image 块的灯箱功能；设置 allowEditing 为 false 可以禁用用户编辑权限，隐藏相关界面选项。

代码示例

{
	"version": 2,
	"settings": {
		"blocks": {
			"core/image": {
				"lightbox": {
					"enabled": true
				}
			}
		}
	}
}
{
	"version": 2,
	"settings": {
		"blocks": {
			"core/image": {
				"lightbox": {
					"allowEditing": false
				}
			}
		}
	}
}
📄 原文内容

settings.lightbox is a specific setting that you can enable for supported blocks. It enables a lightbox feature that expands an image when a site visitor clicks on an image.

This setting is only available as of WordPress 6.4 and is specific to the core Image block (core/image).

Lightbox settings

The lightbox setting is specific to the Image block, so the following examples will be shown in that context.

The lightbox property is an object that has two nested properties that you can configure:

  • enabled: Whether to enable the lightbox feature for the Image block. The default value is undefined (the equivalent of being disabled).
  • allowEditing: Whether to show the Expand on click option in the interface, which allows the user to enable/disable lightbox for individual images. Defaults to true.

Here is a look at the default theme.json:

{
	"version": 2,
	"settings": {
		"blocks": {
			"core/image": {
				"lightbox": {
					"allowEditing": true
				}
			}
		}
	}
}

Enabling lightbox for images

To enable the lightbox feature for Image blocks used throughout the site, you must set settings.blocks.core/image.lightbox.enabled to true in theme.json:

{
	"version": 2,
	"settings": {
		"blocks": {
			"core/image": {
				"lightbox": {
					"enabled": true
				}
			}
		}
	}
}

On the front-end of the site, visitors will be able to expand the image when clicking on it. The image will then overlay the entire screen (including an x button for closing the overlay), as shown below:

Image of palm trees expanded as an overlay modal.

Disabling user editing

By default, WordPress will show an Expand on Click option under the Settings tab for the Image block:

WordPress post editor with an Image block showing the "expand on click" option selected.

This control allows your theme’s users to enable or disable the lightbox feature on a per-block basis.

To disallow user editing, you must set settings.blocks.core/image.lightbox.allowEditing to false in theme.json:

{
	"version": 2,
	"settings": {
		"blocks": {
			"core/image": {
				"lightbox": {
					"allowEditing": false
				}
			}
		}
	}
}