操作功能表
適用於桌面端的 Compose Multiplatform 提供對文字操作功能表的開箱即用支援,並允許你透過新增更多項目、設定佈景主題以及自訂文字,方便地客製化任何操作功能表。
本指南中的範例皆為可執行的桌面應用程式。若要嘗試其中一個:
- 使用 Kotlin Multiplatform IDE 外掛程式 或線上精靈建立 Compose Multiplatform 專案。
- 開啟桌面端入口點檔案。例如:
desktopApp/src/main/kotlin/com/example/my_desktop_app/main.kt。 - 將其內容取代為所提供的範例。
自訂區域中的操作功能表
你可以為應用程式的任何任意區域建立操作功能表。使用 ContextMenuArea 來定義一個容器,當在該容器中按下滑鼠右鍵時,就會觸發操作功能表的顯示:
ContextMenuArea(items = { listOf( ContextMenuItem( {...}
import androidx.compose.foundation.ContextMenuArea
import androidx.compose.foundation.ContextMenuItem
import androidx.compose.foundation.background
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.layout.width
import androidx.compose.ui.Modifier
import androidx.compose.ui.graphics.Color
import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.singleWindowApplication
fun main() = singleWindowApplication(title = "Context menu") {
ContextMenuArea(items = {
listOf(
ContextMenuItem("User-defined action") {
// 自訂操作
},
ContextMenuItem("Another user-defined action") {
// 另一個自訂操作
}
)
}) {
// 可使用操作功能表的藍色方塊
Box(modifier = Modifier.background(Color.Blue).height(100.dp).width(100.dp))
}
}
設定佈景主題
你可以自訂操作功能表顏色,以建立符合系統設定的 UI 回應性,並避免在應用程式之間切換時出現劇烈的對比變化。針對預設的淺色與深色佈景主題,提供了兩種內建實作:LightDefaultContextMenuRepresentation 與 DarkDefaultContextMenuRepresentation。 它們不會自動套用到操作功能表顏色,因此你需要透過 LocalContextMenuRepresentation 設定合適的佈景主題:
MaterialTheme( colors = if (isSystemInDarkTheme()) darkColors() else {...}
import androidx.compose.foundation.DarkDefaultContextMenuRepresentation
import androidx.compose.foundation.LightDefaultContextMenuRepresentation
import androidx.compose.foundation.LocalContextMenuRepresentation
import androidx.compose.foundation.isSystemInDarkTheme
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material.MaterialTheme
import androidx.compose.material.Surface
import androidx.compose.material.TextField
import androidx.compose.material.darkColors
import androidx.compose.material.lightColors
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.Modifier
import androidx.compose.ui.window.singleWindowApplication
fun main() = singleWindowApplication(title = "Dark theme") {
MaterialTheme(
colors = if (isSystemInDarkTheme()) darkColors() else lightColors()
) {
val contextMenuRepresentation = if (isSystemInDarkTheme()) {
DarkDefaultContextMenuRepresentation
} else {
LightDefaultContextMenuRepresentation
}
CompositionLocalProvider(LocalContextMenuRepresentation provides contextMenuRepresentation) {
Surface(Modifier.fillMaxSize()) {
Box {
var value by remember { mutableStateOf("") }
TextField(value, { value = it })
}
}
}
}
}
在地化選單項目
預設情況下,操作功能表將以系統設定的慣用語言顯示:

如果你想使用特定語言,請在執行應用程式之前明確將其指定為預設語言:
java.util.Locale.setDefault(java.util.Locale("en"))文字操作功能表
預設文字操作功能表
適用於桌面端的 Compose Multiplatform 為 TextField 與可選取的 Text 提供了內建的操作功能表。
文字欄位的預設操作功能表包含以下操作(取決於游標位置與選取範圍):複製、剪下、貼上以及全選。 此標準操作功能表預設在 Material 的 TextField(androidx.compose.material.TextField 或 androidx.compose.material3.TextField)與 Foundation 的 BasicTextField(androidx.compose.foundation.text.BasicTextField)中提供。
TextField( value = text.value, onValueChange = {...}
import androidx.compose.material.Text
import androidx.compose.material.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.window.singleWindowApplication
fun main() = singleWindowApplication(title = "Context menu") {
val text = remember { mutableStateOf("Hello!") }
TextField(
value = text.value,
onValueChange = { text.value = it },
label = { Text(text = "Input") }
)
}
請參閱 API 參考以了解詳細資訊。
簡易文字元素的預設操作功能表僅包含複製操作。 若要為 Text 組件啟用操作功能表,請將文字包裹在 SelectionContainer 中使其可被選取:
SelectionContainer { Text( {...}
import androidx.compose.foundation.text.selection.SelectionContainer
import androidx.compose.material.Text
import androidx.compose.ui.window.singleWindowApplication
fun main() = singleWindowApplication(title = "Context menu") {
SelectionContainer {
Text("Hello World!")
}
}
新增自訂項目
若要為 TextField 與 Text 組件新增自訂操作功能表操作,請透過 ContextMenuItem 指定新項目,並透過 ContextMenuDataProvider 將它們新增至操作功能表項目的階層中。例如,以下程式碼範例展示如何為文字欄位與簡單的可選取文字元素的預設操作功能表新增兩個自訂操作:
ContextMenuDataProvider( items = { listOf( ContextMenuItem( {...}
import androidx.compose.foundation.ContextMenuDataProvider
import androidx.compose.foundation.ContextMenuItem
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.Spacer
import androidx.compose.foundation.layout.height
import androidx.compose.foundation.text.selection.SelectionContainer
import androidx.compose.material.Text
import androidx.compose.material.TextField
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import androidx.compose.ui.window.singleWindowApplication
fun main() = singleWindowApplication(title = "Context menu") {
val text = remember { mutableStateOf("Hello!") }
Column {
ContextMenuDataProvider(
items = {
listOf(
ContextMenuItem("User-defined action") {
// 自訂操作
},
ContextMenuItem("Another user-defined action") {
// 另一個自訂操作
}
)
}
) {
TextField(
value = text.value,
onValueChange = { text.value = it },
label = { Text(text = "Input") }
)
Spacer(Modifier.height(16.dp))
SelectionContainer {
Text("Hello World!")
}
}
}
}
覆寫預設文字操作功能表
若要覆寫文字欄位與可選取文字元素的預設操作功能表,請覆寫 TextContextMenu 介面。 在以下程式碼範例中,我們重複使用原始的 TextContextMenu,但在清單底部新增了一個額外項目。 該新項目會根據所選取的文字自動調整:
CompositionLocalProvider( LocalTextContextMenu provides object : TextContextMenu { {...}
import androidx.compose.foundation.ContextMenuDataProvider
import androidx.compose.foundation.ContextMenuItem
import androidx.compose.foundation.ContextMenuState
import androidx.compose.foundation.ExperimentalFoundationApi
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.text.LocalTextContextMenu
import androidx.compose.foundation.text.TextContextMenu
import androidx.compose.foundation.text.selection.SelectionContainer
import androidx.compose.material.Text
import androidx.compose.material.TextField
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.platform.LocalUriHandler
import androidx.compose.ui.text.AnnotatedString
import androidx.compose.ui.window.singleWindowApplication
import java.net.URLEncoder
import java.nio.charset.Charset
fun main() = singleWindowApplication(title = "Context menu") {
CustomTextMenuProvider {
Column {
SelectionContainer {
Text("Hello, Compose!")
}
var text by remember { mutableStateOf("") }
TextField(text, { text = it })
}
}
}
@OptIn(ExperimentalFoundationApi::class)
@Composable
fun CustomTextMenuProvider(content: @Composable () -> Unit) {
val textMenu = LocalTextContextMenu.current
val uriHandler = LocalUriHandler.current
CompositionLocalProvider(
LocalTextContextMenu provides object : TextContextMenu {
@Composable
override fun Area(
textManager: TextContextMenu.TextManager,
state: ContextMenuState,
content: @Composable () -> Unit
) {
// 重複使用原始的 TextContextMenu 並新增一個新項目
ContextMenuDataProvider({
val shortText = textManager.selectedText.crop()
if (shortText.isNotEmpty()) {
val encoded = URLEncoder.encode(shortText, Charset.defaultCharset())
listOf(ContextMenuItem("Search $shortText") {
uriHandler.openUri("https://google.com/search?q=$encoded")
})
} else {
emptyList()
}
}) {
textMenu.Area(textManager, state, content = content)
}
}
},
content = content
)
}
private fun AnnotatedString.crop() = if (length <= 5) toString() else "${take(5)}..."
Swing 互通性
如果你正在將 Compose 程式碼嵌入到現有的 Swing 應用程式中,且需要操作功能表的外觀與行為與應用程式的其他部分相符,可以使用 JPopupTextMenu 類別。在此類別中,LocalTextContextMenu 使用 Swing 的 JPopupMenu 作為 Compose 組件中的操作功能表。
fun JPopupTextMenuProvider(owner: Component, content: @Composable () -> Unit) {...}
import androidx.compose.foundation.ExperimentalFoundationApi
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.text.JPopupTextMenu
import androidx.compose.foundation.text.LocalTextContextMenu
import androidx.compose.foundation.text.selection.SelectionContainer
import androidx.compose.material.Text
import androidx.compose.material.TextField
import androidx.compose.runtime.Composable
import androidx.compose.runtime.CompositionLocalProvider
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.runtime.setValue
import androidx.compose.ui.awt.ComposePanel
import androidx.compose.ui.platform.LocalLocalization
import java.awt.Color
import java.awt.Component
import java.awt.Dimension
import java.awt.Graphics
import java.awt.event.KeyEvent
import java.awt.event.KeyEvent.CTRL_DOWN_MASK
import java.awt.event.KeyEvent.META_DOWN_MASK
import javax.swing.Icon
import javax.swing.JFrame
import javax.swing.JMenuItem
import javax.swing.JPopupMenu
import javax.swing.KeyStroke.getKeyStroke
import javax.swing.SwingUtilities
import org.jetbrains.skiko.hostOs
fun main() = SwingUtilities.invokeLater {
val panel = ComposePanel()
panel.setContent {
JPopupTextMenuProvider(panel) {
Column {
SelectionContainer {
Text("Hello, World!")
}
var text by remember { mutableStateOf("") }
TextField(text, { text = it })
}
}
}
val window = JFrame()
window.contentPane.add(panel)
window.size = Dimension(800, 600)
window.isVisible = true
window.title = "Swing interop"
}
@OptIn(ExperimentalFoundationApi::class)
@Composable
fun JPopupTextMenuProvider(owner: Component, content: @Composable () -> Unit) {
val localization = LocalLocalization.current
CompositionLocalProvider(
LocalTextContextMenu provides JPopupTextMenu(owner) { textManager, items ->
JPopupMenu().apply {
textManager.cut?.also {
add(
swingItem(localization.cut, Color.RED, KeyEvent.VK_X, it)
)
}
textManager.copy?.also {
add(
swingItem(localization.copy, Color.GREEN, KeyEvent.VK_C, it)
)
}
textManager.paste?.also {
add(
swingItem(localization.paste, Color.BLUE, KeyEvent.VK_V, it)
)
}
textManager.selectAll?.also {
add(JPopupMenu.Separator())
add(
swingItem(localization.selectAll, Color.BLACK, KeyEvent.VK_A, it)
)
}
// 新增可在應用程式其他部分透過 ContextMenuDataProvider 定義的項目
for (item in items) {
add(
JMenuItem(item.label).apply {
addActionListener { item.onClick() }
}
)
}
}
},
content = content
)
}
private fun swingItem(
label: String,
color: Color,
key: Int,
onClick: () -> Unit
) = JMenuItem(label).apply {
icon = circleIcon(color)
accelerator = getKeyStroke(key, if (hostOs.isMacOS) META_DOWN_MASK else CTRL_DOWN_MASK)
addActionListener { onClick() }
}
private fun circleIcon(color: Color) = object : Icon {
override fun paintIcon(c: Component?, g: Graphics, x: Int, y: Int) {
g.create().apply {
this.color = color
translate(8, 2)
fillOval(0, 0, 16, 16)
}
}
override fun getIconWidth() = 16
override fun getIconHeight() = 16
}
後續步驟
探索關於其他桌面端組件的教學。
