【Harmony】文本公共接口EditMenuOptions的使用

一、EditMenuOptions介绍

EditMenuOptions用于设置自定义菜单扩展项，允许用户设置扩展项的文本内容、图标、回调方法。支持的组件：Text，TextArea，TextInput，RichEditor，Search。

在最新的API15/16中,TextMenuItemId接口新增了TRANSLATE属性值，通过结合自定义菜单项，可以实现更为丰富的功能。

二、相关接口介绍

2.1、editMenuOptions

设置自定义菜单扩展项

editMenuOptions(editMenu: EditMenuOptions)

参数名	类型	必填	说明
editMenu	EditMenuOptions	是	扩展菜单选项。

2.2、EditMenuOptions

onCreateMenu函数说明

onCreateMenu(menuItems: Array<TextMenuItem>): Array<TextMenuItem>

菜单数据模版编辑能力。

参数：

参数名	类型	必填	说明
menuItems	Array<TextMenuItem>	是	菜单项。**说明：**对默认菜单项的名称修改不生效。

返回值：

类型	说明
Array<TextMenuItem>	设置的菜单项。**说明：**不返回系统默认菜单项的图标。

onMenuItemClick函数说明

onMenuItemClick(menuItem: TextMenuItem, range: TextRange): boolean

菜单项功能函数。

参数：

参数名	类型	必填	说明
menuItem	TextMenuItem	是	菜单项。
range	TextRange	是	选中的文本信息。

返回值：

类型	说明
boolean	菜单项的执行逻辑。返回为true，拦截系统默认逻辑，仅执行自定义逻辑。返回为false，先执行自定义逻辑，再执行系统逻辑。

2.3、TextRange对象说明

//举例：声明一个TextRange对象
let range:TextRange={start:1,//用户选中文本开始的位置的索引，这里的1代表选中这段文本开始的字符位置索引end:3//用户选中文本结束的位置的索引，这里的3代表选中这段文本结束的字符位置索引
}
//例如一个文本，”我喜欢编程“，那么选中的文字就是“喜欢”

名称	类型	必填	说明
start	number	否	起始索引。
end	number	否	结束索引。

2.4、TextMenuItem对象说明

//举例：声明一个TextMenuItem对象
let itemForward:TextMenuItem = {content: "转发",//必填 文本内容icon: $r("app.media.startIcon"),//选填 图标,注意：这里资源不支持网络图片id: TextMenuItemId.of("itemForward"), //必填 字符串/资源菜单id。//labelInfo?: ResourceStr; //选填 快捷键提示，例如复制项的提示是"Ctrl+C"。注意：该字段仅2in1设备支持
}

名称	类型	必填	说明
content	ResourceStr	是	菜单名称。
icon	ResourceStr	否	菜单图标。不支持网络图片。
id	TextMenuItemId	是	菜单id。
labelInfo15+	ResourceStr	否	快捷键提示。该字段仅2in1设备支持。元服务API： 从API version 15开始，该接口支持在元服务中使用。

2.5、TextMenuItemId

自定义菜单项的Id值。用于识别菜单选项，内置菜单项Id值见下列属性表格。

属性

名称	类型	只读	可选	说明
CUT	TextMenuItemId	是	是	默认裁剪。
COPY	TextMenuItemId	是	是	默认复制。
PASTE	TextMenuItemId	是	是	默认粘贴。
SELECT_ALL	TextMenuItemId	是	是	默认全选。
COLLABORATION_SERVICE	TextMenuItemId	是	是	互通服务。
CAMERA_INPUT	TextMenuItemId	是	是	拍摄输入。
AI_WRITER13+	TextMenuItemId	是	是	可对选中的文本进行润色、摘要提取、排版等。该菜单项依赖大模型能力，否则不生效。
TRANSLATE15+	TextMenuItemId	是	是	对选中的文本提供翻译服务。

of

static of(id: ResourceStr): TextMenuItemId//静态方法，通过传入id创建TextMenuItemId。//举例:创建一个id为column的TextMenuItemId
let textMenuItemId =TextMenuItemId.of("column")

参数：

参数名	类型	必填	说明
id	ResourceStr	是	菜单的id。

返回值：

类型	说明
TextMenuItemId	TextMenuItemId的对象。

equals

equals(id: TextMenuItemId): boolean//通过传入id比较是否相等，需要通过类型为TextMenuItemId的对象调用。//举例：判断TextMenuItemId是否相等。
let textMenuItemId =TextMenuItemId.of("column")
let result= textMenuItemId.equals("column2")//result结果为：false

参数：

参数名	类型	必填	说明
id	TextMenuItemId	是	TextMenuItemId的id。

返回值：

