From 00d3c5c33e0ba81fcb5e168c89e7d10124a350ce Mon Sep 17 00:00:00 2001
From: yangzk <yangzhongkai@huawei.com>
Date: Fri, 12 Aug 2022 09:46:20 +0800
Subject: [PATCH] =?UTF-8?q?IssueNo:=20#I5LZIQ=20Description:=20=E5=8D=A1?=
 =?UTF-8?q?=E7=89=87router=E4=BA=8B=E4=BB=B6=E5=92=8Cmessage=E4=BA=8B?=
 =?UTF-8?q?=E4=BB=B6=E8=B5=84=E6=96=99=E8=A1=A5=E5=85=85=E8=AF=B4=E6=98=8E?=
 =?UTF-8?q?=20Sig:=20SIG=5FApplicationFramework=20Feature=20or=20Bugfix:?=
 =?UTF-8?q?=20Bugfix=20Binary=20Source:=20No?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change-Id: I33f96361b92a90779c07d3fce3a6a5d95b857977
Signed-off-by: yangzk <yangzhongkai@huawei.com>
---
 .../application-dev/ability/fa-formability.md | 56 +++++++++++++++-
 .../ability/stage-formextension.md            | 64 ++++++++++++++++++-
 2 files changed, 117 insertions(+), 3 deletions(-)

diff --git a/zh-cn/application-dev/ability/fa-formability.md b/zh-cn/application-dev/ability/fa-formability.md
index 16e2f63f0b..8b4504b521 100644
--- a/zh-cn/application-dev/ability/fa-formability.md
+++ b/zh-cn/application-dev/ability/fa-formability.md
@@ -333,7 +333,7 @@ onUpdate(formId) {
      "actions": {
        "routerEvent": {
          "action": "router",
-         "abilityName": "com.example.MyApplication.hmservice.FormAbility",
+         "abilityName": "com.example.entry.MainAbility",
          "params": {
            "message": "add detail"
          }
@@ -346,6 +346,60 @@ onUpdate(formId) {
 
 ![fa-form-example](figures/fa-form-example.png)
 
+### 开发卡片事件
+
+卡片支持为组件设置action，包括router事件和message事件，其中router事件用于Ability跳转，message事件用于卡片开发人员自定义点击事件。关键步骤说明如下：
+
+1. 在hml中为组件设置onclick属性，其值对应到json文件的actions字段中。
+2. 若设置router事件，则
+   - action属性值为"router"；
+   - abilityName为跳转目标的Ability名，如目前DevEco创建的FA模型的MainAbility默认名为com.example.entry.MainAbility；
+   - params为跳转目标Ability的自定义参数，可以按需填写。其值可以在目标Ability启动时的want中的parameters里获取。如FA模型MainAbility的onCreate生命周期里可以通过featureAbility.getWant()获取到want，然后在其parameters字段下获取到配置的参数；
+3. 若设置message事件，则
+   - action属性值为"message"；
+   - params为message事件的用户自定义参数，可以按需填写。其值可以在卡片生命周期函数onEvent中的message里获取；
+
+示例如下：
+
+   - hml:
+   ```html
+   <div class="container">
+       <stack>
+           <div class="container-img">
+               <image src="/common/widget.png" class="bg-img"></image>
+           </div>
+           <div class="container-inner">
+               <text class="title" onclick="routerEvent">{{title}}</text>
+               <text class="detail_text" onclick="messageEvent">{{detail}}</text>
+           </div>
+       </stack>
+   </div>
+   ```
+
+   - json:
+   ```json
+   {
+     "data": {
+       "title": "TitleDefault",
+       "detail": "TextDefault"
+     },
+     "actions": {
+       "routerEvent": {
+         "action": "router",
+         "abilityName": "com.example.entry.MainAbility",
+         "params": {
+           "message": "add detail"
+         }
+       },
+       "messageEvent": {
+         "action": "message",
+         "params": {
+           "message": "add detail"
+         }
+       }
+     }
+   }
+   ```
 ## 相关实例
 
 针对FA模型卡片提供方的开发，有以下相关实例可供参考：
diff --git a/zh-cn/application-dev/ability/stage-formextension.md b/zh-cn/application-dev/ability/stage-formextension.md
index 1360cdf213..9f72cb5546 100644
--- a/zh-cn/application-dev/ability/stage-formextension.md
+++ b/zh-cn/application-dev/ability/stage-formextension.md
@@ -344,7 +344,7 @@ onUpdate(formId) {
      "actions": {
        "routerEvent": {
          "action": "router",
-         "abilityName": "com.example.MyApplication.hmservice.FormAbility",
+         "abilityName": "MainAbility",
          "params": {
            "message": "add detail"
          }
@@ -353,6 +353,66 @@ onUpdate(formId) {
    }
    ```
 
-最终可以得到，如下卡片：
+最终可以得到如下卡片：
 
 ![fa-form-example](figures/fa-form-example.png)
+
+### 开发卡片事件
+
+卡片支持为组件设置action，包括router事件和message事件，其中router事件用于Ability跳转，message事件用于卡片开发人员自定义点击事件。关键步骤说明如下：
+
+1. 在hml中为组件设置onclick属性，其值对应到json文件的actions字段中。
+2. 若设置router事件，则
+   - action属性值为"router"；
+   - abilityName为跳转目标的Ability名，如目前DevEco创建的Stage模型的MainAbility默认名为MainAbility；
+   - params为跳转目标Ability的自定义参数，可以按需填写。其值可以在目标Ability启动时的want中的parameters里获取。如Stage模型MainAbility的onCreate生命周期里的入参want的parameters字段下获取到配置的参数；
+3. 若设置message事件，则
+   - action属性值为"message"；
+   - params为message事件的用户自定义参数，可以按需填写。其值可以在卡片生命周期函数onEvent中的message里获取；
+
+示例如下：
+
+   - hml:
+   ```html
+   <div class="container">
+       <stack>
+           <div class="container-img">
+               <image src="/common/widget.png" class="bg-img"></image>
+           </div>
+           <div class="container-inner">
+               <text class="title" onclick="routerEvent">{{title}}</text>
+               <text class="detail_text" onclick="messageEvent">{{detail}}</text>
+           </div>
+       </stack>
+   </div>
+   ```
+
+   - json:
+   ```json
+   {
+     "data": {
+       "title": "TitleDefault",
+       "detail": "TextDefault"
+     },
+     "actions": {
+       "routerEvent": {
+         "action": "router",
+         "abilityName": "MainAbility",
+         "params": {
+           "message": "add detail"
+         }
+       },
+       "messageEvent": {
+         "action": "message",
+         "params": {
+           "message": "add detail"
+         }
+       }
+     }
+   }
+   ```
+## 相关实例
+
+针对Stage模型卡片提供方的开发，有以下相关实例可供参考：
+- [`FormExtAbility`：Stage模型卡片（eTS JS）（API9）](https://gitee.com/openharmony/app_samples/tree/master/ability/FormExtAbility)
+
-- 
GitLab