控制或调整允许的图片和文件格式

images_file_types

此选项用于配置编辑器允许接受的图片文件格式。更改此选项将调整编辑器的以下行为：

  • 在 图片 对话框中，允许上传哪些图片文件格式。

  • 哪些图片文件格式会被核心粘贴功能和 PowerPaste 的 smart_paste 功能识别，并插入到 img 元素中。

类型： String

默认值： 'jpeg,jpg,jpe,jfi,jif,jfif,png,gif,bmp,webp'

可能的值： 有效的 Web 图片文件扩展名列表。有关可能值的列表，请参阅：MDN Web Docs - 图片文件类型和格式指南。

示例：使用 images_file_types

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  plugins: 'image',
  toolbar: 'image',
  images_file_types: 'jpg,svg,webp'
});

file_picker_types

此选项允许您通过以空格或逗号分隔的类型名称列表来指定所需的文件选择器类型。当前有三个有效类型：file、image 和 media。

类型： String

可能的值： 'file'、'image'、'media'

示例：使用 file_picker_types

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  file_picker_types: 'file image media'
});

block_unsupported_drop

当 block_unsupported_drop 选项设置为 true 时，编辑器会阻止不支持的图片和文件被拖放到编辑器中。如果 block_unsupported_drop 选项设置为 false，则拖放不支持的文件到编辑器中会导致浏览器跳转离开包含编辑器的页面。

类型： Boolean

默认值： true

可能的值： true、false

示例：使用 block_unsupported_drop

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  block_unsupported_drop: false
});

在图片和媒体对话框中添加文件浏览器

file_picker_callback

此钩子可用于将自定义文件选择器添加到那些支持文件选择器的对话框中。一旦定义了 file_picker_callback，在支持的文件类型字段旁边就会出现一个小的浏览按钮（参见 file_picker_types）。当用户点击该按钮时，TinyMCE 会自动调用回调函数，并传入三个参数：

  • callback - 一个回调函数，用于在获取文件后调用；它期望将字段的新值作为第一个参数，可选地将对话框中其他字段的元信息作为第二个参数

  • value - 受影响字段的当前值

  • meta - 一个对象，包含指定对话框中其他字段的值（注意 meta.filetype 包含字段的类型）

需要注意的是，我们仅提供钩子。具体的功能实现由您自行完成。

类型： Function

以下示例演示了如何使用 file_picker_callback API，但并未实际选取任何文件。有关更具功能性的示例，请查看交互式示例。

示例：使用 file_picker_callback

tinymce.init({
  selector: 'textarea',  // change this value according to your HTML
  file_picker_callback: (callback, value, meta) => {
    // 为链接对话框提供文件和文本
    if (meta.filetype == 'file') {
      callback('mypage.html', { text: 'My text' });
    }

    // 为图片对话框提供图片和替代文本
    if (meta.filetype == 'image') {
      callback('myimage.jpg', { alt: 'My alt text' });
    }

    // 为媒体对话框提供替代源和海报
    if (meta.filetype == 'media') {
      callback('movie.mp4', { source2: 'alt.ogg', poster: 'image.jpg' });
    }
  }
});

交互式示例

HTML

<textarea id="file-picker"></textarea>

JS

tinymce.init({
  selector: 'textarea#file-picker',
  plugins: 'image code',
  toolbar: 'undo redo | link image | code',
  /* enable title field in the Image dialog*/
  image_title: true,
  /* enable automatic uploads of images represented by blob or data URIs*/
  automatic_uploads: true,
  /*
    URL of our upload handler (for more details check: https://www.tiny.cloud/docs/configure/file-image-upload/#images_upload_url)
    images_upload_url: 'postAcceptor.php',
    here we add custom filepicker only to Image dialog
  */
  file_picker_types: 'image',
  /* and here's our custom image picker*/
  file_picker_callback: (cb, value, meta) => {
    const input = document.createElement('input');
    input.setAttribute('type', 'file');
    input.setAttribute('accept', 'image/*');

    input.addEventListener('change', (e) => {
      const file = e.target.files[0];

      const reader = new FileReader();
      reader.addEventListener('load', () => {
        /*
          Note: Now we need to register the blob in TinyMCEs image blob
          registry. In the next release this part hopefully won't be
          necessary, as we are looking to handle it internally.
        */
        const id = 'blobid' + (new Date()).getTime();
        const blobCache =  tinymce.activeEditor.editorUpload.blobCache;
        const base64 = reader.result.split(',')[1];
        const blobInfo = blobCache.create(id, file, base64);
        blobCache.add(blobInfo);

        /* call the callback and populate the Title field with the file name */
        cb(blobInfo.blobUri(), { title: file.name });
      });
      reader.readAsDataURL(file);
    });

    input.click();
  },
  content_style: 'body { font-family:Helvetica,Arial,sans-serif; font-size:16px }'
});

定制图像和文件的处理方式

images_upload_handler

通过此选项，您可以指定一个函数，该函数用于使用自定义逻辑替换 TinyMCE 的默认 JavaScript 上传处理函数。

