链接

链接功能允许您在内容中插入超链接，并提供 UI 来创建和编辑它们。由于 自动链接 插件，您键入或粘贴的 URL 和电子邮件地址会自动转换为有效的链接。

# 演示

使用链接工具栏按钮 或按 Ctrl/Cmd+K 创建新链接。单击链接会打开上下文工具栏。工具栏允许您通过单击来编辑现有链接 或取消链接它们 。

# 链接周围的输入

CKEditor 5 允许在链接的内部和外部边界处进行输入，使编辑对用户来说更容易。

要在链接内输入，将光标移动到其（开始或结束）边界。只要链接保持突出显示（默认情况下：蓝色），输入和应用格式将在其边界内进行

要在链接之前或之后输入，将光标移动到其边界，然后按一次箭头键 (← 或 →) 离开链接。链接不再突出显示，并且您键入的任何文本或应用的任何格式都不会在链接内

# 安装

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

import { ClassicEditor, AutoLink, Link } from 'ckeditor5';

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        plugins: [ Link, AutoLink, /* ... */ ],
        toolbar: [ 'link', /* ... */ ],
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 自定义链接属性（装饰器）

默认情况下，在编辑器中创建的所有链接都在 编辑器数据 中的 编辑器数据 中具有 href="..." 属性。如果您希望您的链接具有其他链接属性，链接装饰器 提供了一种简单的方法来配置和管理它们。

您可以使用两种类型的链接装饰器

• 自动 – 它们将链接与预定义规则进行匹配，并根据结果管理其属性。
• 手动 – 它们允许用户使用编辑器 UI 单独控制链接属性。

# 演示

在下面的编辑器中，所有外部链接都获得 target="_blank" 和 rel="noopener noreferrer" 属性 (自动装饰器)。单击一个链接并对其进行编辑 以查看您可以使用编辑气泡中的切换按钮来控制特定链接的 download 属性 (手动装饰器)。查看下面的编辑器数据（实时更新）以查看额外的链接属性。

