diff --git a/zh-cn/application-dev/basic-services/Readme-CN.md b/zh-cn/application-dev/basic-services/Readme-CN.md index c82026fb1b91365e0cbcef164a20c1b506e70714..0a056d35f763c51a6a56dc30fee963a0a591f813 100644 --- a/zh-cn/application-dev/basic-services/Readme-CN.md +++ b/zh-cn/application-dev/basic-services/Readme-CN.md @@ -7,4 +7,5 @@ - [升级服务](update/Readme-CN.md) - [剪贴板服务](pasteboard/Readme-CN.md) - [上传下载](request/Readme-CN.md) -- [压缩与解压](compress/Readme-CN.md) \ No newline at end of file +- [压缩与解压](compress/Readme-CN.md) +- [划词服务](selectionInput/Readme-CN.md) \ No newline at end of file diff --git a/zh-cn/application-dev/basic-services/basic-services-kit-overview.md b/zh-cn/application-dev/basic-services/basic-services-kit-overview.md index 239dd17474a3aad6a292f97c9ea16288fb034fc9..c9b6b9ec81775ea5049af69893137354f1b7e6e7 100644 --- a/zh-cn/application-dev/basic-services/basic-services-kit-overview.md +++ b/zh-cn/application-dev/basic-services/basic-services-kit-overview.md @@ -28,6 +28,7 @@ Basic Services Kit为开发者提供了多种基础能力，满足开发者不 - [压缩](../reference/apis-basic-services-kit/js-apis-zlib.md)：提供文件压缩解压缩的能力。 - [打印](../reference/apis-basic-services-kit/js-apis-print.md)：提供基础文件打印的能力，比如传入文件进行打印、设置打印参数等。 - [上传下载](../reference/apis-basic-services-kit/js-apis-request.md)：提供文件上传下载、后台传输代理的基础能力。 + - [划词服务](../reference/apis-basic-services-kit/js-apis-selectionInput-selectionManager.md)：提供划词配置同步接口，划词服务SA监听多模键鼠事件获取鼠标和触控板操作窗口和应用信息，DFX增强。 - 进程间/线程间通信： - [公共事件](../reference/apis-basic-services-kit/js-apis-commonEventManager.md)：提供进程间通信的能力，包括订阅、发布、退订公共事件等，相关开发指南请参考[公共事件简介](common-event/common-event-overview.md)。 diff --git a/zh-cn/application-dev/basic-services/selectionInput/Readme-CN.md b/zh-cn/application-dev/basic-services/selectionInput/Readme-CN.md new file mode 100644 index 0000000000000000000000000000000000000000..0dd50643e6dc6275c59a18a535347a4318f6dd80 --- /dev/null +++ b/zh-cn/application-dev/basic-services/selectionInput/Readme-CN.md @@ -0,0 +1,4 @@ +# 划词服务 + +- [划词服务概述](selection-services-intro.md) +- [实现一个划词应用](selection-services-application-guide.md) diff --git a/zh-cn/application-dev/basic-services/selectionInput/figures/device-connection.png b/zh-cn/application-dev/basic-services/selectionInput/figures/device-connection.png new file mode 100644 index 0000000000000000000000000000000000000000..bc089b7d142341f34dc2e522689877e8ab0ccd4b Binary files /dev/null and b/zh-cn/application-dev/basic-services/selectionInput/figures/device-connection.png differ diff --git a/zh-cn/application-dev/basic-services/selectionInput/figures/selection-application-project.png b/zh-cn/application-dev/basic-services/selectionInput/figures/selection-application-project.png new file mode 100644 index 0000000000000000000000000000000000000000..6aadd76ed2ce21995f977e04e780af7d177f0b30 Binary files /dev/null and b/zh-cn/application-dev/basic-services/selectionInput/figures/selection-application-project.png differ diff --git "a/zh-cn/application-dev/basic-services/selectionInput/figures/\345\210\222\350\257\215\346\234\215\345\212\241\346\241\206\346\236\266\345\216\237\347\220\206\345\233\276.jpg" "b/zh-cn/application-dev/basic-services/selectionInput/figures/\345\210\222\350\257\215\346\234\215\345\212\241\346\241\206\346\236\266\345\216\237\347\220\206\345\233\276.jpg" new file mode 100644 index 0000000000000000000000000000000000000000..b51b7a68ade654cfce9cd82ed1e61382c86c01ff Binary files /dev/null and "b/zh-cn/application-dev/basic-services/selectionInput/figures/\345\210\222\350\257\215\346\234\215\345\212\241\346\241\206\346\236\266\345\216\237\347\220\206\345\233\276.jpg" differ diff --git a/zh-cn/application-dev/basic-services/selectionInput/selection-services-application-guide.md b/zh-cn/application-dev/basic-services/selectionInput/selection-services-application-guide.md new file mode 100644 index 0000000000000000000000000000000000000000..cc11ac885127e628efa6f4c472f2adea57fd9f24 --- /dev/null +++ b/zh-cn/application-dev/basic-services/selectionInput/selection-services-application-guide.md @@ -0,0 +1,149 @@ +# 实现一个划词应用 + +## 接口说明 + +接口详情参见[selectionInput.SelectionManager](../../reference/apis-basic-services-kit/js-apis-selectionInput-selectionManager.md)、[selectionInput.SelectionExtensionAbility](../../reference/apis-basic-services-kit/js-apis-selectionInput-selectionExtensionAbility.md)、[selectionInput.SelectionExtensionContext](../../reference/apis-basic-services-kit/js-apis-selectionInput-selectionExtensionContext.md)和[selectionInput.SelectionPanel](../../reference/apis-basic-services-kit/js-apis-selectionInput-selectionPanel.md)。 + +| 名称 | 描述 | +| ---- | ---- | +| on(type: 'selectionCompleted', callback: Callback\): void | 订阅划词完成事件，使用`callback`回调函数。 | +| createPanel(ctx: Context, info: PanelInfo): Promise\ | 创建划词面板。 | +| show(): Promise\ | 显示面板。 | + +## 开发步骤 + +以下步骤描述了划词应用的开发流程： + +1. 创建划词应用工程 + +![划词应用工程](figures/selection-application-project.png) + +2. 引入模块 +```ts + +``` + +3. 继承划词ExtensionAbility实现扩展生命周期函数 + ```ts + import { selectionManager, PanelInfo, PanelType, SelectionExtensionAbility } from '@kit.BasicServicesKit'; + + class SelectionAbilityStub extends rpc.RemoteObject { + constructor(des) { + if (typeof des === 'string') { + super(des); + } else { + return null; + } + } + + onRemoteMessageRequest( + code: number, + data: rpc.MessageSequence, + reply: rpc.MessageSequence, + options: rpc.MessageOption + ): boolean | Promise { + return true; + } + } + + class ServiceExtAbility extends SelectionExtensionAbility { + panel_: selectionManager.Panel = undefined; + + onConnect(want: Want): rpc.RemoteObject { + return new SelectionAbilityStub('remote'); + } + + onDisconnect(): void { + } + } + ``` + +4. 使用划词Ability接口监听划词事件 +```ts +selectionManager.on('selectionCompleted', (info: selectionManager.SelectionInfo) => { +}); +``` + +5. 使用划词Ability接口创建划词窗口 +```ts +let panelInfo: PanelInfo = { + panelType: PanelType.MENU_PANEL, + x: 0, + y: 0, + width: 500, + height: 200 +} +selectionManager.createPanel(this.context, panelInfo) + .then(async (panel: selectionManager.Panel) => { + panel.setUiContent('pages/MenuPanel') + .then(()=>{ + }) + .catch((error: BusinessError) => { + }); + this.panel_ = panel; + }) + .catch((error: BusinessError) => { + }); +``` + +6. 使用划词Ability接口销毁划词窗口 +```ts +selectionManager.destroyPanel(this.panel_); +``` + +## 代码文件介绍 + +``` +/src/main/ +├── ets/ +│ ├── pages +│ | ├── MainPanel.ets # 主面板 +│ | └── MenuPanel.ets # 菜单面板 +| └── ServiceExtAbility +│ └── SelectionExtensionAbility.ts # 划词扩展类 +├── resources/base/profile/main_pages.json +├── module.json5 # 配置文件 +``` + +1. 划词应用配置文件介绍 + +`module.json5`中需要在`requestPermissions`子项中添加应用所需权限，在`extensionAbilities`子项中指定划词扩展类文件路径。 + +```json +{ + "module": { + ... + "requestPermissions": [ + { + "name": "ohos.permission.START_ABILITIES_FROM_BACKGROUND" + } + ], + "extensionAbilities": [ + { + "name": "SelectionExtensionAbility", + "srcEntry": "./ets/ServiceExtAbility/SelectionExtensionAbility.ts", + "type": "selection", + "exported": false, + } + ] + } +} +``` + +2. 划词ExtensionAbility实现类介绍 + +应用划词扩展类 `ServiceExtAbility` 继承自 `ServiceExtAbility`，实现 `onConnect` 和 `onDisconnect` 方法进行生命周期管理。其中，`onConnect` 方法在用户划词并启动划词扩展时触发。 + +## 调测验证 + +1. 通过设置系统参数设置划词配置 + +- 从设置中打开划词开关 +- 选择当前应用为划词应用 +- 设置划词触发方式 + +2. 通过日志观察划词服务拉起划词ExtensionAbility过程 + +使用DevEco Studio的Hilog窗口查看日志。 + +3. 使用鼠标左键单击选中文本，观察界面弹出划词窗口 diff --git a/zh-cn/application-dev/basic-services/selectionInput/selection-services-intro.md b/zh-cn/application-dev/basic-services/selectionInput/selection-services-intro.md new file mode 100644 index 0000000000000000000000000000000000000000..52c57dd8ebca50cfe44045d5c959f8a32e3732a9 --- /dev/null +++ b/zh-cn/application-dev/basic-services/selectionInput/selection-services-intro.md @@ -0,0 +1,41 @@ +# 划词服务概述 + +划词服务建立被划词应用与划词应用之间的通信通道，确保两者协作处理划词内容，并提供系统应用管理划词应用的能力。 + +## 场景介绍 + +随着系统原生能力的完善和开放生态的支持，"划词服务"应运而生，进一步拓展了文本交互的便捷性。其业务场景包括但不限于文本翻译、内容摘要、术语解释，满足用户高效获取信息的需求，提升跨场景下的文本处理效率。 + +## 框架原理 + +系统通过开关控制划词服务的启停。划词服务运行时，监听多模事件以识别划词动作，并通过剪贴板接口设置划词标记，触发模拟CTRL+C操作。目标应用将选中文本写入剪贴板后，剪贴板回调划词服务接口，回传划词内容，由划词服务发送给上层应用处理。 + +![划词服务框架原理图](figures/划词服务框架原理图.jpg) + +## 功能特点 + +- 划词方式： + + 支持识别滑动、双击、三击三种划词方式。 + +- 划词窗口管理： + + 支持菜单窗口和主窗口两种类型，提供窗口创建、移动、隐藏、销毁等接口，并支持自定义窗口界面。 + +## 能力范围 + +- 提供划词扩展相关API，用于划词应用生命周期管理等。 + +- 提供划词Ability相关API，用于监听划词内容，以及划词窗口创建、销毁等。 + +- 提供划词Panel相关API，用于划词窗口相关操作，包括：设置界面内容、移动、隐藏等，监听隐藏、销毁事件等。 + +## 约束限制 + +- 划词事件支持键鼠外设。 + +- 支持获取文本类型划词内容。 + +- 6.0版本支持PC运行划词服务。 + +- 支持翻译类，AI类应用使用划词服务。 diff --git a/zh-cn/application-dev/quick-start/module-configuration-file.md b/zh-cn/application-dev/quick-start/module-configuration-file.md index 1378330af2d00f9accbd8ae30de0192d5f83891a..10fb90517cf90b865e65ccf341c1c5124e7552f8 100644 --- a/zh-cn/application-dev/quick-start/module-configuration-file.md +++ b/zh-cn/application-dev/quick-start/module-configuration-file.md @@ -523,7 +523,7 @@ skills示例： | description | 标识当前ExtensionAbility组件的描述，开发者可以通过该字段描述当前组件的功能与作用，取值为长度不超过255字节的字符串，可以是对描述内容的资源索引，用于支持多语言。 | 字符串 | 该标签可缺省，缺省值为空。 | | icon | 标识当前ExtensionAbility组件的图标，取值为资源文件的索引。如果ExtensionAbility组件被配置为mainElement，该标签必须配置。 | 字符串 | 该标签可缺省，缺省值为空。 | | label | 标识当前ExtensionAbility组件对用户显示的名称，取值为该名称的资源索引，以支持多语言，字符串长度不超过255字节。如果ExtensionAbility被配置当前Module的mainElement时，该标签必须配置，且要确保应用内唯一。 | 字符串 | 该标签可缺省，缺省值为空。 | -| type | 标识当前ExtensionAbility组件的类型，支持的取值如下：
- form：卡片的ExtensionAbility。
- workScheduler：延时任务的ExtensionAbility。
- inputMethod：输入法的ExtensionAbility。
- service：后台运行的service组件。
- accessibility：辅助能力的ExtensionAbility。
- fileAccess：公共数据访问的ExtensionAbility，允许应用程序提供文件和文件夹给文件管理类应用展示。
- dataShare：数据共享的ExtensionAbility。
- staticSubscriber：静态广播的ExtensionAbility。
- wallpaper：壁纸的ExtensionAbility。
- backup：数据备份的ExtensionAbility。
- enterpriseAdmin：[企业设备管理](../mdm/mdm-kit-admin.md)的ExtensionAbility。企业设备管理应用必须拥有此类型的ExtensionAbility。
- window：该ExtensionAbility会在启动过程中创建一个window，为开发者提供界面开发。开发者开发出来的界面将通过UIExtensionComponent控件组合到其他应用的窗口中。
- thumbnail：获取文件缩略图的ExtensionAbility，开发者可以对自定义文件类型的文件提供缩略。
- preview：该ExtensionAbility会将文件解析后在一个窗口中显示，开发者可以通过将此窗口组合到其他应用窗口中。
- print：打印框架的ExtensionAbility。
- push：推送的ExtensionAbility。
- driver：驱动框架的ExtensionAbility。应用配置了driver类型的ExtensionAbility后会被视为驱动应用，驱动应用在安装、卸载和恢复时不会区分用户，且创建新用户时也会安装设备上已有的驱动应用。例如，创建子用户时会默认安装主用户已有的驱动应用，在子用户上卸载驱动应用时，主用户上对应的驱动应用也会同时被卸载。
- remoteNotification：远程通知的ExtensionAbility。
- remoteLocation：远程定位的ExtensionAbility。
- voip：网络音视频通话的ExtensionAbility。
- action：自定义操作业务模板的ExtensionAbility，为开发者提供基于UIExtension的自定义操作业务模板。
- adsService：广告业务的ExtensionAbility，提供广告业务框架。
- embeddedUI：嵌入式UI扩展能力，提供跨进程界面嵌入的能力。
- insightIntentUI：为开发者提供能被小艺意图调用，以窗口形态呈现内容的扩展能力。
- ads：广告业务的ExtensionAbility，与AdComponent控件组合使用，将广告页面展示到其他应用中。仅支持设备厂商使用。
- photoEditor：图片编辑业务的ExtensionAbility，为开发者提供基于UIExtension的图片编辑业务模版。
- appAccountAuthorization：应用账号授权扩展能力的ExtensionAbility，用于处理账号授权请求，比如账号登录授权。
- autoFill/password：用于账号和密码自动填充业务的ExtensionAbility，支持数据的保存、填充能力。
- hms/account：应用账号管理能力的ExtensionAbility。
- sysDialog/atomicServicePanel：提供构建原子化服务服务面板的基础能力的ExtensionAbility，使用时基于UIExtensionAbility实现。
- sysDialog/userAuth：本地用户鉴权的ExtensionAbility。
- sysDialog/common：通用弹窗的ExtensionAbility。
- sysDialog/power：关机重启弹窗的ExtensionAbility。
- sysDialog/print：打印模态弹窗的ExtensionAbility。
- sysDialog/meetimeCall：畅连通话的ExtensionAbility。
- sysDialog/meetimeContact：畅连联系人的ExtensionAbility。
- sysPicker/meetimeMessage：畅连消息的ExtensionAbility。
- sysPicker/meetimeContact：畅连联系人列表的ExtensionAbility。
- sysPicker/meetimeCallLog：畅连通话记录列表的ExtensionAbility。
- sysPicker/share：系统分享的ExtensionAbility。
- sysPicker/mediaControl：投播组件的ExtensionAbility。
- sysPicker/photoPicker：三方应用通过对应的UIExtensionType拉起图库picker界面。
- sysPicker/filePicker：文件下载弹窗的ExtensionAbility。
- sysPicker/audioPicker：音频管理弹窗的ExtensionAbility。
- sysPicker/photoEditor：图片编辑弹窗的ExtensionAbility。
- sys/commonUI：非通用的ExtensionAbility，提供业务属性强相关的嵌入式显示或弹框。
- autoFill/smart：用于情景化场景自动填充业务的ExtensionAbility，支持数据的保存、填充能力。
- uiService：弹窗服务组件，在启动过程中会创建window，并支持双向通信。
- statusBarView：一步直达的ExtensionAbility。
- recentPhoto：最近照片推荐的ExtensionAbility。
- fence：地理围栏的ExtensionAbility。
- callerInfoQuery：企业联系人查询的ExtensionAbility。
- assetAcceleration：资源预下载的ExtensionAbility。
- formEdit：卡片编辑的ExtensionAbility。
- distributed：分布式扩展的ExtensionAbility。
- liveForm：互动卡片的[ExtensionAbility](../reference/apis-form-kit/js-apis-app-form-LiveFormExtensionAbility.md)。从API version 20开始，支持该字段。
- appService：为[企业普通应用](../security/AccessToken/permissions-for-enterprise-apps.md)提供后台服务相关扩展能力[AppServiceExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-appServiceExtensionAbility.md)，包括后台服务的创建、销毁、连接、断开等生命周期回调。从API version 20开始，支持该字段。
- awc/webpage：通用网页浏览的ExtensionAbility。
- awc/newsfeed：信息流资讯业务的ExtensionAbility。
**说明：**
其中service、adsService、staticSubscriber、window、sys/commonUI、fileAccess、sysDialog类型、sysPicker类型、dataShare类型和uiService类型，三方应用的配置不生效，当前配置仅在系统应用中有效。 | 字符串 | 该标签不可缺省。 | +| type | 标识当前ExtensionAbility组件的类型，支持的取值如下：
- form：卡片的ExtensionAbility。
- workScheduler：延时任务的ExtensionAbility。
- inputMethod：输入法的ExtensionAbility。
- service：后台运行的service组件。
- accessibility：辅助能力的ExtensionAbility。
- fileAccess：公共数据访问的ExtensionAbility，允许应用程序提供文件和文件夹给文件管理类应用展示。
- dataShare：数据共享的ExtensionAbility。
- staticSubscriber：静态广播的ExtensionAbility。
- wallpaper：壁纸的ExtensionAbility。
- backup：数据备份的ExtensionAbility。
- enterpriseAdmin：[企业设备管理](../mdm/mdm-kit-admin.md)的ExtensionAbility。企业设备管理应用必须拥有此类型的ExtensionAbility。
- window：该ExtensionAbility会在启动过程中创建一个window，为开发者提供界面开发。开发者开发出来的界面将通过UIExtensionComponent控件组合到其他应用的窗口中。
- thumbnail：获取文件缩略图的ExtensionAbility，开发者可以对自定义文件类型的文件提供缩略。
- preview：该ExtensionAbility会将文件解析后在一个窗口中显示，开发者可以通过将此窗口组合到其他应用窗口中。
- print：打印框架的ExtensionAbility。
- push：推送的ExtensionAbility。
- driver：驱动框架的ExtensionAbility。应用配置了driver类型的ExtensionAbility后会被视为驱动应用，驱动应用在安装、卸载和恢复时不会区分用户，且创建新用户时也会安装设备上已有的驱动应用。例如，创建子用户时会默认安装主用户已有的驱动应用，在子用户上卸载驱动应用时，主用户上对应的驱动应用也会同时被卸载。
- remoteNotification：远程通知的ExtensionAbility。
- remoteLocation：远程定位的ExtensionAbility。
- voip：网络音视频通话的ExtensionAbility。
- action：自定义操作业务模板的ExtensionAbility，为开发者提供基于UIExtension的自定义操作业务模板。
- adsService：广告业务的ExtensionAbility，提供广告业务框架。
- embeddedUI：嵌入式UI扩展能力，提供跨进程界面嵌入的能力。
- insightIntentUI：为开发者提供能被小艺意图调用，以窗口形态呈现内容的扩展能力。
- ads：广告业务的ExtensionAbility，与AdComponent控件组合使用，将广告页面展示到其他应用中。仅支持设备厂商使用。
- photoEditor：图片编辑业务的ExtensionAbility，为开发者提供基于UIExtension的图片编辑业务模版。
- appAccountAuthorization：应用账号授权扩展能力的ExtensionAbility，用于处理账号授权请求，比如账号登录授权。
- autoFill/password：用于账号和密码自动填充业务的ExtensionAbility，支持数据的保存、填充能力。
- hms/account：应用账号管理能力的ExtensionAbility。
- sysDialog/atomicServicePanel：提供构建原子化服务服务面板的基础能力的ExtensionAbility，使用时基于UIExtensionAbility实现。
- sysDialog/userAuth：本地用户鉴权的ExtensionAbility。
- sysDialog/common：通用弹窗的ExtensionAbility。
- sysDialog/power：关机重启弹窗的ExtensionAbility。
- sysDialog/print：打印模态弹窗的ExtensionAbility。
- sysDialog/meetimeCall：畅连通话的ExtensionAbility。
- sysDialog/meetimeContact：畅连联系人的ExtensionAbility。
- sysPicker/meetimeMessage：畅连消息的ExtensionAbility。
- sysPicker/meetimeContact：畅连联系人列表的ExtensionAbility。
- sysPicker/meetimeCallLog：畅连通话记录列表的ExtensionAbility。
- sysPicker/share：系统分享的ExtensionAbility。
- sysPicker/mediaControl：投播组件的ExtensionAbility。
- sysPicker/photoPicker：三方应用通过对应的UIExtensionType拉起图库picker界面。
- sysPicker/filePicker：文件下载弹窗的ExtensionAbility。
- sysPicker/audioPicker：音频管理弹窗的ExtensionAbility。
- sysPicker/photoEditor：图片编辑弹窗的ExtensionAbility。
- sys/commonUI：非通用的ExtensionAbility，提供业务属性强相关的嵌入式显示或弹框。
- autoFill/smart：用于情景化场景自动填充业务的ExtensionAbility，支持数据的保存、填充能力。
- uiService：弹窗服务组件，在启动过程中会创建window，并支持双向通信。
- statusBarView：一步直达的ExtensionAbility。
- recentPhoto：最近照片推荐的ExtensionAbility。
- fence：地理围栏的ExtensionAbility。
- callerInfoQuery：企业联系人查询的ExtensionAbility。
- assetAcceleration：资源预下载的ExtensionAbility。
- formEdit：卡片编辑的ExtensionAbility。
- distributed：分布式扩展的ExtensionAbility。
- liveForm：互动卡片的[ExtensionAbility](../reference/apis-form-kit/js-apis-app-form-LiveFormExtensionAbility.md)。从API version 20开始，支持该字段。
- appService：为[企业普通应用](../security/AccessToken/permissions-for-enterprise-apps.md)提供后台服务相关扩展能力[AppServiceExtensionAbility](../reference/apis-ability-kit/js-apis-app-ability-appServiceExtensionAbility.md)，包括后台服务的创建、销毁、连接、断开等生命周期回调。从API version 20开始，支持该字段。
- awc/webpage：通用网页浏览的ExtensionAbility。
- awc/newsfeed：信息流资讯业务的ExtensionAbility。
- selection：划词扩展的[ExtensionAbility](../reference/apis-basic-services-kit/js-apis-selectionInput-selectionExtensionAbility.md)。从API version 20开始，支持该字段。
**说明：**
其中service、adsService、staticSubscriber、window、sys/commonUI、fileAccess、sysDialog类型、sysPicker类型、dataShare类型和uiService类型，三方应用的配置不生效，当前配置仅在系统应用中有效。 | 字符串 | 该标签不可缺省。 | | permissions | 标识当前ExtensionAbility组件自定义的权限信息。当其他应用访问该ExtensionAbility时，需要申请相应的权限信息。
一个数组元素为一个权限名称。通常采用反向域名格式（最大255字节），取值为[系统预定义的权限](../security/AccessToken/app-permissions.md)。 | 字符串数组 | 该标签可缺省，缺省值为空。 | | appIdentifierAllowList | 标识允许启动此ExtensionAbility的应用程序列表。
一个数组元素为一个应用程序的appIdentifier，appIdentifier信息可参考[应用包信息](../reference/apis-ability-kit/js-apis-bundleManager-bundleInfo.md#signatureinfo)。
**说明：**
仅当ExtensionAbility组件的type为appService时支持配置该标签。
从API version 20开始，支持该字段。 | 字符串数组 | 该标签可缺省，缺省值为空。 | | readPermission | 标识读取当前ExtensionAbility组件数据所需的权限，取值为长度不超过255字节的字符串。仅当ExtensionAbility组件的type为dataShare时支持配置该标签。 | 字符串 | 该标签可缺省，缺省值为空。 | diff --git a/zh-cn/application-dev/reference/apis-ability-kit/js-apis-bundleManager.md b/zh-cn/application-dev/reference/apis-ability-kit/js-apis-bundleManager.md index a5cfddc0ad3119e285e107de91fd9f207227236b..0c4b3e1e72bab27baf6a8055085a1f1b10002d50 100644 --- a/zh-cn/application-dev/reference/apis-ability-kit/js-apis-bundleManager.md +++ b/zh-cn/application-dev/reference/apis-ability-kit/js-apis-bundleManager.md @@ -68,6 +68,7 @@ import { bundleManager } from '@kit.AbilityKit'; | DISTRIBUTED18+ | 28 | [DistributedExtensionAbility](../apis-distributedservice-kit/js-apis-distributedExtensionAbility.md)：提供分布式相关扩展能力，提供分布式创建、销毁、连接的生命周期回调。 | | APP_SERVICE20+ | 29 | [AppServiceExtensionAbility](../apis-ability-kit/js-apis-app-ability-appServiceExtensionAbility.md)：为企业普通应用提供后台服务能力。 | | LIVE_FORM20+ | 30 | [LiveFormExtensionAbility](../apis-form-kit/js-apis-app-form-LiveFormExtensionAbility.md)：互动卡片相关扩展能力，提供互动卡片创建、销毁的生命周期回调。
**原子化服务API：** 从API version 20开始，该接口支持在原子化服务中使用。| +| SELECTION20+ | 31 | [SelectionExtensionAbility](../apis-basic-services-kit/js-apis-selectionInput-selectionExtensionAbility.md)：划词相关扩展能力，提供连接和断开回调。 | | UNSPECIFIED | 255 | 不指定类型，配合[queryExtensionAbilityInfo接口](js-apis-bundleManager-sys.md#bundlemanagerqueryextensionabilityinfo)可以查询所有类型的ExtensionAbility。 | diff --git a/zh-cn/application-dev/reference/apis-basic-services-kit/Readme-CN.md b/zh-cn/application-dev/reference/apis-basic-services-kit/Readme-CN.md index e37ce9c180ed450932942eefaf82a71b91414a34..05620734941a3368b4e1096a5c8cfaae68390305 100644 --- a/zh-cn/application-dev/reference/apis-basic-services-kit/Readme-CN.md +++ b/zh-cn/application-dev/reference/apis-basic-services-kit/Readme-CN.md @@ -42,6 +42,10 @@ - [@ohos.app.ability.PrintExtensionAbility (打印扩展能力)(系统接口)](js-apis-app-ability-PrintExtensionAbility-sys.md) - [@ohos.print (打印)(系统接口)](js-apis-print-sys.md) - [@ohos.request (上传下载)(系统接口)](js-apis-request-sys.md) + - [@ohos.selectionInput.SelectionExtensionAbility (划词扩展能力)](js-apis-selectionInput-selectionExtensionAbility.md) + - [@ohos.selectionInput.SelectionExtensionContext (划词扩展上下文)](js-apis-selectionInput-selectionExtensionContext.md) + - [@ohos.selectionInput.selectionManager (划词管理)](js-apis-selectionInput-selectionManager.md) + - [@ohos.selectionInput.SelectionPanel (划词面板)](js-apis-selectionInput-selectionPanel.md) - 进程线程通信 - [系统定义的公共事件](common_event/commonEventManager-definitions.md) @@ -150,4 +154,5 @@ - [设备证明错误码](errorcode-deviceAttest.md) - [智能语音错误码](errorcode-intelligentVoice.md) - [设置数据项错误码](errorcode-settings.md) + - [划词服务错误码](errorcode-selection.md) \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis-basic-services-kit/errorcode-selection.md b/zh-cn/application-dev/reference/apis-basic-services-kit/errorcode-selection.md new file mode 100644 index 0000000000000000000000000000000000000000..ee71a6cd622cf298c7ff21402758466e69873bd6 --- /dev/null +++ b/zh-cn/application-dev/reference/apis-basic-services-kit/errorcode-selection.md @@ -0,0 +1,61 @@ +# 划词服务错误码 + +> **说明：** +> +> 以下仅介绍本模块特有错误码，通用错误码请参考[通用错误码说明文档](../errorcode-universal.md)。 + +## 33600001 划词服务异常 + +**错误信息** + +Selection service exception. + +**错误描述** + +划词服务异常时，会报此错误码。 + +**可能原因** + +当划词应用调用此接口，若划词服务或其依赖的服务出现异常，系统将返回此错误码。 + +**处理步骤** + +建议重启设备后重新调用接口。 + +## 33600002 此划词窗口已被销毁 + +**错误信息** + +This selection window has been destroyed. + +**错误描述** + +此划词窗口已被销毁。 + +**可能原因** + +1. 划词窗口已被销毁。 +2. 划词窗口未被创建。 + +**处理步骤** + +1. 在操作划词窗口前，检查窗口对象是否有效。 +2. 避免操作已销毁的窗口对象。 + +## 33600003 无效操作，划词应用无效。 + +**错误信息** + +Invalid operation. The selection app is not valid. + +**错误描述** + +非法操作，划词应用无效。 + +**可能原因** + +非用户选择的划词应用调用了划词接口。 + +**处理步骤** + +在系统设置中检查当前的划词应用是否为本应用。 diff --git a/zh-cn/application-dev/reference/apis-basic-services-kit/js-apis-selectionInput-selectionExtensionAbility.md b/zh-cn/application-dev/reference/apis-basic-services-kit/js-apis-selectionInput-selectionExtensionAbility.md new file mode 100644 index 0000000000000000000000000000000000000000..18c9c24f3f3d401393c62709ce811fdf943359b2 --- /dev/null +++ b/zh-cn/application-dev/reference/apis-basic-services-kit/js-apis-selectionInput-selectionExtensionAbility.md @@ -0,0 +1,90 @@ +# @ohos.selectionInput.SelectionExtensionAbility (划词扩展能力) + +本模块支持开发者自行开发第三方应用的划词服务功能，以及生命周期管理。 + +> **说明：** +> +> 本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## 导入模块 + +```ts +import { SelectionExtensionAbility } from '@kit.BasicServicesKit'; +``` +## SelectionExtensionAbility + +### 属性 + +**系统能力：** SystemCapability.SelectionInput.Selection + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| -------- | -------- | -------- | -------- | -------- | +| context | [SelectionExtensionContext](./js-apis-selectionInput-selectionExtensionContext.md) | 否 | 否 | SelectionExtensionAbility的上下文环境，继承自ExtensionContext。 | + +### onConnect + +onConnect(want: Want): rpc.RemoteObject + +Extension生命周期回调函数，划词服务在拉起划词扩展时调用，执行划词扩展初始化操作。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ----------- | ---- | ------------------------------- | +| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 当前Extension的Want类型信息，包括ability名称、bundle名称等。 | + +**返回值：** +| 类型 | 说明 | +| ------- | ------------------------------------------------------------------ | +| [rpc.RemoteObject](../apis-ipc-kit/js-apis-rpc.md#iremoteobject) | RemoteObject对象，用于客户端和服务端通信。 | + +**示例：** + +```ts +import { SelectionExtensionAbility } from '@kit.BasicServicesKit'; +import { rpc } from '@kit.IPCKit'; +import { Want } from '@kit.AbilityKit'; +import { hilog } from '@kit.PerformanceAnalysisKit'; + +const TAG: string = '[SelectionExtensionAbility]'; + +class StubTest extends rpc.RemoteObject { + constructor(des) { + super(des); + } + onConnect(code: number, data: rpc.MessageSequence, reply: rpc.MessageSequence, option: rpc.MessageOption) { + } +} + +class ServiceExtAbility extends SelectionExtensionAbility { + onConnect(want: Want): rpc.RemoteObject { + hilog.info(0x0000, TAG, `onConnect, want: ${want.abilityName}`); + return new StubTest('test'); + } +} +``` + +### onDisconnect + +onDisconnect(): void + +Extension生命周期回调函数，划词服务在断开划词扩展时调用。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**示例：** + +```ts +import { SelectionExtensionAbility } from '@kit.BasicServicesKit'; +import { hilog } from '@kit.PerformanceAnalysisKit'; + +const TAG: string = '[SelectionExtensionAbility]'; + +class ServiceExtAbility extends SelectionExtensionAbility { + onDisconnect(): void { + hilog.info(0x0000, TAG, `onDisconnect`); + } +} +``` diff --git a/zh-cn/application-dev/reference/apis-basic-services-kit/js-apis-selectionInput-selectionExtensionContext.md b/zh-cn/application-dev/reference/apis-basic-services-kit/js-apis-selectionInput-selectionExtensionContext.md new file mode 100644 index 0000000000000000000000000000000000000000..de8e36ae0ca9630e12b44b37531d3508bd374253 --- /dev/null +++ b/zh-cn/application-dev/reference/apis-basic-services-kit/js-apis-selectionInput-selectionExtensionContext.md @@ -0,0 +1,110 @@ +# @ohos.selectionInput.SelectionExtensionContext (划词扩展上下文) + +SelectionExtensionContext模块是SelectionExtensionAbility的上下文环境，继承自ExtensionContext。 + +> **说明：** +> +> 本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## 导入模块 + +```ts +import { SelectionExtensionContext } from '@kit.BasicServicesKit'; +``` + +## SelectionExtensionContext + +### startAbility + +startAbility(want: Want): Promise\ + +拉起目标应用，使用Promise进行异步回调。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | +| want | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 想要被拉起的应用信息，包括ability名称、bundle名称等。 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ------------------------- | +| Promise\ | Promise对象，无返回结果。 | + +**错误码：** + +以下错误码的详细介绍请参见[元能力错误码](../apis-ability-kit/errorcode-ability.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------------- | +| 16000001 | The specified ability does not exist. | +| 16000002 | Incorrect ability type. | +| 16000004 | Cannot start an invisible component. | +| 16000005 | The specified process does not have the permission. | +| 16000006 | Cross-user operations are not allowed. | +| 16000008 | The crowdtesting application expires. | +| 16000009 | An ability cannot be started or stopped in Wukong mode. | +| 16000010 | The call with the continuation and prepare continuation flag is forbidden. | +| 16000011 | The context does not exist. | +| 16000012 | The application is controlled. | +| 16000013 | The application is controlled by EDM. | +| 16000019 | No matching ability is found. | +| 16000050 | Internal error. | +| 16000053 | The ability is not on the top of the UI. | +| 16000055 | Installation-free timed out. | +| 16000061 | Operation not supported. | +| 16000069 | The extension cannot start the third party application. | +| 16000070 | The extension cannot start the service. | +| 16000083 | The ExtensionAbility cannot start the ability due to system control. | +| 16200001 | The caller has been released. | + +**示例：** + +```ts +import { SelectionExtensionAbility, BusinessError } from '@kit.BasicServicesKit'; +import { rpc } from '@kit.IPCKit'; +import { Want } from '@kit.AbilityKit'; + +class SelectionAbilityStub extends rpc.RemoteObject { + constructor(des) { + if (typeof des === 'string') { + super(des); + } else { + return null; + } + } + onRemoteMessageRequest( + code: number, + data: rpc.MessageSequence, + reply: rpc.MessageSequence, + options: rpc.MessageOption + ): boolean | Promise { + console.error(`onRemoteMessageRequest error: ${error.code} ${error.message}`); + return true; + } +} + +class SelectionExtAbility extends SelectionExtensionAbility { + onConnect(want: Want): rpc.RemoteObject { + try { + let wantAbility: Want = { + bundleName: "com.selection.selectionapplication", + abilityName: "EntryAbility", + }; + this.context.startAbility(wantAbility).then(() => { + console.info(`startAbility success`); + }).catch((err: BusinessError) => { + let error = err as BusinessError; + console.error(`startAbility error: ${error.code} ${error.message}`); + }) + } catch (err) { + let error = err as BusinessError; + console.error(`startAbility error: ${error.code} ${error.message}`); + } + return new SelectionAbilityStub('remote'); + } +} +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis-basic-services-kit/js-apis-selectionInput-selectionManager.md b/zh-cn/application-dev/reference/apis-basic-services-kit/js-apis-selectionInput-selectionManager.md new file mode 100644 index 0000000000000000000000000000000000000000..3a2d5551f02c6edbb892f8e097ba25e654199c5c --- /dev/null +++ b/zh-cn/application-dev/reference/apis-basic-services-kit/js-apis-selectionInput-selectionManager.md @@ -0,0 +1,550 @@ +# @ohos.selectionInput.selectionManager (划词管理) + +本模块面向第三方应用，为三方应用提供划词管理能力，包括：创建窗口、显示窗口、移动窗口、隐藏窗口、销毁窗口、监听鼠标划词事件、获取选中文本等。 + +> **说明：** +> +> 本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## 导入模块 + +```ts +import { selectionManager } from '@kit.BasicServicesKit'; +``` + +## + +## on('selectionCompleted') + +on(type: 'selectionCompleted', callback: Callback\): void + +订阅划词完成事件，使用callback异步回调。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | ---------------------------------------------- | +| type | string | 是 | 设置监听类型，固定取值为'selectionCompleted'。 | +| callback | Callback\<[SelectionInfo](#selectioninfo)> | 是 | 回调函数，返回当前划词信息。 | + +**错误码：** + +以下错误码的详细介绍请参见[划词服务错误码](errorcode-selection.md)。 + +| 错误码ID | 错误信息 | +| ---------- | ----------------------------- | +| 33600003 | Invalid operation. The selection app is not valid. | + +**示例：** + +```ts +import { selectionManager } from '@kit.BasicServicesKit'; + +try { + selectionManager.on('selectionCompleted', (info: selectionManager.SelectionInfo) => { + console.info(`SelectionInfo text: ${info.text}`); + }); +} catch (err) { + console.error(`Failed to register selectionCompleted callback: ${JSON.stringify(err)}`); +} +``` + +## off('selectionCompleted') + +off(type: 'selectionCompleted', callback?: Callback\): void + +取消订阅划词完成事件。使用callback异步回调。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 设置监听类型，固定取值为'selectionCompleted'。 | +| callback | Callback\<[SelectionInfo](#selectioninfo)> | 否 | 取消订阅的回调函数。参数不填写时，取消订阅type对应的所有回调事件。 | + +**示例：** + +```ts +import { selectionManager } from '@kit.BasicServicesKit'; + +let selectionChangeCallback = (selectionInfo: selectionManager.SelectionInfo) => { + console.info(`SelectionInfo text: ${info.text}`); +}; + +selectionManager.on('selectionCompleted', selectionChangeCallback); +try { + selectionManager.off('selectionCompleted', selectionChangeCallback); +} catch (err) { + console.error(`Failed to unregister selectionCompleted: ${JSON.stringify(err)}`); +} +``` + +## createPanel + +createPanel(ctx: Context, info: PanelInfo): Promise\ + +创建划词面板，仅支持带有划词功能的三方应用调用。使用Promise异步回调。 + +单个划词应用仅允许创建一个[主面板类型](./js-apis-selectionInput-selectionPanel.md)和一个[菜单面板类型](./js-apis-selectionInput-selectionPanel.md)的窗口。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ----------- | ---- | ------------------------ | +| ctx | [Context](../apis-ability-kit/js-apis-inner-application-context.md) | 是 | 当前划词面板依赖的上下文信息。 | +| info | [PanelInfo](./js-apis-selectionInput-selectionPanel.md) | 是 | 划词面板信息。 | + +**返回值：** +| 类型 | 说明 | +| ------- | ------------------------------------------------------------------ | +| Promise\<[Panel](#panel)> | Promise对象，返回当前创建的划词面板对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[划词服务错误码](errorcode-selection.md)。 + +| 错误码ID | 错误信息 | +| ---------- | ----------------------------- | +| 33600001 | Selection service exception. | +| 33600003 | Invalid operation. The selection app is not valid. | + +**示例：** + +```ts +import { selectionManager, panelInfo, PanelType, BusinessError } from '@kit.BasicServicesKit'; + +let panelInfo: PanelInfo = { + panelType: PanelType.MENU_PANEL, + x: 0, + y: 0, + width: 500, + height: 200 +} +selectionManager.createPanel(this.context, panelInfo) + .then((panel: selectionManager.Panel) => { + console.info('Succeed in creating panel.'); + }).catch((err: BusinessError) => { + console.error(`Failed to create panel: ${JSON.stringify(err)}`); + }); +``` + +## destroyPanel + +destroyPanel(panel: Panel): Promise\ + +销毁划词面板。使用Promise异步回调。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------| ----------- | ---- | ------------------------ | +| panel | [Panel](#panel) | 是 | 要销毁的面板对象。 | + +**返回值：** +| 类型 | 说明 | +| ------- | -------------------------------------------------------------------- | +| Promise\ | Promise对象，无返回结果。| + +**错误码：** + +以下错误码的详细介绍请参见[划词服务错误码](errorcode-selection.md)。 + +| 错误码ID | 错误信息 | +| ---------- | ----------------------------- | +| 33600001 | Selection service exception. | + +**示例：** + +```ts +import { selectionManager, panelInfo, PanelType, BusinessError } from '@kit.BasicServicesKit'; + +let panelInfo: PanelInfo = { + panelType: PanelType.MENU_PANEL, + x: 0, + y: 0, + width: 500, + height: 200 +} +let selectionPanel: selectionManager.Panel | undefined = undefined; + +selectionManager.createPanel(this.context, panelInfo) + .then((panel: selectionManager.Panel) => { + console.info('Succeed in creating panel.'); + selectionPanel = panel; + try { + if (selectionPanel) { + selectionManager.destroyPanel(selectionPanel).then(() => { + console.info('Succeed in destroying panel.'); + }).catch((err: BusinessError) => { + console.error(`Failed to destroy panel: ${JSON.stringify(err)}`); + }); + } + } catch (err) { + console.error(`Failed to destroy panel: ${JSON.stringify(err)}`); + } + }).catch((err: BusinessError) => { + console.error(`Failed to create panel: ${JSON.stringify(err)}`); + }); +``` + +## SelectionInfo + +划词事件信息。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| --------- | -------- | ---- | ---- | ------------ | +| text | string | 否 | 否 | 划词文本。 | +| selectionType | [SelectionType](#selectiontype) | 否 | 否 | 触发划词类型。 | +| startDisplayX | number | 否 | 否 | 划词起始位置的屏幕x轴坐标。 | +| startDisplayY | number | 否 | 否 | 划词起始位置的屏幕y轴坐标。 | +| endDisplayX | number | 否 | 否 | 划词结束位置的屏幕x轴坐标。 | +| endDisplayY | number | 否 | 否 | 划词结束位置的屏幕y轴坐标。 | +| startWindowX | number | 否 | 否 | 划词起始位置的窗口x轴坐标。 | +| startWindowY | number | 否 | 否 | 划词起始位置的窗口y轴坐标。 | +| endWindowX | number | 否 | 否 | 划词结束位置的窗口x轴坐标。 | +| endWindowY | number | 否 | 否 | 划词结束位置的窗口y轴坐标。 | +| displayID | number | 否 | 否 | 被划词应用窗口的屏幕ID。 | +| windowID | number | 否 | 否 | 被划词应用的窗口ID。 | +| bundleName | string | 否 | 否 | 划词应用的bundleName。 | + +## Panel + +下列API均需使用[createPanel](#createpanel)获取到Panel实例后，通过实例调用。 + +### setUiContent + +setUiContent(path: string): Promise\ + +为当前的划词面板加载具体页面内容。使用Promise异步回调。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | -------- | +| path | string | 是 | 具体页面的路径。 | + +**返回值：** + +| 类型 | 说明 | +| ------- | ------------------------------ | +| Promise\ | Promise对象，无返回结果。 | + +**错误码：** + +以下错误码的详细介绍请参见[划词服务错误码](errorcode-selection.md)。 + +| 错误码ID | 错误信息 | +| ---------- | ----------------------------- | +| 33600001 | Selection service exception. | +| 33600002 | This selection window has been destroyed. | + +**示例：** + +```ts +import { selectionManager, BusinessError } from '@kit.BasicServicesKit'; + +try { + selectionPanel.setUiContent('pages/Index').then(() => { + console.info('Succeeded in setting the content.'); + }).catch((err: BusinessError) => { + console.error(`Failed to setUiContent: ${JSON.stringify(err)}`); + }); +} catch (err) { + console.error(`Failed to setUiContent: ${JSON.stringify(err)}`); +} +``` + +### show + +show(): Promise\ + +显示划词面板，使用Promise异步回调。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**返回值：** + +| 类型 | 说明 | +| ------- | ------------------------------ | +| Promise\ | Promise对象，无返回结果。 | + +**错误码：** + +以下错误码的详细介绍请参见[划词服务错误码](errorcode-selection.md)。 + +| 错误码ID | 错误信息 | +| ---------- | ----------------------------- | +| 33600001 | Selection service exception. | +| 33600002 | This selection window has been destroyed. | + +**示例：** + +```ts +import { selectionManager, BusinessError } from '@kit.BasicServicesKit'; + +selectionPanel.show().then(() => { + console.info('Succeeded in showing the panel.'); +}).catch((err: BusinessError) => { + console.error(`Failed to show panel: ${JSON.stringify(err)}`); +}); +``` + +### hide + +hide(): Promise\ + +隐藏当前划词面板，使用promise异步回调。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**返回值：** + +| 类型 | 说明 | +| ------- | ------------------------------ | +| Promise\ | Promise对象，无返回结果。 | + +**错误码：** + +以下错误码的详细介绍请参见[划词服务错误码](errorcode-selection.md)。 + +| 错误码ID | 错误信息 | +| ---------- | ----------------------------- | +| 33600001 | Selection service exception. | +| 33600002 | This selection window has been destroyed. | + +**示例：** + +```ts +import { selectionManager, BusinessError } from '@kit.BasicServicesKit'; + +selectionPanel.hide().then(() => { + console.info('Succeeded in hiding the panel.'); +}).catch((err: BusinessError) => { + console.error(`Failed to hide panel: ${JSON.stringify(err)}`); +}); +``` + +### startMoving + +startMoving(): Promise\ + +移动划词面板，使用Promise异步回调。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**返回值：** + +| 类型 | 说明 | +| ------- | ------------------------------ | +| Promise\ | Promise对象，无返回结果。 | + +**错误码：** + +以下错误码的详细介绍请参见[划词服务错误码](errorcode-selection.md)。 + +| 错误码ID | 错误信息 | +| ---------- | ----------------------------- | +| 33600001 | Selection service exception. | +| 33600002 | This selection window has been destroyed. | + +**示例：** + +```ts +import { selectionManager, BusinessError } from '@kit.BasicServicesKit'; + +RelativeContainer() { +} +.onTouch((event: TouchEvent) => { + if (event.type === TouchType.Down) { + if (selectionPanel !== undefined) { + selectionPanel.startMoving().then(() => { + console.info('Succeeded in startMoving the panel.'); + }).catch((err: BusinessError) => { + console.error(`Failed to startMoving panel: ${JSON.stringify(err)}`); + }); + } + } +}) +``` + +### moveTo + +moveTo(x: number, y: number): Promise\ + +移动划词面板至屏幕指定位置，使用Promise异步回调。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------- | ---- | -------- | +| x | number | 是 |x轴方向移动的值，单位为px。| +| y | number | 是 |y轴方向移动的值，单位为px。| + +**返回值：** + +| 类型 | 说明 | +| ------- | ------------------------------ | +| Promise\ | Promise对象，无返回结果。 | + +**错误码：** + +以下错误码的详细介绍请参见[划词服务错误码](errorcode-selection.md)。 + +| 错误码ID | 错误信息 | +| ---------- | ----------------------------- | +| 33600001 | Selection service exception. | +| 33600002 | This selection window has been destroyed. | + +**示例：** + +```ts +import { selectionManager, BusinessError } from '@kit.BasicServicesKit'; + +try { + selectionPanel.moveTo(200, 200).then(() => { + console.info('Succeeded in moving the panel.'); + }).catch((err: BusinessError) => { + console.error(`Failed to move panel: ${JSON.stringify(err)}`); + }); +} catch (err) { + console.error(`Failed to move panel: ${JSON.stringify(err)}`); +} +``` + +### on('destroyed') + +on(type: 'destroyed', callback: Callback\): void + +订阅划词窗口销毁事件。使用callback异步回调。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | ---------------------------------------------- | +| type | string | 是 | 设置监听类型，固定取值为'destroyed'。 | +| callback | Callback\ | 是 | 回调函数。 | + +**示例：** + +```ts +import { selectionManager, BusinessError } from '@kit.BasicServicesKit'; + +try { + selectionPanel.on('destroyed', () => { + console.info('Panel has destroyed.'); + }); +} catch (err) { + console.error(`Failed to register destroyed callback: ${JSON.stringify(err)}`); +} +``` + +### off('destroyed') + +off(type: 'destroyed', callback?: Callback\): void + +取消订阅划词窗口销毁事件。使用callback异步回调。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 设置监听类型，固定取值为'destroyed'。 | +| callback | Callback\ | 否 | 取消订阅的回调函数。参数不填写时，取消订阅type对应的所有回调事件。| + +**示例：** + +```ts +import { selectionManager, BusinessError } from '@kit.BasicServicesKit'; + +try { + selectionPanel.off('destroyed'); +} catch (err) { + console.error(`Failed to unregister destroyed: ${JSON.stringify(err)}`); +} +``` + +### on('hidden') + +on(type: 'hidden', callback: Callback\): void + +订阅划词窗口隐藏事件。使用callback异步回调。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | ---------------------------------------------- | +| type | string | 是 | 设置监听类型，固定取值为'hidden'。 | +| callback | Callback\ | 是 | 回调函数，返回当前划词服务的信息。 | + +**示例：** + +```ts +import { selectionManager, BusinessError } from '@kit.BasicServicesKit'; + +try { + selectionPanel.on('hidden', () => { + console.info('Panel has hidden.'); + }); +} catch (err) { + console.error(`Failed to register hidden callback: ${JSON.stringify(err)}`); +} +``` + +### off('hidden') + +off(type: 'hidden', callback?: Callback\): void + +取消订阅划词窗口隐藏事件。使用callback异步回调。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 设置监听类型，固定取值为'hidden'。 | +| callback | Callback\ | 否 | 取消订阅的回调函数。参数不填写时，取消订阅type对应的所有回调事件。 | + +**示例：** + +```ts +import { selectionManager, BusinessError } from '@kit.BasicServicesKit'; + +try { + selectionPanel.off('hidden'); +} catch (err) { + console.error(`Failed to unregister hidden: ${JSON.stringify(err)}`); +} +``` + +## SelectionType + +定义触发划词的类型枚举。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +| 名称 | 值 | 说明 | +| ------------ | -- | ------------------ | +| MOUSE_MOVE | 1 | 滑动选词类型。 | +| DOUBLE_CLICK | 2 | 双击选词类型。 | +| TRIPLE_CLICK | 3 | 三击选词类型。 | diff --git a/zh-cn/application-dev/reference/apis-basic-services-kit/js-apis-selectionInput-selectionPanel.md b/zh-cn/application-dev/reference/apis-basic-services-kit/js-apis-selectionInput-selectionPanel.md new file mode 100644 index 0000000000000000000000000000000000000000..056ae997aa6ddce4257779782cc71bfc81740169 --- /dev/null +++ b/zh-cn/application-dev/reference/apis-basic-services-kit/js-apis-selectionInput-selectionPanel.md @@ -0,0 +1,38 @@ +# @ohos.selectionInput.SelectionPanel (划词面板) + +本模块提供划词面板的属性信息和类型。 + +> **说明：** +> +>本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 + +## 导入模块 + +```ts +import { PanelInfo, PanelType } from '@kit.BasicServicesKit'; +``` + +## PanelInfo + +划词面板属性信息。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +| 名称 | 类型 | 只读 | 可选 | 说明 | +| --------- | -------- | -------- | -------- | -------- | +| panelType | [PanelType](#paneltype) | 否 | 否 | 划词面板类型。 | +| x | number | 否 | 否 | 划词面板左上角的x轴坐标。 | +| y | number | 否 | 否 | 划词面板左上角的y轴坐标。 | +| width | number | 否 | 否 | 划词面板宽度。 | +| height | number | 否 | 否 | 划词面板高度。 | + +## PanelType + +划词面板类型枚举。 + +**系统能力：** SystemCapability.SelectionInput.Selection + +| 名称 | 值 | 说明 | +| ------------- | ---- | ------------ | +| MENU_PANEL | 1 | 菜单面板类型。 | +| MAIN_PANEL | 2 | 主面板类型。 | diff --git a/zh-cn/application-dev/website.md b/zh-cn/application-dev/website.md index e51c534b3cb5e808dc3b876a4f3a801e0d67213e..412fb6b341eb1129bba833801393c133ae9bebdd 100644 --- a/zh-cn/application-dev/website.md +++ b/zh-cn/application-dev/website.md @@ -1316,6 +1316,9 @@ - [应用文件上传下载](basic-services/request/app-file-upload-download.md) - 压缩与解压 - [压缩与解压](basic-services/compress/deflate-and-inflate.md) + - 划词服务 + - [划词服务概述](basic-services/selectionIput/selection-services-intro.md) + - [实现一个划词应用](basic-services/selectionIput/selection-services-application-guide.md) - Function Flow Runtime Kit（任务并发调度服务） - [Function Flow Runtime Kit概述](ffrt/ffrt-overview.md) - [Function Flow Runtime并发范式](ffrt/ffrt-concurrency-paradigm.md) @@ -4015,6 +4018,10 @@ - [@ohos.print (打印)(系统接口)](reference/apis-basic-services-kit/js-apis-print-sys.md) - [@ohos.request (上传下载)(系统接口)](reference/apis-basic-services-kit/js-apis-request-sys.md) + - [@ohos.selectionInput.SelectionExtensionAbility (划词扩展能力)](reference/apis-basic-services-kit/js-apis-selectionInput-selectionExtensionAbility.md) + - [@ohos.selectionInput.SelectionExtensionContext (划词扩展上下文)](reference/apis-basic-services-kit/js-apis-selectionInput-selectionExtensionContext.md) + - [@ohos.selectionInput.selectionManager (划词管理)](reference/apis-basic-services-kit/js-apis-selectionInput-selectionManager.md) + - [@ohos.selectionInput.SelectionPanel (划词面板)](reference/apis-basic-services-kit/js-apis-selectionInput-selectionPanel.md) - 进程线程通信 - [系统定义的公共事件](reference/apis-basic-services-kit/common_event/commonEventManager-definitions.md) @@ -4126,6 +4133,7 @@ - [智能语音错误码](reference/apis-basic-services-kit/errorcode-intelligentVoice.md) - [设置数据项错误码](reference/apis-basic-services-kit/errorcode-settings.md) + - [划词服务错误码](reference/apis-basic-services-kit/errorcode-selection.md) - Function Flow Runtime Kit（任务并发调度服务） - C API - 模块