上传处理函数接受两个参数：

  • blobInfo

  • 一个接受 1 到 100 之间数值的 progress 回调函数。

并且返回一个 Promise，该 Promise 会以上传图像的 URL 为结果进行解析，或以错误为结果进行拒绝。错误可以是字符串，也可以是包含以下属性的对象：

  • message - 要在 UI 中显示的错误消息。

  • remove - 从文档中移除图像的标志，如果未设置，则默认为 false。

当未设置此选项时，TinyMCE 会使用 XMLHttpRequest 一次将一张图像上传到服务器，并使用服务器返回的远程图像的 JSON location 属性来解析 Promise。

类型： 函数

示例：使用 images_upload_handler

const example_image_upload_handler = (blobInfo, progress) => new Promise((resolve, reject) => {
  const xhr = new XMLHttpRequest();
  xhr.withCredentials = false;
  xhr.open('POST', 'postAcceptor.php');

  xhr.upload.onprogress = (e) => {
    progress(e.loaded / e.total * 100);
  };

  xhr.onload = () => {
    if (xhr.status === 403) {
      reject({ message: 'HTTP Error: ' + xhr.status, remove: true });
      return;
    }

    if (xhr.status < 200 || xhr.status >= 300) {
      reject('HTTP Error: ' + xhr.status);
      return;
    }

    const json = JSON.parse(xhr.responseText);

    if (!json || typeof json.location != 'string') {
      reject('Invalid JSON: ' + xhr.responseText);
      return;
    }

    resolve(json.location);
  };

  xhr.onerror = () => {
    reject('Image upload failed due to a XHR Transport error. Code: ' + xhr.status);
  };

  const formData = new FormData();
  formData.append('file', blobInfo.blob(), blobInfo.filename());

  xhr.send(formData);
});

tinymce.init({
  selector: 'textarea',  // 根据您的 HTML 更改此值
  images_upload_handler: example_image_upload_handler
});

images_upload_url

通过此选项，您可以指定服务器端上传处理程序的 URL。每当您调用 editor.uploadImages() 或（如果启用了 automatic_uploads 选项则自动）时，将触发上传。上传处理程序应按以下格式返回上传文件的新位置：

{ "location": "folder/sub-folder/new-location.png" }

请务必查看服务器端上传处理程序的演示实现（用 PHP 编写）此处。

类型： 字符串

示例：使用 images_upload_url

tinymce.init({
  selector: 'textarea',  // 根据您的 HTML 更改此值
  images_upload_url: 'postAcceptor.php'
});

files_upload_handler

此选项指定一个函数，该函数处理链接对话框中上传标签页内的文件上传。这类似于 images_upload_handler，但专门为文档和文件上传设计。

上传处理函数接受两个参数：

  • blobInfo - 一个包含要上传的文件 blob 信息的对象。

  • 一个接受 1 到 100 之间数值的 progress 回调函数。

并返回一个 Promise，该 Promise 会解析为包含上传文件 url 和 fileName 的对象，或者因错误而拒绝。解析的对象必须具有以下结构：

  • url - 上传文件的 URL

  • fileName - 上传文件的文件名

错误可以是字符串，也可以是包含以下属性的对象：

  • message - 要在 UI 中显示的错误消息。

  • remove - 一个用于从文档中移除文件的标志，如果未设置则默认为 false。

当同时配置了 files_upload_handler 和 documents_file_types 时，链接对话框会显示一个“上传”选项卡，该选项卡允许通过 files_upload_handler 定义的函数上传文件。

类型： Function

默认值： undefined

示例：使用 files_upload_handler

此示例展示一个客户端 JavaScript 处理程序，该处理程序将文件上传到服务器端点。服务器应返回一个包含 location 属性的 JSON 响应，该属性包含上传文件的 URL。

const files_upload_handler = (blobInfo, progress) => new Promise((resolve, reject) => {
  const xhr = new XMLHttpRequest();
  xhr.withCredentials = false;
  xhr.open('POST', 'upload-handler.php');

  xhr.upload.onprogress = (e) => {
    progress(e.loaded / e.total * 100);
  };

  xhr.onload = () => {
    if (xhr.status === 403) {
      reject({ message: 'HTTP Error: ' + xhr.status, remove: true });
      return;
    }

    if (xhr.status < 200 || xhr.status >= 300) {
      reject('HTTP Error: ' + xhr.status);
      return;
    }

    const json = JSON.parse(xhr.responseText);

    if (!json || typeof json.location != 'string') {
      reject('Invalid JSON: ' + xhr.responseText);
      return;
    }

    resolve({
      url: json.location,
      fileName: blobInfo.filename()
    });
  };

  xhr.onerror = () => {
    reject('File upload failed due to a XHR Transport error. Code: ' + xhr.status);
  };

  const formData = new FormData();
  formData.append('file', blobInfo.blob(), blobInfo.filename());

  xhr.send(formData);
});

