调整图像大小

图像调整大小功能允许您更改内容中图像的宽度。它是通过 ImageResize 插件实现的。

# 调整图像大小的方法

编辑器提供了不同的方法来调整图像大小，可以使用“调整大小手柄”或使用专用 UI 组件（下拉菜单或独立按钮）。

ImageResize 插件启用了显示在选定图像上的四个调整大小手柄。用户可以通过拖动它们来调整图像大小。您可以配置该功能以使用百分比（默认）或像素值。

该插件还允许您通过单击图像工具栏来更改图像大小。您可以使用 resizeOptions 设置一个可选的静态配置，并选择是否要使用下拉菜单或一组独立按钮。

# 使用调整大小手柄

在这种情况下，您可以通过拖动显示在其每个角上的方形手柄来调整图像大小。启用图像调整大小后，此选项不需要任何额外的配置。

使用角手柄调整图像大小，并根据需要调整到文本。您还可以使用图像工具栏中的对齐选项 来实现所需的效果。

图像也可以使用样式进行预调整大小，如下所示（最后三张图像设置为 28% 以确保视觉一致性）。

您可以在 CKEditor 5 WYSIWYG 编辑器中通过两种不同的方式配置通过手柄调整图像大小

• 通过安装 ImageResize 插件。它包含本指南 安装 部分所述的所有必要功能（ImageResizeEditing、ImageResizeHandles、ImageResizeButtons）。

• 通过安装 ImageResizeEditing 和 ImageResizeHandles 插件的组合。这将不会加载不必要的 ImageResizeButtons 插件

import { ClassicEditor, Image, ImageResizeEditing, ImageResizeHandles } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Image, ImageResizeEditing, ImageResizeHandles, /* ... */ ],
        // More of editor's configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

这两种方法默认都启用调整大小手柄。

# 使用调整大小下拉菜单

在这种情况下，用户可以选择一组预定义的选项。您可以在用户单击图像后可用的图像工具栏中显示这些选项，以下拉菜单的形式。

要使用此选项，您需要启用图像大小调整并配置可用的大小调整选项。然后将下拉菜单添加到图像工具栏配置中。

const imageConfiguration = {
    resizeOptions: [
        {
            name: 'resizeImage:original',
            value: null,
            label: 'Original'
        },
        {
            name: 'resizeImage:custom',
            label: 'Custom',
            value: 'custom'
        },
        {
            name: 'resizeImage:40',
            value: '40',
            label: '40%'
        },
        {
            name: 'resizeImage:60',
            value: '60',
            label: '60%'
        }
    ],
    toolbar: [ 'resizeImage', /* ... */ ]
}

尝试在图像工具栏中使用的大小调整下拉菜单的实时演示。

# 使用独立的大小调整按钮

在这种情况下，大小调整选项将显示为单独的按钮。此解决方案的优点是 UX 最流畅，因为用户只需单击一次即可调整图像大小。

要使用此选项，您需要启用图像大小调整并配置可用的大小调整选项。然后将适当的按钮添加到图像工具栏配置中。

const imageConfiguration = {
    resizeOptions: [
        {
            name: 'resizeImage:original',
            value: null,
            icon: 'original'
        },
        {
            name: 'resizeImage:custom',
            value: 'custom',
            icon: 'custom'
        },
        {
            name: 'resizeImage:50',
            value: '50',
            icon: 'medium'
        },
        {
            name: 'resizeImage:75',
            value: '75',
            icon: 'large'
        }
    ],
    toolbar: [
        'resizeImage:50',
        'resizeImage:75',
        'resizeImage:original',
        'resizeImage:custom',
        // More toolbar options.
        // ...
    ]
}

尝试在图像工具栏中使用的独立大小调整按钮的实时演示。

# 禁用图像大小调整手柄

如果要以用户只能通过按钮调整图像大小的方式配置编辑器，则可以省略ImageResizeHandles 插件来实现。

因此，您的插件设置应如下所示：plugins: [ 'ImageResizeEditing', 'ImageResizeButtons', /* ... */ ]，而不是 plugins: [ 'ImageResize', /* ... */ ]。

这将仅通过选定的 UI 启用图像大小调整功能：图像工具栏中的下拉菜单或独立按钮。

