Package com.vaadin.flow.component.trigger.internal

Class WriteToClipboardAction

java.lang.Object
com.vaadin.flow.component.trigger.internal.Action
com.vaadin.flow.component.trigger.internal.PromiseAction<String>
com.vaadin.flow.component.trigger.internal.WriteToClipboardAction
All Implemented Interfaces:
Serializable
public class WriteToClipboardAction extends PromiseAction<String>
Writes a ClipboardItem to the user's clipboard via navigator.clipboard.write. Supports up to three concurrent MIME types in one item: text/plain, text/html and image/png (typically produced by an ImageBlobInput). Any combination is allowed; at least one slot must be set.

The Clipboard API requires the write call to happen inside a short-lived user gesture (click, key press, ...). Bind this action to a trigger that fires during such a gesture.

Construction comes in three flavours, each available as fire-and-forget and as a with-outcome variant taking onCopied/onError consumers:

  • Text/HTML — the typical case for copying a string
  • Image — the typical case for copying an image
  • Multi-format via ClipboardContent — combine any of the three slots in one item
onCopied receives the exact string that was copied — the text/plain value if present, otherwise the text/html value, otherwise null (image-only case) — useful when the input was a PropertyInput whose value is only known on the client. onError receives a PromiseAction.Error record with the browser's error name and message.

For internal use only. May be renamed or removed in a future release.

See Also:

  • Constructor Details

    • WriteToClipboardAction

      public WriteToClipboardAction(@Nullable Action.Input<String> textInput, @Nullable Action.Input<String> htmlInput)
      Creates a fire-and-forget text/HTML clipboard-copy action.
      Parameters:
      textInput - input producing the text/plain payload, or null to omit
      htmlInput - input producing the text/html payload, or null to omit
      Throws:
      IllegalArgumentException - if both inputs are null

    • WriteToClipboardAction

      public WriteToClipboardAction(@Nullable Action.Input<String> textInput, @Nullable Action.Input<String> htmlInput, SerializableConsumer<@Nullable String> onCopied, SerializableConsumer<PromiseAction.Error> onError)
      Creates a text/HTML clipboard-copy action whose outcome is reported back to the server.
      Parameters:
      textInput - input producing the text/plain payload, or null to omit
      htmlInput - input producing the text/html payload, or null to omit
      onCopied - invoked on the UI thread with the string that was copied after the client reports the write resolved (text/plain if present, otherwise text/html), or null if the JS resolved with undefined; not null
      onError - invoked on the UI thread with the browser's error after the client reports the write rejected, not null
      Throws:
      IllegalArgumentException - if both inputs are null

    • WriteToClipboardAction

      public WriteToClipboardAction(Action.Input<?> imageInput)
      Creates a fire-and-forget image clipboard-copy action.
      Parameters:
      imageInput - input producing the source <img> for the image/png payload (typically an ImageBlobInput), not null

    • WriteToClipboardAction

      public WriteToClipboardAction(Action.Input<?> imageInput, SerializableConsumer<@Nullable String> onCopied, SerializableConsumer<PromiseAction.Error> onError)
      Creates an image clipboard-copy action whose outcome is reported back to the server. onCopied receives null — the image-only write has no meaningful string value.
      Parameters:
      imageInput - input producing the source <img> for the image/png payload (typically an ImageBlobInput), not null
      onCopied - invoked on the UI thread with null after the client reports the write resolved, not null
      onError - invoked on the UI thread with the browser's error after the client reports the write rejected, not null

    • WriteToClipboardAction

      public WriteToClipboardAction(ClipboardContent content)
      Creates a fire-and-forget multi-format clipboard-copy action from a ClipboardContent describing the payload. Use Clipboard.onClick(...).write(content) as the typical entry point.
      Parameters:
      content - the clipboard payload, not null; must have at least one slot set
      Throws:
      IllegalArgumentException - if content has no slots set

    • WriteToClipboardAction

      public WriteToClipboardAction(ClipboardContent content, SerializableConsumer<@Nullable String> onCopied, SerializableConsumer<PromiseAction.Error> onError)
      Creates a multi-format clipboard-copy action from a ClipboardContent whose outcome is reported back to the server.
      Parameters:
      content - the clipboard payload, not null; must have at least one slot set
      onCopied - invoked on the UI thread with the string that was copied after the client reports the write resolved (text/plain if present, otherwise text/html, otherwise null in the image-only case), or null if the JS resolved with undefined; not null
      onError - invoked on the UI thread with the browser's error after the client reports the write rejected, not null
      Throws:
      IllegalArgumentException - if content has no slots set

  • Method Details

    • toPromiseJs

      protected JsFunction toPromiseJs(Trigger trigger)
      Description copied from class: PromiseAction
      Subclasses return a JsFunction that, when invoked with the trigger's event, evaluates to a Promise. The value the promise resolves with is decoded to T on the server and handed to onSuccess. To deliver a typed value, subclasses can wrap their API call in an IIFE inside the function body — for example, copying a string and resolving with it: 
      
 return JsFunction.of(
         "return ((v) => navigator.clipboard.writeText(v).then(() => v))($0(event))",
         textInput.toJs(trigger)).withArguments("event");
      Specified by:
      toPromiseJs in class PromiseAction<String>
      Parameters:
      trigger - the surrounding trigger this render is for, not null
      Returns:
      the promise-yielding JS function, not null