Skip to content

上下文菜单 ​

适用于桌面的 Compose Multiplatform 开箱即用地支持文本上下文菜单,并允许您通过添加更多项、设置主题以及自定义文本来便捷地定制任意上下文菜单。

本指南中的示例均为可运行的桌面应用。若要尝试运行:

  1. 使用 Kotlin Multiplatform IDE 插件 或 在线向导 创建一个 Compose Multiplatform 项目。
  2. 打开桌面端入口点文件。例如 desktopApp/src/main/kotlin/com/example/my_desktop_app/main.kt。
  3. 将其内容替换为所提供的示例。

自定义区域中的上下文菜单 ​

您可以为应用程序的任意区域创建上下文菜单。使用 ContextMenuArea 可以定义一个容器,在该容器内点击鼠标右键将触发上下文菜单的显示:

ContextMenuArea(items = { listOf( ContextMenuItem( {...}
kotlin
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))
    }
}
Context menu: ContextMenuArea

设置主题 ​

您可以自定义上下文菜单的颜色,以打造与系统设置相契合的自适应 UI,并避免在应用程序之间切换时出现强烈的对比度反差。针对默认的浅色和深色主题,内置了两种实现: LightDefaultContextMenuRepresentation 和 DarkDefaultContextMenuRepresentation。 它们不会自动应用到上下文菜单颜色上,因此您需要通过 LocalContextMenuRepresentation 来设置合适的主题:

MaterialTheme( colors = if (isSystemInDarkTheme()) darkColors() else {...}
kotlin
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 })
                }
            }
        }
    }
}
Context menu: Dark theme

本地化菜单项 ​

默认情况下,上下文菜单将以系统设置的首选语言显示:

Context menu: Localization

如果您希望使用特定语言,请在运行应用程序之前显式指定默认语言:

Console
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 = {...}
kotlin
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") }
    )
}
Default context menu for TextField

详细信息请参阅 API 参考。

简单的文本元素默认上下文菜单仅包含复制操作。 若要为 Text 组件启用上下文菜单,可以通过将其包装在 SelectionContainer 中使其变为可选中:

SelectionContainer { Text( {...}
kotlin
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!")
    }
}
Default context menu for Text

添加自定义项 ​

若要为 TextField 和 Text 组件添加自定义上下文菜单操作,请通过 ContextMenuItem 指定新项,并通过 ContextMenuDataProvider 将它们添加到上下文菜单项的层次结构中。例如,以下代码示例演示了如何向文本字段和简单可选文本元素的默认上下文菜单中添加两个新的自定义操作:

ContextMenuDataProvider( items = { listOf( ContextMenuItem( {...}
kotlin
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!")
            }
        }
    }
}
Context menu with custom actions

重写默认文本上下文菜单 ​

若要重写文本字段和可选文本元素的默认上下文菜单,请重写 TextContextMenu 接口。 在以下代码示例中,我们复用了原始的 TextContextMenu,但在列表底部添加了一个额外的项。 该新项会根据选中的文本进行自适应调整:

CompositionLocalProvider( LocalTextContextMenu provides object : TextContextMenu { {...}
kotlin
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)}..."
Context menu: LocalTextContextMenu

Swing 互操作性 ​

如果您要将 Compose 代码嵌入到现有的 Swing 应用程序中,并且需要上下文菜单在外观和行为上与应用程序的其他部分保持一致,可以使用 JPopupTextMenu 类。在该类中,LocalTextContextMenu 使用 Swing 的 JPopupMenu 来为 Compose 组件提供上下文菜单。

fun JPopupTextMenuProvider(owner: Component, content: @Composable () -> Unit) {...}
kotlin
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
}
Context menu: Swing interoperability

后续步骤 ​

探索有关其他桌面组件的教程。