Focal Point Picker 是一个用于创建用户界面以识别图像中最重要的视觉点的组件。

它解决了在裁剪容器中显示图像时的两个常见问题。首先，大型背景图像可能会以不理想的方式被裁剪，尤其是在较小的视口（如移动设备）上。其次，CSS aspect-ratio 属性可能会无意中裁剪掉视觉兴趣最高的区域。此组件允许选择包含最重要视觉信息的点，并将其作为 0 到 1 之间的数值对返回。输出值可以应用于 CSS background-position（用于具有 background-image 的元素）或 object-position（用于使用 object-fit: cover 渲染的 <img> / <video> 元素）。

  • 焦点选取器示例值：{ x: 0.5, y: 0.1 }；
  • 对应的 CSS：object-position: 50% 10%；

用法

import { FocalPointPicker } from '@wordpress/components';
import { useState } from '@wordpress/element';

const Example = () => {
    const [ focalPoint, setFocalPoint ] = useState( {
        x: 0.5,
        y: 0.1,
    } );

    const url = '/path/to/image';

    /* 根据焦点选取器值渲染 CSS 样式的示例函数 */
    const style = {
        width: '100%',
        aspectRatio: '16 / 9',
        objectFit: 'cover',
        objectPosition: `${ focalPoint.x * 100 }% ${ focalPoint.y * 100 }%`,
    };

    return (
        <>
            <FocalPointPicker
                url={ url }
                value={ focalPoint }
                onDragStart={ setFocalPoint }
                onDrag={ setFocalPoint }
                onChange={ setFocalPoint }
            />
            <img src={ url } alt="" style={ style } />
        </>
    );
};

属性

url

  • 类型：Text
  • 必需：是

要显示的图像或视频的 URL

autoPlay

  • 类型：Boolean
  • 必需：否
  • 默认值：true

自动播放 HTML5 视频。这仅适用于视频源（url）。

value

  • 类型：Object
  • 必需：是

焦点位置。应为一个包含 x 和 y 参数的对象。

onChange

  • 类型：Function
  • 必需：是

当焦点位置更改时调用的回调函数。

onDrag

  • 类型：Function
  • 必需：否

在拖拽操作期间重复调用的回调函数。

onDragEnd

  • 类型：Function
  • 必需：否

在拖拽操作结束时调用的回调函数。

onDragStart

  • 类型：Function
  • 必需：否

在拖拽操作开始时调用的回调函数。

resolvePoint

  • 类型：Function
  • 必需：否

在内部更新 value 状态之前调用的函数。它接收即将更新的值，并可能返回修改后的值。