简单上传适配器

简单上传适配器允许您使用 XMLHttpRequest API 将图像上传到您的服务器，并具有最小的 编辑器配置。请参见 服务器端配置 部分，了解有关服务器端应用程序要求的信息。

# 安装

在 安装编辑器 后，将该功能添加到您的插件列表和工具栏配置中

import { ClassicEditor, SimpleUploadAdapter } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ SimpleUploadAdapter, /* ... */ ],
        toolbar: [ /* ... */ ],
        simpleUpload: {
            // Feature configuration.
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 配置

此功能的客户端可以使用 config.simpleUpload 对象进行配置。

import { ClassicEditor, SimpleUploadAdapter } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ SimpleUploadAdapter, /* ... */ ],
        toolbar: [ /* ... */ ],
        simpleUpload: {
            // The URL that the images are uploaded to.
            uploadUrl: 'http://example.com',

            // Enable the XMLHttpRequest.withCredentials property.
            withCredentials: true,

            // Headers sent along with the XMLHttpRequest to the upload server.
            headers: {
                'X-CSRF-TOKEN': 'CSRF-Token',
                Authorization: 'Bearer <JSON Web Token>'
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 配置允许的文件类型

应该在两个地方配置允许上传的文件类型

• 在 CKEditor 5 的客户端，通过 CKEditor 5 UI 和命令来限制图像上传。
• 在服务器端，在您的服务器端应用程序配置中。

# 客户端配置

使用 image.upload.types 配置选项来定义允许上传到 CKEditor 5 的图像 MIME 类型。

默认情况下，用户可以上传 jpeg、png、gif、bmp、webp 和 tiff 文件，但是您可以自定义此行为来接受例如 SVG 文件。

# 服务器端配置

您需要在您的服务器上实现任何过滤机制来限制允许上传的图像类型。

# 服务器端配置

要使用此上传适配器，您必须提供一个服务器端应用程序，它将处理上传并与编辑器进行通信，如以下部分所述。

# 通信协议

当图像上传过程启动时，适配器会发送一个 POST 请求到 config.simpleUpload.uploadUrl 下。

您可以使用 config.simpleUpload.headers 对象，将额外的 标头 与 XMLHttpRequest 一起发送到上传服务器，例如，使用 标头 来验证用户。

如果您使用 config.simpleUpload.withCredentials 配置，您可能需要一些 额外的 HTTP 标头 才能使跨站点请求正常工作。

请求的 responseType 始终为 json。请参见 成功上传 和 错误处理 部分以了解更多信息。

# 成功上传

如果上传成功，服务器应返回

• 包含指向服务器上已上传图像的 url 属性的对象

  {
      "url": "https://example.com/images/foo.jpg"
  }
  

• 或者包含 urls 属性的对象，如果您想使用 响应式图像 并且服务器支持它

  {
      "urls": {
          "default": "https://example.com/images/foo.jpg",
          "800": "https://example.com/images/foo-800.jpg",
          "1024": "https://example.com/images/foo-1024.jpg",
          "1920": "https://example.com/images/foo-1920.jpg"
      }
  }
  

  "default" URL 将用于富文本编辑器内容中图像的 src 属性。其他 URL 将用于 srcset 属性，允许 Web 浏览器为视窗的几何形状选择最佳的 URL。

服务器响应中的 URL(s) 用于

• 在编辑期间显示图像（如用户在编辑器中看到的那样）。
• 在 保存到数据库 的编辑器内容中。

# 错误处理

如果出现错误，服务器必须返回包含 error 属性的对象。这将取消编辑器中的上传，例如，允许用户选择另一张图像，如果前一张图像太大或不符合其他验证标准。

如果 error 对象包含 message，它将被传递到 编辑器通知系统 并显示给用户。为了方便用户，请使用清晰且可能具体的错误消息。

{
    "error": {
        "message": "The image upload failed because the image was too big (max 1.5MB)."
    }
}

如果 error 对象中缺少 message 属性，编辑器通知系统 将显示默认的“无法上传文件：[filename].” 消息。

# 上传进度

此上传适配器将开箱即用地通知用户有关 文件上传进度。

# 下一步

查看全面的 图像上传概述，了解有关在 CKEditor 5 中上传图像的不同方法的更多信息。

查看 图像功能指南，详细了解如何在 CKEditor 5 WYSIWYG 编辑器中处理图像。

# 贡献

该功能的源代码可在 GitHub 上获取：https://github.com/ckeditor/ckeditor5/tree/master/packages/ckeditor5-upload。