图片样式

图片样式功能允许您调整图片的外观。它是通过将 CSS 类应用于图片或更改它们的类型（从内联到块或反之）来实现的。

# 概述

此软件包允许通过以下方式调整图片外观

• 应用 CSS 类 – 添加特定 预定义 或 自定义 CSS 类，或删除任何与样式相关的 CSS 类。
• 管理 HTML 表示 – 通过将图片类型从内联更改为块或反之。应用样式可能会更改图片类型，具体取决于样式的配置。

# 图片类

应用于图片的样式可以添加与样式相关的类，也可以删除它。此行为取决于 ImageStyleOptionDefinition 的特定配置。只有将 isDefault 标志设置为 true 的定义才会删除任何应用的与图片样式相关的类。

# 内联和块级图片

您可以在编辑器中将图片显示为内联或块级。

内联类型图片表示为内联 HTML 元素。您可以像普通文本一样将它们插入段落中间或链接中。内联图片的 HTML 表示如下所示

• <span class=”image-style-class”><img></img></span> 在可编辑区域中。
• <img class=”image-style-class”></img> 在通过 getData() 方法检索的 HTML 内容中。

块级类型图片只能插入在其他块之间，例如段落、表格或媒体。块级图片的 HTML 表示如下所示

• <figure class=”image image-style-class”><img></img></figure>.

通过对图片应用或删除样式可以执行在这两种图片类型之间的切换。每个定义的样式选项都提供了一个可以应用到的图片类型的列表。应用样式可能会更改图片类型，具体取决于样式的配置。

当您插入新图片时，编辑器将默认情况下根据插入的上下文（例如，当前选择/位置和 插件可用性）选择最佳图片类型。您可以使用 image.insert.type 配置 控制新插入图片的默认类型。

# UI

您可以使用由ImageStyle插件创建的工具栏按钮之一来应用样式。每个定义的样式（包括默认和自定义）将在ComponentFactory中以imageStyle:image-style-name的名称注册。然后，您可以通过引用此名称将其添加到图像或主工具栏中。

默认图像工具栏已设置其标准配置。

• 经典、内联、气泡和气泡块编辑器类型的默认 UI 包含一组用于应用语义样式的按钮，以支持创建结构化内容。 查看实时示例.
• 文档编辑器类型 UI 使用多个按钮来应用表现样式，还使用语义样式将图像外观重置为默认值。 查看实时示例.

您还可以创建完全自定义的图像样式 UI，设置您的图标和工具提示，并将图像样式按钮分组到自定义下拉菜单中。有关更多信息，请参阅本指南的配置样式部分。

# 样式化图像的方法

CKEditor 5 提供两种基本的样式化图像方法

• 特定样式可以定义图像类型，因此您可以将其样式化，例如，作为头像、横幅或表情符号。它将被称为“语义样式”，因为它指的是特定图像的用途。
• 有时用户应该能够通过能够单独且完全任意地设置大小和对齐方式来细粒度地控制图像的呈现方式。定义图像对齐方式的样式将被称为“表现”样式，因为它指的是图像的外观。

# 语义样式

语义样式允许用户从图像的预定义外观中选择。用户无法单独设置图像边框、对齐方式、边距、宽度等。相反，他们可以选择由准备 WYSIWYG 编辑器集成的开发人员定义的样式之一。查看下面的表格中可用语义样式的列表。语义样式使集成人员能够将各种预定义的图像外观提供给用户。这使开发人员可以控制用户如何设置图像样式，并通过一次设置多个属性来简化用户的操作。

大多数编辑器类型支持编辑结构化内容。这需要将对可能图像外观的控制权传递给开发人员。因此，我们引入了包含一组应用语义样式的按钮的 UI（取自下面列出的默认样式）。

以下示例显示了一个具有此类基本配置的编辑器。图像有三种类型

• 块图像 – 表示没有与样式相关的 CSS 类的块图像。
• 内联图像 – 表示没有与样式相关的 CSS 类的内联图像。
• 边侧图像 – 应用了image-style-side CSS 类的语义样式

您可以使用在单击图像后打开的上下文工具栏更改单个图像的样式。

