hyva-render-media-image

Hyvä 渲染图像

使用 \Hyva\Theme\ViewModel\Media 视图模型，为 Hyvä Theme 模板生成响应式 <picture> 元素。

适用场景

• 在 Hyvä PHTML 模板中添加图像
• 创建针对移动端和桌面端使用不同来源的响应式图像
• 实现主视觉横幅、产品图像或 CMS 内容图像
• 针对 Core Web Vitals（LCP、CLS）优化图像

工作流

1. 收集图像需求

用户可能通过以下方式之一提供图像数据：

选项 A：直接提供值 - 向用户询问：

1. 图像路径 - 位于 pub/media/ 中的位置（例如，wysiwyg/hero.jpg、catalog/product/...）
2. 图像尺寸 - 宽度和高度（像素）
3. 响应式需求 - 移动端和桌面端是否使用不同图像？
4. 图像用途 - 主视觉/LCP 图像（立即加载）还是首屏以下图像（延迟加载）？
5. 替代文本 - 有意义的无障碍描述

选项 B：PHP 变量 - 用户提供变量名（例如，$imageData、$heroImage）。告知用户所需的数组结构，详见 references/rendering-images.md 中的 ## Image Configuration Format。

2. 生成代码

查阅 references/rendering-images.md，获取完整的 API 参考、代码示例和所有配置选项。

选择合适的模式：

场景	使用模式
单张图像，字面值	单图像示例
来自变量的单张图像	包装在数组中：[$imageData]
来自变量的多张图像	直接传入：$images
移动端和桌面端使用不同图像	使用媒体查询的响应式图像
需要为 <picture> 包装元素设置样式	Picture 元素属性

基础模板：

<?php
/** @var \Hyva\Theme\ViewModel\Media $mediaViewModel */
$mediaViewModel = $viewModels->require(\Hyva\Theme\ViewModel\Media::class);

echo $mediaViewModel->getResponsivePictureHtml(
    $images,        // Array of image configs (see reference for format)
    $imgAttributes, // Optional: alt, class, loading, fetchpriority
    $pictureAttributes // Optional: class, data-* attributes for <picture>
);

3. 设置加载策略

图像类型	属性
主视觉/LCP（首屏内）	'loading' => 'eager', 'fetchpriority' => 'high'
首屏以下	'loading' => 'lazy'

资源

• references/rendering-images.md - 完整的 API 参考，包含方法签名、所有配置选项、代码示例和最佳实践