在 Compose Multiplatform 中分享內容
在 Compose Multiplatform 應用程式中,你可以與系統或其他應用程式分享文字、URL、檔案以及其他內容。
分享功能因平台而異:
- Android 與 iOS 提供原生系統分享對話方塊。
- 桌面應用程式通常沒有通用的系統分享對話方塊。常見的替代方案包括使用剪貼簿、透過預設應用程式開啟檔案或 URL,或是呼叫平台專屬的 API。
- Web 應用程式可以使用 Web Share API(取決於瀏覽器支援度)。
若要在 Compose Multiplatform 應用程式中分享內容,可以使用社群程式庫或直接呼叫平台專屬的 API。 若要在任何平台上透過預設關聯的應用程式開啟連結,請使用共用 UriHandler API。
社群程式庫
社群程式庫封裝了原生分享 API,並提供可從 commonMain 原始碼集呼叫的共用 API。
KMP Sharing 為 Android 和 iOS 上的系統分享對話方塊提供了共用 API。 它支援分享文字或 URL,並可選擇附加檔案 URI:
val share = rememberShare()
val sharingOptions = SharingOptions(androidDialogTitle = "Share with")
Button(onClick = { share("https://kotlinlang.org", sharingOptions) }) {
Text("Share link")
}
Button(onClick = { share("Kotlin programming language", sharingOptions) }) {
Text("Share text")
}FileKit 透過原生對話方塊提供跨平台的檔案選取、儲存和檔案操作。 你可以將這些程式庫搭配使用,例如透過 FileKit 選取檔案,並透過 KMP Sharing 分享它們:
val share = rememberShare()
val sharingOptions = SharingOptions(androidDialogTitle = "Share with")
val photosPicker = rememberFilePickerLauncher(
type = FileKitType.Image,
mode = FileKitMode.Multiple(),
onError = {},
onResult = { photos ->
photos?.takeIf { it.isNotEmpty() }?.let { selectedPhotos ->
share(selectedPhotos.map(PlatformFile::sharingUri), sharingOptions)
}
},
)
Button(onClick = photosPicker::launch) {
Text("Pick and share photos")
}KMP Sharing 期望檔案值為 URI。如果你從 FileKit 取得的是本機路徑,請在分享前將 PlatformFile 路徑轉換為 URI: 在 commonMain 的頂層定義此幫助程式:
private fun PlatformFile.sharingUri(): String = path.let { filePath ->
when {
filePath.startsWith("content://") || filePath.startsWith("file://") -> filePath
else -> "file://$filePath"
}
}在 klibs.io 上瀏覽其他程式庫選項。 對於程式庫未涵蓋的使用案例,你可以使用平台專屬的 API來實作分享。
平台專屬的分享 API
你可以直接使用各個平台上的原生 API 來實作分享,例如控制內容類型、分享選項或分享流程。
Android
在 androidMain 原始碼集中,使用 ACTION_SEND intent 來分享文字、URL 或檔案。 對於文字或 URL,請使用 Intent.EXTRA_TEXT 傳遞內容:
val intent = Intent(Intent.ACTION_SEND).apply {
type = "text/plain"
putExtra(Intent.EXTRA_TEXT, "https://kotlinlang.org")
}
context.startActivity(Intent.createChooser(intent, "Share with"))若要分享檔案,請使用 content:// URI 並授予暫時的讀取權限:
val intent = Intent(Intent.ACTION_SEND).apply {
type = "image/jpeg"
putExtra(Intent.EXTRA_STREAM, contentUri)
addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
}
context.startActivity(Intent.createChooser(intent, "Share with"))對於應用程式私有檔案,請透過 FileProvider、MediaStore 或其他內容提供者公開該檔案。 對於多個檔案,請將 ACTION_SEND_MULTIPLE 與 Intent.EXTRA_STREAM 搭配使用,並傳入 ArrayList<Uri>:
val intent = Intent(Intent.ACTION_SEND_MULTIPLE).apply {
type = "image/jpeg"
putParcelableArrayListExtra(Intent.EXTRA_STREAM, ArrayList(contentUris))
addFlags(Intent.FLAG_GRANT_READ_URI_PERMISSION)
}
context.startActivity(Intent.createChooser(intent, "Share with"))若要了解更多資訊,請參閱 Android Developers 頁面在應用程式之間分享資料。
iOS
對於以 UIKit 為基礎的 UI,請在原生的 iosApp 專案中顯示 UIActivityViewController:
let items: [Any] = [URL(string: "https://kotlinlang.org")!]
let controller = UIActivityViewController(
activityItems: items,
applicationActivities: nil
)
viewController.present(controller, animated: true)在原生應用程式的 SwiftUI 程式碼中,針對 Transferable 協定所支援的值,你可以使用 ShareLink。
對於自訂或大型檔案,請實作 Transferable 表示形式,或搭配平台橋接器使用 UIActivityViewController。
若要了解更多資訊,請參閱 Apple Developer 頁面 Collaborating and sharing copies of your data。
Desktop
桌面應用程式沒有通用的分享對話方塊。常見的做法包括:
- 將內容複製到剪貼簿。
- 使用預設應用程式開啟檔案。
- 使用平台專屬的 API,例如 macOS 上的
NSSharingServicePicker類別及其可用分享服務清單。
例如,當存在與檔案類型關聯的應用程式時,你可以使用 java.awt.Desktop 在該應用程式中開啟檔案:
val file = java.io.File("/path/to/document.pdf")
if (java.awt.Desktop.isDesktopSupported()) {
val desktop = java.awt.Desktop.getDesktop()
if (desktop.isSupported(java.awt.Desktop.Action.OPEN)) {
desktop.open(file)
}
}Web
在瀏覽器與作業系統支援的情況下,Web 應用程式可透過 JavaScript 互通性使用 Web Share API。 它通常需要 HTTPS 以及使用者手勢操作(例如點擊按鈕)。
在呼叫 API 之前請先檢查是否支援,並提供備援方案,例如將內容複製到剪貼簿:
if (navigator.share) {
await navigator.share({
title: "Kotlin",
text: "Kotlin programming language",
url: "https://kotlinlang.org"
})
} else {
await navigator.clipboard.writeText("https://kotlinlang.org")
}對於檔案,請使用 navigator.canShare() 檢查支援情況:
if (navigator.canShare && navigator.canShare({ files })) {
await navigator.share({
files,
title: "Photos"
})
}檔案分享的支援程度取決於瀏覽器、平台、檔案類型與檔案大小。 如果檔案無法分享,常見的備援方案包括提供檔案下載,或是改為複製該內容的連結。
相關功能
開啟連結與深層連結(Deep Link)。 Compose Multiplatform 提供了
UriHandler作為共用 API,用於請求平台開啟 URI:https://連結、自訂應用程式結構定義(custom application schemes)、mailto:、geo:等等。 透過LocalUriHandler.current取得處理常式,並在事件處理常式中呼叫openUri():kotlinval uriHandler = LocalUriHandler.current Button(onClick = { uriHandler.openUri("mailto:user@example.com?subject=Hello") }) { Text("Send email") }拖放。 Compose Multiplatform 提供了共用 API,可透過將內容拖曳至目的地來進行分享。請參閱拖放。
剪貼簿。 Compose Multiplatform 支援 Jetpack Compose 的 Clipboard 介面。 然而,目前從通用程式碼與剪貼簿互動仍受限制。請在 CMP-7624 追蹤進度。
