Clipboard API and events

Table of Contents

• 1. Conformance
• 2. Introduction
• 3. Use Cases
• 4. Events
  • 4.1 Event types and details
    • 4.1.1 copy event
    • 4.1.2 cut event
    • 4.1.3 paste event
• 5. Processing model
• 6. Clipboard event interfaces
  • 6.1 Dictionary ClipboardEventInit Members
  • 6.2 Attributes
• 7. DataTransfer interface
  • 7.1 Attributes
  • 7.2 Methods
• 8. Integration with other scripts and events
• 9. Pasting HTML and multi-part data
  • 9.1 Security risks
  • 9.2 General security policies
  • 9.3 Cross-origin HTML paste sanitization algorithm
• 10. Other security and privacy considerations
• 11. Mandatory data types
• A. References
  • A.1 Normative references
  • A.2 Informative references

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

2. Introduction

This section is informative

This specification defines the common clipboard operations of cutting, copying and pasting, in such a way that they are exposed to Web Applications and can be adapted to provide advanced functionalities. Its goal is to provide for compatibility where possible with existing implementations.

3. Use Cases

This section is informative

There are many use cases for being able to change the default clipboard operations (cut/copy/paste). We have collected a few samples to demonstrate possible uses, although these may not all be supported by this specification.

Rich content editing

When copying text which contains hyperlinks or other structure, it is often useful to be able to reformat the content to preserve important information.

Graphics with built-in semantics

In order to make web applications which allow the manipulation of rich text, or of graphic content such as SVG, it is useful to provide a mechanism that allows for copying more than just the rendered content.

Mathematical information

With content such as mathematics, simply copying rendered text and pasting it into another application generally leads to most of the semantics being lost. MathML often needs to be transformed to be copied as plain text, for example to make sure "to the power of" is shown with the caret "^" sign in a formula plain-text input. The XML source could also be placed in the clipboard with the appropriate transformation occurring at paste time.

4. Events

5. Processing model

These are the general steps to follow when firing clipboard events.

1. Initialise a DataTransfer object [HTML5-DND] which the event.clipboardData property will refer to
2. Initialise an internal clear-was-called flag and set its value to false
3. Initialise an internal types-to-clear list which is initially empty
4. If the native OS clipboard supports a sequence number, let clipboard-entry be the sequence number of the current content

5. Determine the target node for the event as follows

   • In an editable context, the event object's target property must refer to the element that contains the start of the selection in document order, i.e. the end that is closer to the beginning of the document. If there is no selection or cursor, the target is the BODY element [HTML5].

   • In a non-editable document, the event's target must refer to a node focused for example by clicking, using the tab key, or by an interactive cursor, or to the BODY element [HTML5] if no other node has focus.

6. Prepare for firing the event per the event type specific instructions below:

   Paste event

   Set the associated DataTransfer object's drag data store mode flag to read-only

   For each part on the OS clipboard, carry out these steps:

   If the current clipboard part contains plain text:

   1. Ensure the text is in the encoding the scripting engine uses internally
   2. Add one entry for the text to the DataTransferItemList with drag data item kind set to string and drag data item type string set to text/plain

   If the current clipboard part represents file references:

   1. Determine MIME type of referenced files
   2. Add one entry per file reference to the DataTransferItemList with drag data item kind set to file and drag data item type string set to the corresponding MIME type

      What if the MIME type is unknown? Use application/octet-stream?

   If the current clipboard part contains HTML- or XHTML-formatted text, according to the operating system's convention for describing such clipboard formats

   If the implementation supports pasting HTML, the implementation must process the markup according to the following steps:

   1. Add one entry to the DataTransferItemList with drag data item kind set to Plain Unicode string, drag data item type string set to text/html or application/xhtml+xml accordingly. Let mainPartIndex be the index of this entry in the DataTransferItemList.
   2. Extract the markup from the clipboard and use the relevant parser to construct a DOM tree
   3. If the markup's source URL is known, resolve all relative URLs in HREF and SRC attributes using the source URL as base URL, and set the respective attributes to the resolved absolute URL
   4. If the markup's source URL is known, and the origin differs from the origin of the document the paste event will fire on, the user agent may apply a cross-origin HTML paste sanitization algorithm
   5. If the markup's origin is from a local application or is unknown, check whether there are references to local files and/or other parts of the OS clipboard's contents. If such references are found, references to sub-parts must be replaced by content-id references using the cid: URL scheme [RFC2392]. To do so, process each attribute referencing a local file or clipboard part according to the following steps:
      1. Let itemNumber be the number of items on the DataTransferItemList

      2. Choose the appropriate steps from this list:

         If the DataTransferItemList of the current DataTransfer object already contains an entry for the referenced file or clipboard part

         set itemNumber to the index of the existing entry

         Otherwise

         1. Add a new entry to the DataTransferItemList with index set to itemNumber, drag data item kind set to "file", and drag data item type string set to the MIME type of the file or clipboard part if known.
         2. Let the new entry's internal file name be the file name part of the HTML attribute contents
         3. Let the new entry's last modified date be the timestamp of the referenced file or 0 if the entry references a clipboard part

      3. Update the DOM attribute that referenced the local file or clipboard part to contain the string 'cid:' followed by itemNumber.
   6. Serialize the processed DOM and update the DataTransferItemList entry referenced by mainPartIndex with the resulting HTML code

   If the current clipboard part contains data in another supported binary or text-based format:

   1. Determine the MIME type of the data
   2. Add one entry to the DataTransferItemList with drag data item kind set to file, drag data item type string set to the corresponding MIME type

   Otherwise

   Do nothing

   Update the files property to match entries in the DataTransferItemList.

   Update the types property to match entries in the DataTransferItemList.

   Copy / cut event

   Set the associated DataTransfer object's drag data store mode flag to read/write

