# 主题开发者须知：图片尺寸

**注意：** 本文档用于开发经典主题（而不是区块主题）。请参考此[其他文档](docs/theming/block-theme-development/theming-woo-blocks)，了解区块主题的开发。

为了在您的商品目录中显示图像，WooCommerce 注册了一些图片尺寸，这些尺寸定义了要使用的实际图像尺寸。 这些尺寸包括：

- `woocommerce_thumbnail` - 用于商品“网格”，例如在商店页面上。
- `woocommerce_single` - 用于单个商品页面。
- `woocommerce_gallery_thumbnail` - 用于在单个商品页面上主图像下方，用于切换图库。

`woocommerce_single` 显示完整的商品图像，如已上传的图像，默认情况下不进行裁剪。 默认宽度为 600 像素。 `woocommerce_gallery_thumbnail` 始终以正方形裁剪，默认尺寸为 100x100 像素。 这用于在图库中浏览图像。 `woocommerce_thumbnail` 默认宽度为 300 像素，正方形裁剪，以使商品网格看起来整洁。 裁剪的长宽比可以由商店所有者自定义。 重要的是要注意，尽管设置了实际的图像宽度，但主题最终可以使用 CSS 更改图像的显示尺寸，并且图像宽度可能受限于商品网格/列的宽度。

## 主题可以定义图片尺寸

从 WooCommerce 3.3.0 开始，主题可以在声明对 WooCommerce 的支持时，声明应该使用的尺寸。 如果主题定义了图像尺寸（宽度），则商店所有者将无法更改它们，但定义的尺寸应针对主题进行优化。

```php
add_theme_support( 'woocommerce', array(
    'thumbnail_image_width' => 200,
    'gallery_thumbnail_image_width' => 100,
    'single_image_width' => 500,
) );
```

当调用 WordPress 函数，例如 [`wp_get_attachment_image_src`](https://developer.wordpress.org/reference/functions/wp_get_attachment_image_src)，这些函数需要一个图像尺寸时，您应该使用图像尺寸名称，这些名称是：

- `woocommerce_thumbnail`
- `woocommerce_single`
- `woocommerce_gallery_thumbnail`

商店所有者仍然可以控制长宽比和裁剪（参见下文）。

## 在自定义设置中自定义图片尺寸

自定义设置包含控制 WooCommerce 中缩略图的选项。![自定义设置中的设置](https://woocommerce.wordpress.com/wp-content/uploads/2017/12/imagefeature.png?w=712) 如果主题声明了图片尺寸，则顶部部分将被隐藏，并且仅显示裁剪选项。更改裁剪选项或宽度将更新右侧的预览，以显示效果。更改不会对客户可见，直到自定义设置被“发表”，并且 [缩略图已重新生成为新的尺寸](docs/theming/theme-development/thumbnail-image-regeneration)。自定义设置中的缩略图裁剪部分允许店主为目录中的图像选择三种裁剪比例设置中的一种：

- 1:1 (方形裁剪)
- 自定义 (店主可以输入自定义长宽比)
- 未裁剪 (保留单个图像的长宽比)

实际的图片尺寸将根据所选的裁剪选项和图片宽度进行计算。

## 通过钩子更改图片尺寸

虽然主题可以固定图片尺寸在某些宽度，并且店主可以控制宽度和长宽比，但如果您需要更多地控制缩略图尺寸，则有一些可用的钩子。`wc_get_image_size` 函数由 WooCommerce 使用来获取图片尺寸的尺寸。此函数的返回值会通过一个过滤器传递：`woocommerce_get_image_size_{SIZE_NAME_WITHOUT_WOOCOMMERCE_PREFIX}`。如果您使用此钩子，您将获得一个类似于以下的尺寸数组：

```php
array(
    'width' => 200,
    'height' => 200,
    'crop' => 1,
)
```

例如，如果我想将画廊缩略图更改为 150x150 像素的未裁剪图像，可以使用以下代码：

```php
add_filter( 'woocommerce_get_image_size_gallery_thumbnail', function( $size ) {
    return array(
        'width' => 150,
        'height' => 150,
        'crop' => 0,
    );
} );
```

我们不建议插件和主题使用此方法，因为它会从店主那里剥夺控制权，并且他们的设置将不被尊重，但此选项可供店主使用。**注意：** 在更改图片尺寸后，您可能需要 [重新生成您的缩略图](https://github.com/woocommerce/woocommerce/wiki/Thumbnail-Image-Regeneration-in-3.3)，以便将新尺寸应用于现有图像。

## 通过钩子修改 WooCommerce 中使用的图片尺寸

除了上述钩子之外，WooCommerce 中的一些模板函数会通过过滤器处理图片尺寸，因此您可以选择使用除了 WooCommerce 注册的图片尺寸之外的其他尺寸。 以下是一些可用的过滤器：

| 过滤器                                | 描述                                                                 | 默认值                               |
|---------------------------------------|----------------------------------------------------------------------|------------------------------------|
| `single_product_archive_thumbnail_size` | 控制产品网格/目录中使用的尺寸。                                          | `woocommerce_thumbnail`            |
| `subcategory_archive_thumbnail_size`    | 控制产品网格/目录中用于分类图片的尺寸。                                    | `woocommerce_thumbnail`            |
| `woocommerce_gallery_thumbnail_size`    | 控制产品画廊中使用的尺寸，位于主图像下方，用于切换到不同的图像。                     | 表示 `gallery_thumbnail` 图像尺寸的数组。 通常为 `array( 100, 100 )`。 |
| `woocommerce_gallery_image_size`        | 控制产品画廊中使用的尺寸。                                                  | `woocommerce_single`               |
| `woocommerce_gallery_full_size`         | 控制产品画廊中用于缩放或查看原始尺寸图像的尺寸。                               | `full`                             |

**注意：** `full` 是由 WordPress 注册的尺寸，可以在 `设置 > 媒体` 中设置。 例如，如果我想将产品画廊缩略图尺寸设置为 WordPress 注册的 `thumbnail` 尺寸，而不是 `woocommerce_gallery_thumbnail`，可以使用以下代码片段：

```php
add_filter( 'woocommerce_gallery_thumbnail_size', function( $size ) {
    return 'thumbnail';
} );
```

**注意：** 上述钩子由 WooCommerce 核心使用。 如果主题有自定义模板文件或使用自己的函数来输出图像，则这些过滤器可能未被使用。