链接

link 插件允许用户将外部资源（如网站 URL）链接到文档中选中的文本。

该插件添加了两个工具栏按钮 link 和 unlink，以及三个菜单项 link、unlink 和 openlink。名为 link 的工具栏按钮和菜单项包含在 TinyMCE 的默认配置中。link 菜单项可在 Insert 菜单中找到。

link 插件还包含上下文菜单和上下文工具栏。可以通过下文所述的 link_context_toolbar 和 link_quicklink 选项来配置上下文工具栏。

基本设置

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配您的 HTML
  plugins: 'link',
  toolbar: 'link'
});

有关通过模块打包器捆绑此插件的信息，请参阅 Bundling TinyMCE - Overview。

选项

这些设置影响 link 插件的执行。可以在此处指定预定义的链接、目标等。

link_default_target

此选项允许您在通过链接对话框插入/编辑链接时，为链接设置一个默认的 target 值。如果 link_default_target 的值与 link_target_list 选项中指定的某个值匹配，那么该选项项将作为链接对话框中目标下拉列表的默认项。

此选项也适用于 autolink 插件。

类型： String

示例：使用 link_default_target

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配您的 HTML
  plugins: 'link',
  toolbar: 'link',
  link_default_target: '_blank'
});

link_assume_external_targets

设置当提供的 URL 不包含协议前缀时，TinyMCE 是否应自动添加 http:// 前缀。

• false：当用户输入的 URL 以 www 开头且没有协议时，系统将提示用户添加 http:// 前缀。其他 URL 将直接添加，无需提示。

• true：URL 被视为外部链接。当未指定协议时，系统将提示用户添加 http:// 前缀。

• 'http'：URL 被视为外部链接。对于没有协议前缀的 URL，将自动添加 http:// 前缀。

• 'https'：URL 被视为外部链接。对于没有协议前缀的 URL，将自动添加 https:// 前缀。

类型： Boolean 或 String

默认值： false

可能的值： true、false、'http'、'https'

示例：使用 link_assume_external_targets

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配您的 HTML
  plugins: 'link',
  toolbar: 'link',
  link_assume_external_targets: true
});

link_class_list

link_class_list 选项允许您为链接对话框指定一个类列表。这些类将显示在链接对话框的下拉菜单中。每个类必须定义为一个包含 title 和 value 的对象。例如：{ title: 'Cat', value: 'cat' }。当提交对话框时，从下拉列表中选择的类项的 value 将被设置为链接的 class。

类型： Array

默认值： []

示例：使用 link_class_list

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配您的 HTML
  plugins: 'link',
  toolbar: 'link',
  link_class_list: [
    { title: 'None', value: '' },
    { title: 'External Link', value: 'ext_link' },
    { title: 'Internal Support Link', value: 'int_sup_link' },
    { title: 'Internal Marketing Link', value: 'int_mark_link' },
    { title: 'Other Internal Link', value: 'int_other_link' }
  ]
});

链接类嵌套列表示例

要创建嵌套列表，请将 value 替换为 menu 以添加列表的顶级项，然后提供一个包含多个项的数组。

例如：

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配您的 HTML
  plugins: 'link',
  toolbar: 'link',
  link_class_list: [
    { title: 'None', value: '' },
    { title: 'External Link', value: 'ext_link' },
    { title: 'Internal Links',
      menu: [
        { title: 'Internal Support Link', value: 'int_sup_link' },
        { title: 'Internal Marketing Link', value: 'int_mark_link' },
        { title: 'Other Internal Link', value: 'int_other_link' }
      ]
    }
  ]
});

link_context_toolbar

默认情况下，无法直接从编辑器中打开链接。将 link_context_toolbar 设置为 true 将启用上下文工具栏，当用户的光标位于链接内时，该工具栏将出现。此上下文工具栏包含用于修改、删除和打开所选链接的字段。外部链接将在单独的标签页中打开，而相对链接将滚动到编辑器内的目标（如果找到目标）。

此上下文工具栏与 Link 插件中提到的上下文工具栏相同 - link_quicklink 文档。

类型： Boolean

默认值： false

可能的值： true, false

示例：使用 link_context_toolbar

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配您的 HTML
  plugins: 'link',
  toolbar: 'link',
  link_context_toolbar: true
});

link_default_protocol

此选项允许您设置通过链接对话框插入/编辑链接时的默认协议。该协议将应用于未指定协议且已接受前缀提示的任何链接。

此选项也适用于 autolink 插件。

类型： String

默认值： 'https'

示例：使用 link_default_protocol

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配您的 HTML
  plugins: 'link',
  toolbar: 'link',
  link_default_protocol: 'http'
});

link_list

此选项允许您为链接对话框指定一个预定义的链接列表。这些链接将添加到链接对话框的下拉列表中。当选择某个列表项时，对话框将填充相关数据。如果您的用户需要经常链接到相同的来源，此选项非常有用。