# 表现样式

表现样式与内容的任何特殊含义无关。它们直接控制图像的视觉效果。默认情况下，可用的表现样式决定了图像对齐行为。查看下面的表格中可用语义样式的列表。

下面的示例编辑器使用预定义的表现图像样式，这些样式由按钮表示，这些按钮根据图像在文档中的显示方式分组到下拉菜单中

• 内联图像 – 显示在文本行内。它是内联图像的默认样式，它不会将任何 CSS 类应用于图像。
• 带有文本环绕的图像 – 这些是具有 CSS float 属性的图像。它们可以是内联模式或块模式。为了保持 HTML 输出的有效性，块图像（用<figure>标签环绕）只能放在段落之前或之后，不能放在段落中间。它包含以下图像样式
  • 'align-left' ,
  • 'align-right' .
• 放在段落之间的图像 – 没有 CSS float 属性的块图像。它包含以下图像样式
  • 'align-block-left' ,
  • 'align-block-right' ,
  • 'block' – 此样式是块图像的默认样式，它不会将任何 CSS 类应用于图像。

您可以使用在单击图像后调用的上下文工具栏更改单个图像的样式。

该示例还配置为使用图像调整大小功能，其中提供三个调整大小选项：'resizeImage:original'、'resizeImage:50'和'resizeImage:75'。它们允许您将编辑器中的图像宽度设置为原始图像大小（最高为编辑器窗口宽度的 100%）、50% 和 75%。您还可以使用调整大小手柄设置图像的自定义大小。

查看下面的结果

这组按钮和样式在文档编辑器中默认可用，不需要任何额外的自定义

import { DecoupledEditor } from 'ckeditor5';

DecoupledEditor.create( document.querySelector( '#editor' ) ).then( /* ... */ );

# 配置样式

在编辑器配置中定义图像样式有三种方法

• 使用其中一个预定义的默认样式。
• 修改上面提到的其中一个样式。您可以更改它应用于图像的类、图标、工具提示和支持的图像类型。
• 定义完全自定义的图像样式。

# 演示

下面的编辑器示例展示了通过自定义图像的视觉表示和设置图像样式的 UI（图标、工具提示和下拉菜单）可以实现什么。