类型	说明
boolean	两个TextMenuItemId是否相等。true表示相等，false表示不相等。

三、简单案例

import { promptAction } from '@kit.ArkUI'@Entry
@Component
struct Index {onCreateMenu = (menuItems: TextMenuItem[]):TextMenuItem[] =>{//1.这个传入的数组每项类型是TextMenuItem，我们随便定义三项：“转发“,"撤回","引用"//1.1“转发“let itemForward:TextMenuItem = {content: "转发",//必填 文本内容icon: $r("app.media.startIcon"),//选填 图标,注意：这里资源不支持网络图片id: TextMenuItemId.of("itemForward"), //必填 字符串/资源菜单id。//labelInfo?: ResourceStr; //选填 快捷键提示，例如复制项的提示是"Ctrl+C"。注意：该字段仅2in1设备支持}//1.2"撤回"let itemWithdraw:TextMenuItem ={content: "撤回",icon: $r("app.media.startIcon"),id: TextMenuItemId.of("itemWithdraw"),}//1.3"引用"let itemReferences:TextMenuItem ={content: "引用",icon: $r("app.media.startIcon"),id: TextMenuItemId.of("itemReferences"),}//2.将上面定义的三个菜单项，添加到传入的数组中,如果菜单项多就循环添加menuItems.push(itemForward)menuItems.push(itemWithdraw)menuItems.push(itemReferences)//3.返回传入的数组return menuItems}onMenuItemClick = (menuItem: TextMenuItem, range: TextRange): boolean =>{//这里返回值是true还是false不影响我们自定义的菜单项，因为无论是是true还是false我们自定义拦截的逻辑都会执行//这里的返回值是true还是false针对的是系统内置的菜单项，比如"复制","翻译","全选"这类菜单项，//这些系统内置的菜单项有自己的逻辑实现，我们通过TextMenuItemId也可以拦截系统内置的菜单项添加我们的逻辑，比如在"翻译"之前我想添加一个窗口，//用于用户选择翻译哪国语言，这种情况我们需要拦截"翻译"菜单项，然后添加窗口实现，然后通过返回false，先执行自定义逻辑，再执行系统逻辑。//如果返回的是true，那么只会执行我们的逻辑，系统逻辑就被拦截了不会执行。相当于重写//拦截自定义菜单项"转发"if(menuItem.id.equals(TextMenuItemId.of("itemForward"))){//TODO:转发的逻辑。。。return true;//这里返回值无所谓，什么都行}//拦截自定义菜单项"引用"if(menuItem.id.equals(TextMenuItemId.of("itemReferences"))){//TODO:引用的逻辑。。。return false;//这里返回值无所谓，什么都行}//拦截系统内置菜单项”翻译“if(menuItem.id.equals(TextMenuItemId.of("OH_DEFAULT_TRANSLATE"))){//TODO:翻译的逻辑。。。promptAction.showDialog({message:"翻译之前的窗口：中文，英文，日文"})return false;//这里需要返回false，让自定义逻辑在系统逻辑之前执行。}//拦截系统内置菜单项”全选“if(menuItem.id.equals(TextMenuItemId.of("OH_DEFAULT_SELECT_ALL"))){//TODO:重写全选的逻辑promptAction.showToast({message:"全选失效了，因为被我拦截了"})return true;//这里返回true,系统逻辑就不会执行，而是执行我们的逻辑。}return false}//EditMenuOptions接口里面定义的是两个回调方法，这里可以直接选择在箭头函数中实现，也也可在外部定义通过引用传递//参数1：onCreateMenu(menuItems: Array<TextMenuItem>): Array<TextMenuItem>;这个方法我们需要操作他传入的参数//menuItems这个数组，向这个数组添加菜单项，然后返回这个数组。//参数2：onMenuItemClick(menuItem: TextMenuItem, range: TextRange): boolean;这个方法用于我们实现操作菜单//项的逻辑实现，其中menuItem是传入的菜单项，range是选中文本的信息。这个方法每次调用会给我们返回一个布尔值//返回为true，拦截系统默认逻辑，仅执行自定义逻辑。//返回为false，先执行自定义逻辑，再执行系统逻辑。@State editMenu:EditMenuOptions = {onCreateMenu:this.onCreateMenu,onMenuItemClick:this.onMenuItemClick}build() {Column() {Text("文本扩展自定义菜单").fontSize(30).width("100%").textAlign(TextAlign.Center).copyOption(CopyOptions.LocalDevice)//实现自定义菜单项建议搭配copyOption实现.editMenuOptions(this.editMenu) //需要传递一个EditMenuOptions类型的参数,此处选择在外部定义editMenu}.width("100%")}
}