有多种方式可以指定如何获取链接列表的数据，但所有方法都依赖于返回的数据包含一个链接项数组。链接项是一个包含 title 和 value 的对象。例如：{ title: 'My page 1', value: 'https://www.tiny.cloud' }。

类型： String, Array 或 Function

链接项数组示例

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配您的 HTML
  plugins: 'link',
  toolbar: 'link',
  link_list: [
    { title: '{companyname} Home Page', value: '{companyurl}' },
    { title: '{companyname} Blog', value: '{companyurl}/blog' },
    { title: '{productname} Documentation', value: '{companyurl}/docs/' },
    { title: '{productname} on Stack Overflow', value: '{communitysupporturl}' },
    { title: '{productname} GitHub', value: 'https://github.com/tinymce/' }
  ]
});

嵌套链接项列表示例

要创建嵌套列表，请将 value 替换为 menu 以添加列表的顶级，然后提供一个项目数组。

例如：

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配您的 HTML
  plugins: 'link',
  toolbar: 'link',
  link_list: [
    { title: '{companyname} Home Page', value: '{companyurl}' },
    { title: '{companyname} Blog', value: '{companyurl}/blog' },
    { title: '{productname} Support resources',
      menu: [
        { title: '{productname} Documentation', value: '{companyurl}/docs/' },
        { title: '{productname} on Stack Overflow', value: '{communitysupporturl}' },
        { title: '{productname} GitHub', value: 'https://github.com/tinymce/' }
      ]
    }
  ]
});

返回 JSON 链接项数组的外部脚本示例

您还可以配置一个包含 JSON 数据的 URL。JSON 数据必须使用与上述相同的格式。

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配您的 HTML
  plugins: 'link',
  toolbar: 'link',
  link_list: '/mylist.php'
});

自定义异步回调函数示例

link_list 还可以接收一个函数，该函数在链接对话框打开时调用。TinyMCE 会将此函数传递一个 success 回调函数，该函数应传递一个链接项数组。这样可以异步和动态地生成链接列表。

以下是一个如何将 link_list 与回调函数一起使用的示例。fetchLinkList 可以替换为任何返回链接项数组的函数。它可以用于基于以下内容生成链接项列表：

• 从数据库中检索的数据。

• 当前编辑器内容。

• 当前用户。

const fetchLinkList = () => [
  { title: 'My page 1', value: 'https://www.tiny.cloud' },
  { title: 'My page 2', value: 'https://about.tiny.cloud' }
];

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配您的 HTML
  plugins: 'link',
  toolbar: 'link',
  link_list: (success) => { // 链接对话框打开时调用
    const links = fetchLinkList(); // 获取 link_list 数据
    success(links); // 将 link_list 数据传递给 {productname}
  }
});

link_title

此选项允许您禁用 link 对话框中的链接 title 输入字段。

类型： Boolean

默认值： true

可能的值： true, false

示例：使用 link_title

tinymce.init({
  selector: 'textarea',  // 根据需要修改此值以匹配您的 HTML
  plugins: 'link',
  toolbar: 'link',
  link_title: false
});

link_quicklink

此选项更改 CTRL + K 快捷键和 mceLink 命令的行为。

当 link_quicklink 设置为 false 时，按下 CTRL + K 或执行 mceLink 命令将打开链接对话框。

当 link_quicklink 设置为 true 时，按下 CTRL + K 将打开链接上下文工具栏，不过仍然可以通过运行 editor.execCommand('mceLink', false, { dialog: true }) 来打开链接对话框。

当选中一个链接时，链接上下文工具栏包含用于修改、删除和打开所选链接的字段和按钮。当所选内容不包含链接时，链接上下文工具栏包含用于快速插入链接的字段和按钮。

此上下文工具栏与上述 link_context_toolbar 文档中提到的上下文工具栏相同。

类型： Boolean

默认值： false

可能的值： true、false

示例：使用 link_quicklink

tinymce.init({
  selector: 'textarea',  // 根据你的 HTML 更改此值
  plugins: 'link',
  toolbar: 'link',
  link_quicklink: true
});

link_rel_list

此选项允许你为 link 对话框指定一个 rel 值列表。这些值将被应用到 rel 属性。每个 rel 项必须定义为一个包含 title 和 value 的对象。例如：{ title: 'No Referrer', value: 'noreferrer' }。当对话框提交时，所选 rel 项的 value 将被设置为链接的 rel 属性。

类型： Array

默认值： []

示例：使用 link_rel_list

tinymce.init({
  selector: 'textarea',  // 根据你的 HTML 更改此值
  plugins: 'link',
  toolbar: 'link',
  link_rel_list: [
    { title: 'No Referrer', value: 'noreferrer' },
    { title: 'External Link', value: 'external' }
  ]
});

