@ckeditor/ckeditor5-link
- Version 40.1.0
- Published
- 395 kB
- 3 dependencies
- GPL-2.0-or-later license
Install
npm i @ckeditor/ckeditor5-link
yarn add @ckeditor/ckeditor5-link
pnpm add @ckeditor/ckeditor5-link
Overview
Link feature for CKEditor 5.
Index
Classes
Interfaces
Type Aliases
Classes
class AutoLink
class AutoLink extends Plugin {}
The autolink plugin.
property pluginName
static readonly pluginName: string;
property requires
static readonly requires: readonly [any];
method afterInit
afterInit: () => void;
method init
init: () => void;
class Link
class Link extends Plugin {}
The link plugin.
This is a "glue" plugin that loads the and .
property pluginName
static readonly pluginName: string;
property requires
static readonly requires: readonly [ typeof LinkEditing, typeof LinkUI, typeof AutoLink];
class LinkCommand
class LinkCommand extends Command {}
The link command. It is used by the .
property automaticDecorators
readonly automaticDecorators: AutomaticDecorators;
An instance of the helper that ties together all that are used by the and the features.
property manualDecorators
readonly manualDecorators: Collection<ManualDecorator>;
A collection of corresponding to the .
You can consider it a model with states of manual decorators added to the currently selected link.
property value
value: string;
The value of the
'linkHref'
attribute if the start of the selection is located in a node with this attribute.Modifiers
@readonly
method execute
execute: (href: string, manualDecoratorIds?: Record<string, boolean>) => void;
Executes the command.
When the selection is non-collapsed, the
linkHref
attribute will be applied to nodes inside the selection, but only to those nodes where thelinkHref
attribute is allowed (disallowed nodes will be omitted).When the selection is collapsed and is not inside the text with the
linkHref
attribute, a new with thelinkHref
attribute will be inserted in place of the caret, but only if such element is allowed in this place. The_data
of the inserted text will equal thehref
parameter. The selection will be updated to wrap the just inserted text node.When the selection is collapsed and inside the text with the
linkHref
attribute, the attribute value will be updated.# Decorators and model attribute management
There is an optional argument to this command that applies or removes model brought by .
Text attribute names in the model correspond to the entries in the . For every decorator configured, a model text attribute exists with the "link" prefix. For example, a
'linkMyDecorator'
attribute corresponds to'myDecorator'
in the configuration.To learn more about link decorators, check out the documentation.
Here is how to manage decorator attributes with the link command:
const linkCommand = editor.commands.get( 'link' );// Adding a new decorator attribute.linkCommand.execute( 'http://example.com', {linkIsExternal: true} );// Removing a decorator attribute from the selection.linkCommand.execute( 'http://example.com', {linkIsExternal: false} );// Adding multiple decorator attributes at the same time.linkCommand.execute( 'http://example.com', {linkIsExternal: true,linkIsDownloadable: true,} );// Removing and adding decorator attributes at the same time.linkCommand.execute( 'http://example.com', {linkIsExternal: false,linkFoo: true,linkIsDownloadable: false,} );**Note**: If the decorator attribute name is not specified, its state remains untouched.
**Note**: removes all decorator attributes.
execute
Parameter href
Link destination.
Parameter manualDecoratorIds
The information about manual decorator attributes to be applied or removed upon execution.
method refresh
refresh: () => void;
method restoreManualDecoratorStates
restoreManualDecoratorStates: () => void;
Synchronizes the state of with the currently present elements in the model.
class LinkEditing
class LinkEditing extends Plugin {}
The link engine feature.
It introduces the
linkHref="url"
attribute in the model which renders to the view as a<a href="url">
element as well as'link'
and'unlink'
commands.
constructor
constructor(editor: Editor);
property pluginName
static readonly pluginName: string;
property requires
static readonly requires: readonly [any, any, any];
method init
init: () => void;
class LinkImage
class LinkImage extends Plugin {}
The
LinkImage
plugin.This is a "glue" plugin that loads the and .
property pluginName
static readonly pluginName: string;
property requires
static readonly requires: readonly [typeof LinkImageEditing, typeof LinkImageUI];
class LinkImageEditing
class LinkImageEditing extends Plugin {}
The link image engine feature.
It accepts the
linkHref="url"
attribute in the model for the element which allows linking images.
property pluginName
static readonly pluginName: string;
property requires
static readonly requires: readonly [ 'ImageEditing', 'ImageUtils', typeof LinkEditing];
method init
init: () => void;
class LinkImageUI
class LinkImageUI extends Plugin {}
The link image UI plugin.
This plugin provides the
'linkImage'
button that can be displayed in the . It can be used to wrap images in links.
property pluginName
static readonly pluginName: string;
property requires
static readonly requires: readonly [ typeof LinkEditing, typeof LinkUI, 'ImageBlockEditing'];
method init
init: () => void;
class LinkUI
class LinkUI extends Plugin {}
The link UI plugin. It introduces the
'link'
and'unlink'
buttons and support for the Ctrl+K keystroke.It uses the .
property actionsView
actionsView: LinkActionsView;
The actions view displayed inside of the balloon.
property formView
formView: any;
The form view displayed inside the balloon.
property pluginName
static readonly pluginName: string;
property requires
static readonly requires: readonly [any];
method destroy
destroy: () => void;
method init
init: () => void;
class UnlinkCommand
class UnlinkCommand extends Command {}
The unlink command. It is used by the .
method execute
execute: () => void;
Executes the command.
When the selection is collapsed, it removes the
linkHref
attribute from each node with the samelinkHref
attribute value. When the selection is non-collapsed, it removes thelinkHref
attribute from each node in selected ranges.# Decorators
If is specified, all configured decorators are removed together with the
linkHref
attribute.execute
method refresh
refresh: () => void;
Interfaces
interface LinkConfig
interface LinkConfig {}
The configuration of the .
ClassicEditor.create( editorElement, {link: ... // Link feature configuration.} ).then( ... ).catch( ... );See .
property addTargetToExternalLinks
addTargetToExternalLinks?: boolean;
When set to
true
, thetarget="blank"
andrel="noopener noreferrer"
attributes are automatically added to all external links in the editor. "External links" are all links in the editor content starting withhttp
,https
, or//
.ClassicEditor.create( editorElement, {link: {addTargetToExternalLinks: true}} ).then( ... ).catch( ... );Internally, this option activates a predefined that extends all external links with the
target
andrel
attributes.**Note**: To control the
target
andrel
attributes of specific links in the edited content, a dedicated decorator must be defined in the array. In such scenario, theconfig.link.addTargetToExternalLinks
option should remainundefined
orfalse
to not interfere with the manual decorator.It is possible to add other or link decorators when this option is active.
More information about decorators can be found in the reference.
false
property decorators
decorators?: Record<string, LinkDecoratorDefinition>;
Decorators provide an easy way to configure and manage additional link attributes in the editor content. There are two types of link decorators:
* – They match links against pre–defined rules and manage their attributes based on the results. * – They allow users to control link attributes individually, using the editor UI.
Link decorators are defined as objects with key-value pairs, where the key is the name provided for a given decorator and the value is the decorator definition.
The name of the decorator also corresponds to the in the model. For instance, the
isExternal
decorator below is represented as alinkIsExternal
attribute in the model.ClassicEditor.create( editorElement, {link: {decorators: {isExternal: {mode: 'automatic',callback: url => url.startsWith( 'http://' ),attributes: {target: '_blank',rel: 'noopener noreferrer'}},isDownloadable: {mode: 'manual',label: 'Downloadable',attributes: {download: 'file.png',}},// ...}}} ).then( ... ).catch( ... );To learn more about the configuration syntax, check out the and decorator option reference.
**Warning:** Currently, link decorators work independently of one another and no conflict resolution mechanism exists. For example, configuring the
target
attribute using both an automatic and a manual decorator at the same time could end up with quirky results. The same applies if multiple manual or automatic decorators were defined for the same attribute.**Note**: Since the
target
attribute management for external links is a common use case, there is a predefined automatic decorator dedicated for that purpose which can be enabled by turning a single option on. Check out the configuration description to learn more.See also the for more information.
property defaultProtocol
defaultProtocol?: string;
When set, the editor will add the given protocol to the link when the user creates a link without one. For example, when the user is creating a link and types
ckeditor.com
in the link form input, during link submission the editor will automatically add thehttp://
protocol, so the link will look as follows:http://ckeditor.com
.The feature also provides email address auto-detection. When you submit
hello@example.com
, the plugin will automatically change it tomailto:hello@example.com
.ClassicEditor.create( editorElement, {link: {defaultProtocol: 'http://'}} ).then( ... ).catch( ... );**NOTE:** If no configuration is provided, the editor will not auto-fix the links.
Type Aliases
type LinkDecoratorDefinition
type LinkDecoratorDefinition = | LinkDecoratorAutomaticDefinition | LinkDecoratorManualDefinition;
A link decorator definition. Two types implement this definition:
* *
Refer to their document for more information about available options or to the for general information.
Package Files (11)
Dependencies (3)
Dev Dependencies (0)
No dev dependencies.
Peer Dependencies (0)
No peer dependencies.
Badge
To add a badge like this oneto your package's README, use the codes available below.
You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@ckeditor/ckeditor5-link
.
- Markdown[](https://www.jsdocs.io/package/@ckeditor/ckeditor5-link)
- HTML<a href="https://www.jsdocs.io/package/@ckeditor/ckeditor5-link"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>
- Updated .
Package analyzed in 4468 ms. - Missing or incorrect documentation? Open an issue for this package.