A protocol that describes how a type interacts with transport APIs
such as drag and drop or copy and paste.
To conform to the ``Transferable`` protocol,
implement the ``transferRepresentation`` property.
For example, an image editing app's layer type might
conform to `Transferable` to let people drag and drop image layers
to reorder them within a document.
struct ImageDocumentLayer {
init(data: Data) { }
func data() -> Data { Data() }
func pngData() -> Data { Data() }
}
The following shows how you can extend `ImageDocumentLayer` to
conform to `Transferable`:
extension ImageDocumentLayer: Transferable {
static var transferRepresentation: some TransferRepresentation {
DataRepresentation(contentType: .layer) { layer in
layer.data()
} importing: { data in
ImageDocumentLayer(data: data)
}
DataRepresentation(exportedContentType: .png) { layer in
layer.pngData()
}
}
}
When people drag and drop a layer within the app or onto another app
that recognizes the custom `layer` content type,
the app uses the first representation.
When people drag and drop the layer onto a different image editor,
it's likely that the editor recognizes the PNG file type.
The second transfer representation adds support for PNG files.
The following declares the custom `layer` uniform type identifier:
extension UTType {
static let layer = UTType(exportedAs: "com.example.layer")
}
> Important: If your app declares custom uniform type identifiers,
include corresponding entries in the app's `Info.plist`.
For more information, see <doc://com.apple.documentation/documentation/uniformtypeidentifiers/defining_file_and_data_types_for_your_app>.
If one of your existing types conforms to <doc://com.apple.documentation/documentation/Swift/Codable>,
`Transferable` automatically handles conversion to and from `Data`.
The following declares a simple `Note` structure that's `Codable`
and an extension to make it `Transferable`:
struct Note: Codable {
let title: String
let body: String
}
extension Note: Transferable {
static var transferRepresentation: some TransferRepresentation {
CodableRepresentation(contentType: .note)
}
}
To ensure compatibility with other apps that don't know about
the custom `note` type identifier,
the following adds an additional transfer representation
that converts the note to text.
extension Note: Transferable {
static var transferRepresentation: some TransferRepresentation {
CodableRepresentation(contentType: .note)
ProxyRepresentation(\.title)
}
}
The order of the representations in the transfer representation matters;
place the representation that most accurately represents your type first,
followed by a sequence of more compatible
but less preferable representations.
Using the type's `Transferable` conformance implementation,
exports a value by writing it to disk and removes when not needed.
This converts a ``Transferable`` item into a temporary file, and
removes it after `fileHandler` closure returns. The default implementation
of this function is available to all types that conform
to `Transferable` protocol.
- Parameters:
- contentType: A content type of the requested file.
If the content type is not provided, CoreTransferable creates
a file from the first `TransferRepresentation` that supports export.
- fileHandler: A closure that accepts a file URL as a parameter.
The file is written to a temporary destination and removed
after the closure returns.
get · iOS 18.2+
suggestedFilename
Swift declaration
var suggestedFilename: String? { get }
A suggested filename of a `Transferable` value.
A filename for given item, or `nil` if none specified.
A name can be specified using ``TransferRepresentation.suggestedFileName(_:)``.
The default implementation of this property is available to all types that conform
to ``Transferable`` protocol.
Content types supported by a given value's `Transferable` conformance
for export (like drag or copy).
Returns a list of all content types available for export in the type's
``Transferable`` conformance, except for those
that are not supported by this specific value. For example, if an ``exportingCondition`` for some
representation evaluates to `false`, this representation isn't included.
The default implementation of this function is available to all types that conform
to `Transferable` protocol.
- Parameters:
- visibility: Desired visibility level for the returned content types. Defaults to `.all`.
method · iOS 18.2+
importedContentTypes
Swift declaration
func importedContentTypes() -> [UTType]
Content types supported by a given value's `Transferable` conformance
for import (like drop or paste).
Returns a list of all content types available for import.
The default implementation of this function is available
to all types that conform to ``Transferable`` protocol.
Using the type's `Transferable` conformance implementation,
exports a value by writing it to a provided destination directory.
If the ``Transferable`` is not backed by a file,
this will write the data to specified destination.
This function uses the first representation provided for a given type
in `static var transferRepresentation` requirement of the `Transferable` protocol
or in the `body` of a custom `TransferRepresentation`.
The default implementation of this function is available to all types that conform
to `Transferable` protocol.
- Parameters:
- destinationDirectory: A directory to write the file to.
- contentType: A content type of the requested file.
If `nil`, the first transfer representation is be used.
- Returns: A URL of the created file. The file is owned by the application,
and it is responsible for removing it when the file is not needed anymore.
method · iOS 18.2+
exported
Swift declaration
func exported(as contentType: UTType?) async throws -> Data
Using the type's `Transferable` conformance implementation,
exports a value as binary data.
If the ``Transferable`` is backed by a file `URL`, this might cause loading the
entire file contents into memory. This function uses
the first representation that conforms to the given content type
in `static var transferRepresentation` requirement of the `Transferable` protocol
or in the `var body` property of a custom `TransferRepresentation`.
The default implementation of this function is available to all
types that conform to `Transferable` protocol.
- Parameters:
- contentType: A content type of the returned data.
If no content type is provided, CoreTransferable generates data using
the first `TransferRepresentation` in the `Transferable` conformance that supports export.
Skipped declarations
4 declarations were excluded from these bindings. Each reason comes from the generator or the iOS SDK compiler.
Transferable.exportedContentTypes(visibility:)
Static protocol requirements cannot be called through an instance.
Transferable.importedContentTypes()
Static protocol requirements cannot be called through an instance.
