hyva-render-media-image

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hyvä Render Image

Hyvä 渲染图片

Generate responsive

<picture>

elements for Hyvä Theme templates using the

\Hyva\Theme\ViewModel\Media

view model.

使用

\Hyva\Theme\ViewModel\Media

视图模型为Hyvä Theme模板生成响应式

<picture>

元素。

When to Use

使用场景

Adding images to Hyvä PHTML templates
Creating responsive images with different sources for mobile/desktop
Implementing hero banners, product images, or CMS content images
Optimizing images for Core Web Vitals (LCP, CLS)

向Hyvä PHTML模板中添加图片
创建移动端/桌面端使用不同资源的响应式图片
实现首屏横幅、产品图片或CMS内容图片
针对Core Web Vitals（LCP、CLS）优化图片

Workflow

工作流程

1. Gather Image Requirements

1. 收集图片需求

The user may provide image data in one of these ways:

Option A: Direct values - Ask the user for:

Image path(s) - Location in

pub/media/

(e.g.,

wysiwyg/hero.jpg

catalog/product/...

)

Image dimensions - Width and height in pixels
Responsive requirements - Different images for mobile vs desktop?
Image purpose - Hero/LCP image (eager loading) or below-fold (lazy loading)?
Alt text - Meaningful description for accessibility

Option B: PHP variable - The user provides a variable name (e.g.,

$imageData

$heroImage

). Inform the user of the required array structure documented in

references/rendering-images.md

under

## Image Configuration Format

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

选项A：直接值 - 向用户收集以下信息：

图片路径 - 位于
```
pub/media/
```
下的位置（例如：
```
wysiwyg/hero.jpg
```
、
```
catalog/product/...
```
）
图片尺寸 - 宽度和高度（像素单位）
响应式需求 - 移动端和桌面端是否使用不同图片？
图片用途 - 首屏/LCP图片（立即加载）还是首屏下方图片（懒加载）？
替代文本 - 用于无障碍访问的有意义描述

选项B：PHP变量 - 用户提供变量名称（例如：

$imageData

、

$heroImage

）。告知用户所需的数组结构记录在

references/rendering-images.md

的

## Image Configuration Format

部分。

2. Generate the Code

2. 生成代码

Refer to

references/rendering-images.md

for the complete API reference, code examples, and all configuration options.

Choose the appropriate pattern:

Scenario	Pattern to Use
Single image, literal values	Single Image Example
Single image from variable	Wrap in array: `[$imageData]`
Multiple images from variable	Pass directly: `$images`
Different images for mobile/desktop	Responsive Images with Media Queries
Need to style the `<picture>` wrapper	Picture Element Attributes

Base template:

php

<?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>
);

完整的API参考、代码示例和所有配置选项请参考

references/rendering-images.md

。

选择合适的模式：

场景	使用模式
单张图片，字面量值	单张图片示例
从变量获取单张图片	包装为数组： `[$imageData]`
从变量获取多张图片	直接传入： `$images`
移动端/桌面端使用不同图片	带媒体查询的响应式图片
需要为 `<picture>` 容器设置样式	Picture元素属性

基础模板：

php

<?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. Set Loading Strategy

3. 设置加载策略

Image Type	Attributes
Hero/LCP (above fold)	`'loading' => 'eager', 'fetchpriority' => 'high'`
Below fold	`'loading' => 'lazy'`

图片类型	属性
首屏/LCP图片（首屏内）	`'loading' => 'eager', 'fetchpriority' => 'high'`
首屏下方图片	`'loading' => 'lazy'`

Resources

资源

```
references/rendering-images.md
```
- Complete API reference with method signature, all configuration options, code examples, and best practices

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