7. Fire the event [DOM-LEVEL-2-EVENTS]. Implementation requirements for access to data during event dispatch is defined in [HTML5-DND]. Some additional clipboard event-specific processing rules are given below:

   If script calls clearData() or items.clear() and the DataTransfer object's drag data store mode flag is read/write

   set the clear-was-called flag to true. If an argument is given, add the argument to the types-to-clear list.

   If script calls setData() or modifies items and the clear-was-called flag is true

   If the types-to-clear list is empty

   set the clear-was-called flag to false

   else, if setData()'s type argument or the new item's drag data item type string is found in the types-to-clear list

   remove it from the list. If the list is now empty, set the clear-was-called flag to false

   If script calls getData() or accesses items in the DataTransferItemList and clipboard-entry is set

   check that the clipboard data's sequence number matches clipboard-entry. If the clipboard no longer contains the same entry, set the DataTransferItemList object's drag data store mode to the disabled mode

   Warning: A malicious script listening to a paste event may set up a never-ending loop in order to read what the user places on the clipboard in the future. On platforms where a clipboard sequence number is not available, other limitations should be implemented.

8. Process the default action or the data from the script per the following instructions:

   Paste event

   If the default action was prevented

   Do nothing, terminate this algorithm.

   Otherwise

   If the cursor or selection is in an editable context, insert the data from the clipboard and queue tasks to fire any events that should fire due to the modification, see interaction with other events for details

   Copy / cut event

   If the default action was prevented

   Update the clipboard contents with the data from the script, as given by the DataTransferItemList. Process each part as follows:

   If the list of items is empty and the clear-was-called flag is true

   If the types-to-clear list is empty

   Clear the clipboard

   else

   Remove given type from the clipboard in an operating system and implementation-specific way

   If data type is text/plain

   1. Ensure encoding is correct per OS and locale conventions
   2. Normalize line endings according to platform conventions
   3. Place text on clipboard

   Otherwise

   Place part on clipboard with the appropriate OS clipboard format description

   Otherwise

   If there is a selection

   Place contents of selection on the clipboard

   If the event was a cut event and the context is editable, remove selection contents and collapse the selection

   Otherwise

   Do nothing, terminate this algorithm

   Calling setData() without calling preventDefault() has no effect, even if there is no selection - the default action is to do nothing.

6. Clipboard event interfaces

The ClipboardEvent interface extends the Event interface [DOM-LEVEL-2-EVENTS].

A synthetic paste event must not give a script access to data on the real system clipboard. Synthetic cut and copy events must not modify data on the system clipboard.

The default action of a synthetic paste event with text/plain data when dispatched in an editable context, is to insert the data.

dictionary ClipboardEventInit : EventInit {
    attribute DOMString data;
    attribute DOMString dataType;
};

[Constructor(DOMString type, optional ClipboardEventInit eventInitDict)]
interface ClipboardEvent : Event {
    readonly attribute DataTransfer clipboardData;
};