import { ClassicEditor, Image, ImageResizeButtons, ImageResizeEditing, ImageToolbar } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Image, ImageResizeEditing, ImageResizeButtons, ImageToolbar, /* ... */ ],
        image: {
            resizeOptions: [
            {
                name: 'resizeImage:original',
                value: null,
                icon: 'original'
            },
            {
                name: 'resizeImage:custom',
                value: 'custom',
                icon: 'custom'
            },
            {
                name: 'resizeImage:50',
                value: '50',
                icon: 'medium'
            },
            {
                name: 'resizeImage:75',
                value: '75',
                icon: 'large'
            }
        ],
        toolbar: [
            'resizeImage:50',
            'resizeImage:75',
            'resizeImage:original',
            'resizeImage:custom',
            // More toolbar options.
            // ...
        ] }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 标记和样式

调整图像大小后，将使用内联width样式，并且编辑器会将image_resized类分配给<figure>元素。

<figure class="image image_resized" style="width: 75%;">
    <img src="..." alt="...">
</figure>

image_resized类用于禁用图像样式分配的max-width（如果将此样式应用于此图像）。例如，“侧边图像”样式定义如下

.ck-content .image-style-side {
    max-width: 50%;
    float: right;
    margin-left: var(--ck-image-style-spacing);
}

max-width将通过以下规则覆盖

.ck-content .image.image_resized {
    max-width: 100%;
}

为调整大小的图像设置样式时，另一个问题是，默认情况下，CKEditor 5 对<figure class="image">元素使用display: table，以使其占据其中<img>元素的大小。不幸的是，浏览器尚不支持在使用display: table样式的同一元素上使用max-width和width。因此，调整图像大小时需要使用display: block。

.ck-content .image.image_resized {
    display: block;
    box-sizing: border-box;
}

.ck-content .image.image_resized img {
    width: 100%;
}

.ck-content .image.image_resized > figcaption {
    display: block;
}

# 使用像素值而不是百分比宽度

使用百分比宽度可确保内容在 WYSIWYG 编辑器以外的位置显示时保持响应。当用户在编辑器中使图像占据内容宽度的 60%（例如）时，如果您更改目标页面（显示此内容的页面）的宽度，图像仍将占据该空间的 60%。如果页面是响应式页面并根据视窗宽度进行调整，也是如此。

如果您配置了编辑器以使用像素值，则在为网站引入新布局后，图像可能会占据太多空间。

但是，在某些情况下，您可能更喜欢像素值。因此，您可以通过设置config.image.resizeUnit选项来配置编辑器以使用像素值。

ClassicEditor
    .create( editorElement, {
        image: {
            resizeUnit: 'px',
            resizeOptions: [
                {
                    name: 'resizeImage:original',
                    label: 'Original',
                    value: null
                },
                {
                    name: 'resizeImage:custom',
                    label: 'Custom',
                    value: 'custom'
                },
                {
                    name: 'resizeImage:100',
                    label: '100px',
                    value: '100'
                },
                {
                    name: 'resizeImage:200',
                    label: '200px',
                    value: '200'
                }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

以下演示使用 CSS 设置固定图像长宽比，因此 200 像素宽的图像会自动获得相同的高度。

.ck.ck-content .image {
    position: relative;
}
.ck.ck-content .image img {
    position: absolute;
    left: 0;
    top: 0;
    width: 100%;
    height: 100%;
    object-fit: cover;
    border-radius: 50%;
}
.ck.ck-content .image::before {
    content: '';
    padding-top: 100%;
    display: block;
}

查看以下实时演示中的差异。

# 图像优化和响应式图像

使用CKBox 文件管理器服务时，它会生成一组调整大小的优化图像。用户可以在需要时调用这些调整大小的版本。要了解有关这些功能的更多信息，请参阅响应式图像指南和CKBox 转换指南。

# 安装

要启用它，您需要安装ImageResize插件，该插件包含所有所需功能（ImageResizeEditing、ImageResizeHandles、ImageResizeButtons）。

import { ClassicEditor, Image, ImageResize } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Image, ImageResize, /* ... */ ],
        // More of editor's configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 通用 API

ImageResize插件注册以下内容

• 图像大小调整按钮（在图像工具栏中使用）。
• 'resizeImage' 命令，它接受目标宽度。

# 贡献

此功能的源代码在 GitHub 上可用，地址为 https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-image。