link_target_list

link_target_list 选项允许你为 link 对话框指定一个命名目标列表。这些目标将显示在链接对话框的下拉菜单中。每个目标必须定义为一个包含 title 和 value 的对象。例如：{ title: 'Same page', value: '_self' }。当对话框提交时，所选目标项的 value 将被设置为链接的 target 属性。

如果同时配置了 link_default_target，并且其值与 link_target_list 中指定的值相匹配，那么该项将被设置为链接对话框中目标下拉菜单的默认项。

类型： Boolean 或 Array

可能的值： true、false、_blank、_self、_parent、_blank

默认值：

[
  { text: 'Current window', value: '' },
  { text: 'New window', value: '_blank' }
]

示例：将 _parent 目标添加到下拉列表中

tinymce.init({
  selector: 'textarea',  // 根据你的 HTML 更改此值
  plugins: 'link',
  toolbar: 'link',
  link_target_list: [
    { title: 'None', value: '' },
    { title: 'Same page', value: '_self' },
    { title: 'New page', value: '_blank' },
    { title: 'Parent frame', value: '_parent' }
  ]
});

要禁用该选项对话框，将 link_target_list 设置为 false。

示例：关闭目标列表对话框

tinymce.init({
  selector: 'textarea',  // 根据你的 HTML 更改此值
  plugins: 'link',
  toolbar: 'link',
  link_target_list: false
});

link_attributes_postprocess

此选项允许覆盖插入的链接的属性。

类型： Function

默认值： undefined

示例：使用 link_attributes_postprocess

tinymce.init({
  selector: 'textarea', // 根据你的 HTML 更改此值
  plugins: 'link',
  toolbar: 'link',
  link_attributes_postprocess: (attrs) => {
    console.log(attrs);
    if (attrs.rel) {
      attrs.rel += 'noreferrer';
    }
  }
});

files_upload_handler

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

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

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

• 一个 progress 回调函数，其值介于 1 到 100 之间

并返回一个 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处理程序，用于将文件上传到服务器端点。服务器应返回一个JSON响应，其中包含一个带有上传文件URL的location属性。

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）

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

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

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

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

documents_file_types

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

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

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

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

类型： Array

默认值： undefined

优先级行为

当设置了documents_file_types时，它将作为整个编辑器中支持的文件类型的唯一依据。这意味着：

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

如果未设置documents_file_types：

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

示例：使用 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' ] }
  ]
});

link_uploadtab

此选项控制是否在链接对话框中显示“上传”选项卡。当同时配置了files_upload_handler和documents_file_types时，上传选项卡允许上传文件。

如果设置为false，即使设置了另外两个选项，上传选项卡也会被隐藏。

类型： Boolean

默认值： true

可能的值： true, false

示例：隐藏链接对话框上传选项卡

tinymce.init({
  selector: 'textarea',
  plugins: 'link',
  toolbar: 'link',
	files_upload_handler: (blobInfo, _progress) => new Promise((success) => {
	  setTimeout(() => {
		success({ url: 'https://www.google.com/logos/google.jpg', fileName: 'test-in-demo' });
	  }, 2_000);
	}),
  documents_file_types: [
    { mimeType: 'application/pdf', extensions: [ 'pdf' ] }
  ],
  link_uploadtab: false  // 隐藏链接对话框上传选项卡
});

工具栏按钮

Link 插件提供以下工具栏按钮：

工具栏按钮标识符	描述
link	在编辑器内创建/编辑链接。
openlink	在新标签页中打开所选链接。
unlink	从当前所选内容中移除链接。

这些工具栏按钮可以通过以下方式添加到编辑器中：

• toolbar 配置选项。

• quickbars_insert_toolbar 配置选项。

• 自定义上下文工具栏。

菜单项

Link 插件提供以下菜单项：

菜单项标识符	默认菜单位置	描述
link	插入	打开链接对话框。
openlink	不适用	在新标签页中打开所选链接。
unlink	不适用	从所选文本中移除超链接。

这些菜单项可以通过以下方式添加到编辑器中：

• menu 配置选项。

• contextmenu 配置选项。

• 自定义菜单工具栏按钮。

命令

Link 插件提供以下 TinyMCE 命令。

命令	描述
mceLink	在当前光标位置或当前所选内容处打开链接对话框或链接上下文工具栏。具体行为取决于 link_quicklink 选项。即使启用了 link_quicklink，若作为第三个参数传入 { dialog: true }，也将始终打开完整的链接对话框。

示例：打开链接对话框或上下文工具栏（默认行为）

tinymce.activeEditor.execCommand('mceLink');

示例：始终打开完整的链接对话框

tinymce.activeEditor.execCommand('mceLink', false, { dialog: true });