The interface can be used to construct event objects per [DOM-CORE-DRAFT]. An example is given below:

var pasteEvent = new ClipboardEvent('paste', { bubbles: true, cancelable: true, dataType: 'text/plain', data: 'My string' } );
document.dispatchEvent(pasteEvent);

7. DataTransfer interface

This section is informative, and describes only the parts of the DataTransfer interface that are relevant for clipboard events. The normative specification for the DataTransfer interface is found in [HTML5-DND]'s DataTransfer interface section.

interface clipboardData : DataTransfer {
             attribute DataTransferItemList items;
             attribute DOMStringList        types;
    readonly attribute FileList             files;
    DOMString getData (DOMString type);
    boolean   setData (DOMString type, DOMString data);
    boolean   clearData (optional DOMString type);
};

8. Integration with other scripts and events

Integration with rich text editing APIs

If an implementation supports the document.execCommand method and allows calling it with the commands "cut", "copy" and "paste", the implementation must fire the corresponding events. The event is syncronous and may prevent the execCommand() call from having its normal effect.

Interaction with other events

If the clipboard operation is triggered by keyboard input, the implementation must fire the corresponding event as the default action of the keydown event that initiates the clipboard operation. For example, if the user presses Ctrl-C to copy, dispatching a copy event must be the default action of the C key's keydown event. The event is asynchronous but must be dispatched before keyup events for the relevant keys.

The default action of the cut and paste events may cause the implementation to dispatch other supported events, such as textInput, input, change, validation events, DOMCharacterDataModified and DOMNodeRemoved / DOMNodeInserted. Any such events are queued up to fire after processing of the cut/paste event is finished.

The implementation must not dispatch other input-related events like textInput, input, change, and validation events in response to the copy operation.

Event listeners that modify selection or focus

If the event listener modifies the selection or focus, the clipboard action must be completed on the modified selection.

9. Pasting HTML and multi-part data

10. Other security and privacy considerations

Enabling authors to change what is copied by a user, or to make an automated copy of something that was never selected and allowing unrestricted calls to paste information can raise various security and privacy concerns.

An example scenario of a problem is where a user selects a link and copies it, but a different link is copied to the clipboard. The effect of this can range from an unexpected result on pasting to an attempted "phishing" attack.

Privacy concerns

Untrusted scripts should not get uncontrolled access to a user's clipboard data. This specification assumes that granting access to the current clipboard data when a user explicitly initiates a paste operation from the UA's trusted chrome is acceptable. However, implementors must proceed carefully, and as a minimum implement the precautions below:

• Objects implementing the DataTransfer interface to return clipboard data must not be available outside the ClipboardEvent event handler.
• If a script stores a reference to an object implementing the DataTransfer interface to use from outside the ClipboardEvent event handler, all methods must be no-ops when called outside the expected context.
• Implementations must not let scripts create synthetic clipboard events to get access to real clipboard data.

Implementations may choose to further limit the functionality provided by the DataTransfer interface. For example, an implementation may allow the user to disable this API, or configure which web sites should be granted access to it.

Nuisance considerations

Scripts may use the DataTransfer API to annoy and confuse users by altering the data on the system clipboard from copy and cut events. This specification does not attempt to prevent such nuisances, though implementations may add additional restrictions.

Implementations must handle scripts that try to place excessive amounts of data on the clipboard gracefully.

11. Mandatory data types

The implementation must recognise the native OS clipboard format description for the following data types, to be able to populate the DataTransferItemList with the correct description for paste events, and set the correct data format on the OS clipboard in response to copy and cut events.

• text/plain
• text/uri-list
• text/csv
• text/css
• text/html
• application/xhtml+xml
• image/png
• image/jpg
• image/gif
• image/svg+xml
• application/xml, text/xml
• application/javascript
• application/json

What about audio and video types? BMP? RTF? RTF was requested due to embedded images possibility (but this spec allows access to local images referenced in HTML fragments by design..).

Some standard Windows formats we don't handle

DataFormats.CF_RTFTEXT 

DataFormats.CF_WAVE 
DataFormats.CF_RIFF 

DataFormats.CF_BITMAP 
DataFormats.CF_DIB 
DataFormats.CF_DIF 
DataFormats.CF_METAFILEPICT 
DataFormats.CF_PALETTE 
DataFormats.CF_TIFF