此编辑器使用自定义图像样式、带有 声明式下拉菜单 的自定义图像工具栏配置，以及一些经过修改的 默认样式。您可以在 config.image.styles API 文档中找到使用和修改这些样式的更多示例。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        // More of editor's configuration.
        // ...
        image: {
            styles: {
                // Defining custom styling options for the images.
                options: [ {
                    name: 'side',
                    icon: sideIcon,
                    title: 'Side image',
                    className: 'image-side',
                    modelElements: [ 'imageBlock' ]
                }, {
                    name: 'margin-left',
                    icon: leftIcon,
                    title: 'Image on left margin',
                    className: 'image-margin-left',
                    modelElements: [ 'imageInline' ]
                }, {
                    name: 'margin-right',
                    icon: rightIcon,
                    title: 'Image on right margin',
                    className: 'image-margin-right',
                    modelElements: [ 'imageInline' ]
                },
                // Modifying icons and titles of the default inline and
                // block image styles to reflect its real appearance.
                {
                    name: 'inline',
                    icon: inlineIcon
                }, {
                    name: 'block',
                    title: 'Centered image',
                    icon: centerIcon
                } ]
            },
            toolbar: [ {
                // Grouping the buttons for the icon-like image styling
                // into one dropdown.
                name: 'imageStyle:icons',
                title: 'Alignment',
                items: [
                    'imageStyle:margin-left',
                    'imageStyle:margin-right',
                    'imageStyle:inline'
                ],
                defaultItem: 'imageStyle:margin-left'
            }, {
                // Grouping the buttons for the regular
                // picture-like image styling into one dropdown.
                name: 'imageStyle:pictures',
                title: 'Style',
                items: [ 'imageStyle:block', 'imageStyle:side' ],
                defaultItem: 'imageStyle:block'
            }, '|', 'toggleImageCaption', 'linkImage'
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

它还应用多个 CSS 规则，不仅可以正确显示自定义图像样式（'image-margin-right'、'image-margin-left' 和 'image-side' 类），还可以提供默认的 内容样式，因此标题、段落、链接、标题和新插入图像的外观保持一致。

下面列出了有关图像样式的最重要的规则。您可以查看完整的 内容样式表。

/* Defining the default content styles for the block images.
This is what the newly inserted image without any
style-specific class will look like. */
.ck-content .image {
    margin-top: 50px;
    margin-bottom: 50px;
}
.ck-content .image img {
    border-radius: 50%;
    width: 180px;
    height: 180px;
    object-fit: cover;
    filter: grayscale(100%) brightness(70%);
    box-shadow: 10px 10px 30px #00000078;
}
.ck-content .image::before {
    content: '';
    width: 100%;
    height: 100%;
    background-color: #1138b0;
    top: 5%;
    left: 5%;
    position: absolute;
    border-radius: 50%;
}
.ck-content .image::after {
    content: '';
    width: 200%;
    height: 200%;
    background-image: url(../../assets/img/image-context.svg);
    background-size: contain;
    background-repeat: no-repeat;
    position: absolute;
    top: -60%;
    pointer-events: none;
    left: -60%;
}

/* Defining the default content styles for the inline images.
This is what the newly inserted image without any
style-specific class will look like. */
.ck-content .image-inline {
    margin: 0 4px;
    vertical-align: middle;
    border-radius: 12px;
}
.ck-content .image-inline img {
    width: 24px;
    max-height: 24px;
    min-height: 24px;
    filter: grayscale(100%);
}

/* Defining the custom content styles for the images
placed on the side of the editing area. */
.ck-content .image.image-side {
    float: right;
    margin-right: -200px;
    margin-left: 50px;
    margin-top: -50px;
}
.ck-content .image.image-side img {
    width: 360px;
    height: 360px;
}

/* Defining the custom content styles for the images
placed on the editor margins. */
.ck-content .image-inline.image-margin-left,
.ck-content .image-inline.image-margin-right {
    position: absolute;
    margin: 0;
    top: auto;
}
.ck-content .image-inline.image-margin-left {
    left: calc( -12.5% - var(--icon-size) / 2 );
}
.ck-content .image-inline.image-margin-right {
    right: calc( -12.5% - var(--icon-size) / 2 );
}
.ck-content .image-inline.image-margin-left img,
.ck-content .image-inline.image-margin-right img {
    filter: none;
}

/* Defining the custom content styles for the image captions. */
.ck-content .image > figcaption {
    z-index: 1;
    position: absolute;
    bottom: 20px;
    left: -20px;
    font-style: italic;
    border-radius: 41px;
    background-color: #ffffffe8;
    color: #1138b0;
    padding: 5px 12px;
    font-size: 13px;
    box-shadow: 0 0 18px #1a1a1a26
}

# 可用样式

ImageStyle 插件提供了一组默认样式，具体取决于已加载的插件。下表列出了这些样式的可用性以及应用特定样式引起的图像行为。

样式名称	必需插件	转换为	应用类	类型
"block"	ImageBlock	block	删除所有类（默认样式）	语义
"inline"	ImageInline	inline	删除所有类（默认样式）	语义
"side"	ImageBlock	block	image-style-side	语义
"alignLeft"	任何	-	image-style-align-left	表现
"alignRight"	任何	-	image-style-align-right	表现
"alignBlockLeft"	ImageBlock	block	image-style-align-block-left	表现
"alignBlockRight"	ImageBlock	block	image-style-align-block-right	表现
"alignCenter"	ImageBlock	block	image-style-align-center	表现

# 安装

查看 图像功能安装指南，了解如何启用此功能。

# 通用 API

ImageStyle 插件注册

• 为每个定义的样式提供一个按钮，例如：'imageStyle:block' 和 'imageStyle:side'（用于在 图像工具栏 中使用）。

• 'imageStyle' 命令。它接受一个基于 image.styles 配置选项的值（例如，'block' 和 'side'）。

  editor.execute( 'imageStyle', { value: 'side' } );
  

# 贡献

该功能的源代码可在 GitHub 上获得，网址为 https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-image。