tinymce.init({
  selector: 'textarea',
  plugins: 'link',
  toolbar: 'link',
  files_upload_handler: files_upload_handler,
  documents_file_types: [
    { mimeType: 'application/pdf', extensions: [ 'pdf' ] },
    { mimeType: 'application/msword', extensions: [ 'doc' ] },
    { mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', extensions: [ 'docx' ] },
    { mimeType: 'text/plain', extensions: [ 'txt' ] }
  ]
});

服务器端处理程序要求

服务器端点（例如上述示例中的 upload-handler.php）应该：

  • 接受包含文件的 POST 请求（以 FormData 形式发送，字段名为 file）

  • 返回一个包含 location 属性的 JSON 响应，该属性包含上传文件的 URL：{ "location": "<path-to-your-web-server>/uploaded/file.pdf" }

  • 通过返回适当的 HTTP 状态码来处理错误（例如，403 表示禁止的文件类型，400 表示无效请求，500 表示服务器错误）

  • 如果需要跨域请求，则设置适当的 CORS 标头

这类似于 images_upload_url 的工作方式，但 files_upload_handler 让您可以完全控制客户端上传逻辑，包括自定义错误处理、进度跟踪和请求自定义。

documents_file_types

此选项指定链接对话框中文件上传支持的文件类型（MIME 类型和扩展名）。当同时配置了 Link 插件和 files_upload_handler 时，链接对话框会显示一个“上传”选项卡，该选项卡允许文件上传。

该选项应该是一个对象数组，其中每个对象包含：

  • mimeType - 表示 MIME 类型的字符串（例如，'application/pdf'）

  • extensions - 表示文件扩展名的字符串数组（例如，['pdf']）

类型： Array

默认值： undefined

优先级行为

当设置了 documents_file_types 时，它在整个编辑器中作为支持的文件类型的可靠来源。这意味着：

  • Link 插件使用此自定义列表，而不是其默认支持的文件类型

如果未设置 documents_file_types：

  • Link 插件使用其默认的支持文件类型列表

示例：使用 documents_file_types

tinymce.init({
  selector: 'textarea',
  plugins: 'link',
  toolbar: 'link',
  // 配置文件上传处理程序以处理文件上传
  files_upload_handler: async (blobInfo, progress) => {
    return { url: 'https://example.com/file.pdf', fileName: 'file.pdf' };
  },
  // 配置支持的文件类型列表
  documents_file_types: [
    { mimeType: 'application/msword', extensions: [ 'doc' ] },
    { mimeType: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', extensions: [ 'docx' ] },
    { mimeType: 'application/pdf', extensions: [ 'pdf' ] },
    { mimeType: 'text/plain', extensions: [ 'txt' ] }
  ]
});

用于改进自定义文件处理的选项

automatic_uploads

启用或禁用由 data URLs 或 blob URIs 表示的图像的自动上传。例如，当通过 Image Editing 插件对图像进行操作后，或者将图像从桌面拖放到编辑器中后，会生成此类图像。

如果未指定 images_upload_url 或 images_upload_handler，此选项将不起作用。

类型： Boolean

默认值： true

可能的值： true, false

示例：使用 automatic_uploads

tinymce.init({
  selector: 'textarea',  // 根据您的 HTML 更改此值
  images_upload_url: 'postAcceptor.php',
  automatic_uploads: false
});

images_upload_base_path

此选项允许您指定一个 basepath，将其添加到从配置的 images_upload_url 页面返回的 URL 前面。

类型： String

示例：使用 images_upload_base_path

tinymce.init({
  selector: 'textarea',  // 根据您的 HTML 更改此值
  images_upload_url: 'postAcceptor.php',
  images_upload_base_path: '/some/basepath'
});

images_upload_credentials

images_upload_credentials 选项指定对配置的 images_upload_url 的调用是否应传递凭据（如 cookies、授权头或 TLS 客户端证书）以进行跨域上传。当设置为 true 时，凭据将被发送到上传处理程序，类似于 XMLHttpRequest 的 withCredentials 属性。

类型： Boolean

默认值： false

可能的值： true, false

示例：使用 images_upload_credentials

tinymce.init({
  selector: 'textarea',  // 根据您的 HTML 更改此值
  images_upload_url: 'postAcceptor.php',
  images_upload_credentials: true
});

images_reuse_filename

默认情况下，TinyMCE 将为每个上传的文件生成唯一的文件名（有关详细信息，请参阅 Upload Images）。有时这可能会产生不良的副作用。例如，当启用 automatic_uploads 时，使用 Image Editing 插件对图像进行的每一次操作都会导致文件上传，并且每次都使用不同的文件名，尽管图像本身并没有改变。

将 images_reuse_filename 设置为 true 可让 TinyMCE 使用图像的实际文件名，而不是每次都生成一个新的文件名。请注意，相应 <img> 标签的 src 属性将被您从服务器返回的任何文件名替换（请参阅 images_upload_url）。它可以是相同的文件名或其他名称，但下次将使用该文件名进行上传。

类型： Boolean

默认值： false

可能的值： true, false

示例：使用 images_reuse_filename

tinymce.init({
  selector: 'textarea',  // 根据您的 HTML 更改此值
  automatic_uploads: true,
  images_upload_url: 'postAcceptor.php',
  images_reuse_filename: true
});