以下代码运行此编辑器。了解更多关于该功能的配置。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        toolbar: {
            items: [
                'link',
                // More toolbar items.
                // ...
            ],
        },
        link: {
            // Automatically add target="_blank" and rel="noopener noreferrer" to all external links.
            addTargetToExternalLinks: true,

            // Let the users control the "download" attribute of each link.
            decorators: [
                {
                    mode: 'manual',
                    label: 'Downloadable',
                    attributes: {
                        download: 'download'
                    }
                }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 配置

您可以通过在 config.link.decorators 配置选项中提供的定义来配置装饰器。

每个装饰器定义必须具有唯一的名称。对于手动装饰器，名称也代表文档模型中的装饰器。

# 向外部链接添加target 和 rel 属性

（自动）链接装饰器的常见用例是向文档中的所有外部链接添加target="_blank" 和 rel="noopener noreferrer" 属性。专门的config.link.addTargetToExternalLinks 配置适用于此目的。当您将此选项设置为true 时，所有以http://、https:// 或 // 开头的链接都将使用target 和 rel 属性“装饰”。

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        link: {
            addTargetToExternalLinks: true
        }
        // More of the editor's configuration.
            // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

在内部，此配置对应于一个自动装饰器，其具有以下定义

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        link: {
            decorators: {
                addTargetToExternalLinks: {
                    mode: 'automatic',
                    callback: url => /^(https?:)?\/\//.test( url ),
                    attributes: {
                        target: '_blank',
                        rel: 'noopener noreferrer'
                    }
                }
            }
        }
        // More of the editor's configuration.
            // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

如果您希望将是否在新标签页中打开链接的决定留给用户，请不要使用config.link.addTargetToExternalLinks 配置。而是定义一个新的手动装饰器，其具有以下定义

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        link: {
            decorators: {
                openInNewTab: {
                    mode: 'manual',
                    label: 'Open in a new tab',
                    attributes: {
                        target: '_blank',
                        rel: 'noopener noreferrer'
                    }
                }
            }
        }
        // More of the editor's configuration.
            // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 向外部链接添加默认链接协议

当用户忘记键入到外部源或网站的完整 URL 地址时，默认链接协议可能很有用。有时复制文本（例如ckeditor.com）并将其转换为链接可能会导致一些问题。因此，创建的链接会将您定向到yourdomain.com/ckeditor.com，因为缺少协议。这使得链接相对于其出现的位置的站点是相对的。

在您启用config.link.defaultProtocol 配置选项后，链接功能将能够为您处理此问题。默认情况下，它不会修复传递的链接值，但是当您将config.link.defaultProtocol 设置为（例如）http:// 时，插件将向可能需要它的每个链接（如ckeditor.com、example.com 等，其中缺少[protocol://]example.com）添加给定的协议。

查看基本的配置示例

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        link: {
            defaultProtocol: 'http://'
        }
        // More of the editor's configuration.
            // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 在链接中添加自定义协议

默认情况下，允许在链接中使用最少的协议集。任何带有无法识别的协议的 URL 将被更改为“#”。您可以使用config.link.allowedProtocols 覆盖协议列表。

查看配置示例

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        link: {
            // You can use `s?` suffix like below to allow both `http` and `https` protocols at the same time.
            allowedProtocols: [ 'https?', 'tel', 'sms', 'sftp', 'smb', 'slack' ]
        }
        // More of the editor's configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 根据预定义规则添加属性（自动装饰器）

自动链接装饰器将编辑器内容中的所有链接与一个函数进行匹配，该函数决定链接是否应该接收某些属性集，同时考虑链接的 URL（href）。这些装饰器会静默地工作，编辑器会在数据向下转换期间应用它们。

例如，要创建一个自动装饰器，该装饰器将download="file.pdf" 属性添加到所有以".pdf" 扩展名结尾的链接，您应该将以下定义添加到config.link.decorators

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        link: {
            decorators: {
                detectDownloadable: {
                    mode: 'automatic',
                    callback: url => url.endsWith( '.pdf' ),
                    attributes: {
                        download: 'file.pdf'
                    }
                }
            }
        }
        // More of the editor's configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 使用 UI 添加属性（手动装饰器）

手动链接装饰器在链接编辑气球中以切换按钮的形式表示。用户可以使用它们来控制特定链接属性的存在（查看演示了解更多信息）。每个手动装饰器定义都有一个易于理解的标签，显示在链接编辑气球中切换按钮旁边。确保它简洁明了，方便用户使用。

要在链接编辑气球中配置一个“可下载”切换按钮，该按钮在打开时将download="file" 属性添加到链接，请将以下定义添加到config.link.decorators

ClassicEditor
    .create( document.querySelector( '#editor' ), {
        link: {
            decorators: {
                toggleDownloadable: {
                    mode: 'manual',
                    label: 'Downloadable',
                    attributes: {
                        download: 'file'
                    }
                },
                openInNewTab: {
                    mode: 'manual',
                    label: 'Open in a new tab',
                    defaultValue: true,			// This option will be selected by default.
                    attributes: {
                        target: '_blank',
                        rel: 'noopener noreferrer'
                    }
                }
            }
        }
        // More of the editor's configuration.
        // ...
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

# 自动链接功能

The AutoLink 功能会自动将 URL 或电子邮件地址转换为工作链接。

要使用自动链接功能，请在链接后按空格键、回车键 或 Shift+回车键。

# 通用 API

The Link 插件注册 UI 按钮组件（'link'）和以下命令

• The 'link' 命令由LinkCommand 实现。
• The 'unlink' 命令由UnlinkCommand 实现。

您可以使用editor.execute() 方法执行命令

// Applies the link to the selected content.
// When the selection is collapsed, it creates new text wrapped in a link.
editor.execute( 'link', 'http://example.com' );

// If there are decorators configured, the command can set their state.
editor.execute( 'link', 'http://example.com', { linkIsExternal: true } );

// Removes the link from the selection (and all decorators if present).
editor.execute( 'unlink' );

该包为链接图像 提供了一个插件。请参阅链接图像 指南，该指南位于图像部分中。

链接在模型 中使用linkHref 属性表示。手动链接装饰器 在模型中使用对应于其名称的文本属性表示，如在config.link.decorators 中配置的那样。

# 贡献

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