!14787 【monthly】新增FormComponent文档说明

Merge pull request !14787 from wangchensu/cherry-pick-1676596970

zh-cn/application-dev/reference/arkui-ts/Readme-CN.md

@@ -60,6 +60,7 @@
   - [DataPanel](ts-basic-components-datapanel.md)
   - [DatePicker](ts-basic-components-datepicker.md)
   - [Divider](ts-basic-components-divider.md)
+  - [Formcomponent](ts-basic-components-formcomponent.md)
   - [Gauge](ts-basic-components-gauge.md)
   - [Image](ts-basic-components-image.md)
   - [ImageAnimator](ts-basic-components-imageanimator.md)

zh-cn/application-dev/reference/arkui-ts/ts-basic-components-formcomponent.md

+# FormComponent
+
+提供卡片组件，实现卡片的显示功能。
+
+>  **说明：**
+>
+> - 该组件从API Version 7开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。
+>
+> - 该组件为卡片组件的使用方，对应提供方的使用参考文档[JS服务卡片UI组件](../js-service-widget-ui/Readme-CN.md)。
+> 
+> - 该组件使用需要具有系统签名。
+
+## 权限
+
+ohos.permission.GET_BUNDLE_INFO
+
+ohos.permission.GET_BUNDLE_INFO_PRIVILEGED
+
+ohos.permission.REQUIRE_FORM
+
+
+## 子组件
+
+无
+
+
+## 接口
+
+FormComponent(value: {
+    id: number;
+    name: string;
+    bundle: string;
+    ability: string;
+    module: string;
+    dimension?: FormDimension;
+    temporary?: boolean
+  })
+
+创建卡片组件，用于显示提供的卡片。
+
+**参数：**
+
+| 参数名    | 参数类型                        | 必填 | 参数描述                                                                |
+| --------- | ------------------------------- | ---- | ----------------------------------------------------------------------- |
+| id        | number                          | 是   | 卡片标识（新建卡片填0）。                                               |
+| name      | string                          | 是   | 卡片名称。                                                              |
+| bundle    | string                          | 是   | 目标卡片包名。                                                          |
+| ability   | string                          | 是   | 目标卡片Ability名称。                                                   |
+| module    | string                          | 是   | 卡片模块名称。                                                          |
+| dimension | [FormDimension](#formdimension) | 否   | 卡片尺寸，支持2 * 2，4 * 4，4 * 2类型卡片。<br/>默认值：Dimension_2_2。 |
+| temporary | boolean                         | 否   | 卡片是否为临时卡片。                                                    |
+
+## FormDimension
+
+| 名称                       | 描述     |
+| -------------------------- | -------- |
+| Dimension_1_2              | 1*2 卡片 |
+| Dimension_2_2              | 2*2 卡片 |
+| Dimension_2_4              | 2*4 卡片 |
+| Dimension_4_4              | 4*4 卡片 |
+| Dimension_2_1<sup>9+</sup> | 2*1 卡片 |
+
+## 属性
+| 名称        | 参数类型                                                                                              | 必填 | 描述                                                                    |
+| ----------- | ----------------------------------------------------------------------------------------------------- | ---- | ----------------------------------------------------------------------- |
+| size        | {<br/>width?:&nbsp;[Length](ts-types.md#length),<br/>height?:&nbsp;[Length](ts-types.md#length)<br/>} | 是   | 设置高宽尺寸。                                                          |
+| moduleName  | string                                                                                                | 是   | 卡片模块名称。                                                          |
+| dimension   | [FormDimension](#formdimension)                                                                       | 否   | 卡片尺寸，支持2 * 2，4 * 4，4 * 2类型卡片。<br/>默认值：Dimension_2_2。 |
+| allowUpdate | boolean                                                                                               | 否   | 是否允许卡片更新。<br/>默认值：true。                                   |
+| visibility  | [Visibility](ts-appendix-enums.md#visibility)                                                         | 否   | 是否允许卡片可见。<br/>默认值：Visible。                                |
+
+
+
+## 事件
+
+| 名称                                                                                                                | 功能描述                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| onAcquired(callback:&nbsp;(info:&nbsp;{&nbsp;id:&nbsp;number&nbsp;})&nbsp;=&gt;&nbsp;void)                          | 获取到卡片后触发，返回卡片的id.                                                                                |
+| onError(callback:&nbsp;(info:&nbsp;{&nbsp;errcode:&nbsp;number,&nbsp;msg:&nbsp;string&nbsp;})&nbsp;=&gt;&nbsp;void) | 组件加载错误回调。<br/>errcode:&nbsp;错误码。<br/>msg:&nbsp;错误信息。                                         |
+| onRouter(callback:&nbsp;(info:&nbsp;any)&nbsp;=&gt;&nbsp;void)                                                      | 组件路由事件回调,返回[routerEvent](../js-service-widget-ui/js-service-widget-syntax-hml.md#事件绑定)中的信息。 |
+| onUninstall(callback:&nbsp;(info:&nbsp;{&nbsp;id:&nbsp;number&nbsp;})&nbsp;=&gt;&nbsp;void)                         | 组件卸载回调，返回卸载卡片的id.                                                                                |
+
+
+## 示例
+
+```ts
+//card.ets
+@Entry
+@Component
+struct CardExample {
+   @State formId:number = 0;
+  build() {
+    Column() {
+      Text('this is a card')
+        .fontSize(50)
+        .fontWeight(FontWeight.Bold)
+      FormComponent({
+        id:this.formId,
+        name:"Form1",
+        bundle:"com.example.cardexample",
+        ability:"FormAbility",
+        module:"entry",
+        dimension:FormDimension.Dimension_2_2,
+        temporary:false
+      })
+        .allowUpdate(true)
+        .size({width:360,height:360})
+        .visibility(Visibility.Visible)
+        .onAcquired((form)=>{
+          console.log(`form info : ${JSON.stringify(form)}`);
+          this.fomId = form.id;
+        })
+        .onError((err)=>{
+          console.log(`fail to add form, err: ${JSON.stringify(err)}`);
+        })
+
+    }
+    .width('100%')
+    .height('100%')
+  }
+}
+```
+
+![Form](figures/form.png)
\ No newline at end of file

zh-cn/application-dev/reference/arkui-ts/ts-components-summary.md

@@ -69,12 +69,6 @@
 - [Swiper](ts-container-swiper.md)
 
     滑块视图容器组件，提供子组件滑动轮播显示的能力。
-- [WaterFlow](ts-container-waterflow.md)
-
-    瀑布流容器组件，由“行”和“列”分割的单元格所组成，通过容器自身的排列规则，将不同大小的“项目”自上而下，如瀑布般紧密布局。
-- [FlowItem](ts-container-flowitem.md)
-
-    瀑布流组件WaterFlow的子组件，用来展示瀑布流具体item。
 
 
 ## 导航
@@ -287,4 +281,7 @@
     独立显示Ability的容器组件。
 - [RemoteWindow](ts-basic-components-remotewindow.md)
 
-    远程控制窗口组件，可以通过此组件控制应用窗口，提供启动退出过程中控件动画和应用窗口联动动画的能力。
\ No newline at end of file
+    远程控制窗口组件，可以通过此组件控制应用窗口，提供启动退出过程中控件动画和应用窗口联动动画的能力。
+- [Formcomponent](ts-basic-components-formcomponent.md)
+
+    提供卡片组件，实现卡片的显示功能。
\ No newline at end of file