!18007 添加像素单位以及提升性能文档的描述

Merge pull request !18007 from 田雨/master

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

@@ -113,7 +113,7 @@ struct TextExample1 {
       Text('TextOverflow+maxLines').fontSize(9).fontColor(0xCCCCCC)
       // 超出maxLines截断内容展示
       Text('This is the setting of textOverflow to Clip text content This is the setting of textOverflow to None text content. This is the setting of textOverflow to Clip text content This is the setting of textOverflow to None text content.')
-        .textOverflow({ overflow: TextOverflow.None })
+        .textOverflow({ overflow: TextOverflow.Clip })
         .maxLines(1)
         .fontSize(12)
         .border({ width: 1 })

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

@@ -26,7 +26,7 @@ Video(value: {src?: string | Resource, currentProgressRate?: number | string | P
 | ------------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
 | src                 | string \| [Resource](ts-types.md)                            | 否   | 视频播放源的路径，支持本地视频路径和网络路径。<br>支持在resources下面的video或rawfile文件夹里放置媒体资源。<br>支持dataability://的路径前缀，用于访问通过Data Ability提供的视频路径，具体路径信息详见 [DataAbility说明](../../application-models/dataability-overview.md)。<br/>**说明：**<br/>视频支持的格式是：mp4、mkv、webm、TS。 |
 | currentProgressRate | number&nbsp;\|&nbsp;string&nbsp;\|&nbsp;PlaybackSpeed<sup>8+</sup> | 否   | 视频播放倍速。<br/>**说明：**<br/>number取值仅支持：0.75，1.0，1.25，1.75，2.0。<br/>默认值：1.0 \| PlaybackSpeed.Speed_Forward_1_00_X |
-| previewUri          | string&nbsp;\|PixelMap&nbsp;\|&nbsp;[Resource](ts-types.md)  | 否   | 视频未播放时的预览图片路径。（暂不支持PixelMap类型）         |
+| previewUri          | string&nbsp;\|PixelMap&nbsp;\|&nbsp;[Resource](ts-types.md)  | 否   | 视频未播放时的预览图片路径。                                 |
 | controller          | [VideoController](#videocontroller)                          | 否   | 设置视频控制器。                                             |
 
 ## PlaybackSpeed<sup>8+</sup>枚举说明

zh-cn/application-dev/reference/arkui-ts/ts-pixel-units.md

@@ -3,11 +3,11 @@
 为开发者提供4种像素单位，框架采用vp为基准数据单位。
 
 
-| 名称   | 描述                                       |
-| ---- | ---------------------------------------- |
-| px   | 屏幕物理像素单位。                                |
-| vp   | 屏幕密度相关像素，根据屏幕像素密度转换为屏幕物理像素，当数值不带单位时，默认单位vp。 |
-| fp   | 字体像素，与vp类似适用屏幕密度变化，随系统字体大小设置变化。          |
+| 名称 | 描述                                                         |
+| ---- | ------------------------------------------------------------ |
+| px   | 屏幕物理像素单位。                                           |
+| vp   | 屏幕密度相关像素，根据屏幕像素密度转换为屏幕物理像素，当数值不带单位时，默认单位vp。在实际宽度为1440物理像素的屏幕上，1vp约等于3px。 |
+| fp   | 字体像素，与vp类似适用屏幕密度变化，随系统字体大小设置变化。 |
 | lpx  | 视窗逻辑像素单位，lpx单位为实际屏幕宽度与逻辑宽度（通过designWidth配置）的比值，designWidth默认值为720。当designWidth为720时，在实际宽度为1440物理像素的屏幕上，1lpx为2px大小。 |
 
 
@@ -37,33 +37,71 @@ struct Example {
       Flex({ wrap: FlexWrap.Wrap }) {
         Column() {
           Text("width(220)")
-            .width(220).height(40).backgroundColor(0xF9CF93)
-            .textAlign(TextAlign.Center).fontColor(Color.White).fontSize('12vp')
+            .width(220)
+            .height(40)
+            .backgroundColor(0xF9CF93)
+            .textAlign(TextAlign.Center)
+            .fontColor(Color.White)
+            .fontSize('12vp')
         }.margin(5)
+
         Column() {
           Text("width('220px')")
-            .width('220px').height(40).backgroundColor(0xF9CF93)
-            .textAlign(TextAlign.Center).fontColor(Color.White)
+            .width('220px')
+            .height(40)
+            .backgroundColor(0xF9CF93)
+            .textAlign(TextAlign.Center)
+            .fontColor(Color.White)
         }.margin(5)
+
         Column() {
           Text("width('220vp')")
-            .width('220vp').height(40).backgroundColor(0xF9CF93)
-            .textAlign(TextAlign.Center).fontColor(Color.White).fontSize('12vp')
+            .width('220vp')
+            .height(40)
+            .backgroundColor(0xF9CF93)
+            .textAlign(TextAlign.Center)
+            .fontColor(Color.White)
+            .fontSize('12vp')
         }.margin(5)
+
         Column() {
           Text("width('220lpx') designWidth:720")
-            .width('220lpx').height(40).backgroundColor(0xF9CF93)
-            .textAlign(TextAlign.Center).fontColor(Color.White).fontSize('12vp')
+            .width('220lpx')
+            .height(40)
+            .backgroundColor(0xF9CF93)
+            .textAlign(TextAlign.Center)
+            .fontColor(Color.White)
+            .fontSize('12vp')
         }.margin(5)
+
         Column() {
           Text("width(vp2px(220) + 'px')")
-            .width(vp2px(220) + 'px').height(40).backgroundColor(0xF9CF93)
-            .textAlign(TextAlign.Center).fontColor(Color.White).fontSize('12vp')
+            .width(vp2px(220) + 'px')
+            .height(40)
+            .backgroundColor(0xF9CF93)
+            .textAlign(TextAlign.Center)
+            .fontColor(Color.White)
+            .fontSize('12vp')
         }.margin(5)
+
         Column() {
           Text("fontSize('12fp')")
-            .width(220).height(40).backgroundColor(0xF9CF93)
-            .textAlign(TextAlign.Center).fontColor(Color.White).fontSize('12fp')
+            .width(220)
+            .height(40)
+            .backgroundColor(0xF9CF93)
+            .textAlign(TextAlign.Center)
+            .fontColor(Color.White)
+            .fontSize('12fp')
+        }.margin(5)
+
+        Column() {
+          Text("width(px2vp(220))")
+            .width(px2vp(220))
+            .height(40)
+            .backgroundColor(0xF9CF93)
+            .textAlign(TextAlign.Center)
+            .fontColor(Color.White)
+            .fontSize('12fp')
         }.margin(5)
       }.width('100%')
     }

zh-cn/application-dev/ui/arkts-performance-improvement-recommendation.md

@@ -131,6 +131,226 @@ struct MyComponent {
 
 上述代码在页面加载时仅初始化加载三个列表元素，之后每点击一次列表元素，将增加一个列表元素。
 
+## 设置List组件的宽高
+
+在使用Scroll容器组件嵌套List组件加载长列表时，若不指定List的宽高尺寸，则默认全部加载。
+
+>  **说明：**
+>
+>  Scroll嵌套List时：
+>
+>  - List没有设置宽高，会布局List的所有子组件。
+>  
+>  - List设置宽高，会布局List显示区域内的子组件。
+>  
+>  - List使用[ForEach](../quick-start/arkts-rendering-control-foreach.md)加载子组件时，无论是否设置List的宽高，都会加载所有子组件。
+>  
+>  - List使用[LazyForEach](../quick-start/arkts-rendering-control-lazyforeach.md)加载子组件时，没有设置List的宽高，会加载所有子组件，设置了List的宽高，会加载List显示区域内的子组件。
+
+```ts
+class BasicDataSource implements IDataSource {
+  private listeners: DataChangeListener[] = []
+
+  public totalCount(): number {
+    return 0
+  }
+
+  public getData(index: number): any {
+    return undefined
+  }
+
+  registerDataChangeListener(listener: DataChangeListener): void {
+    if (this.listeners.indexOf(listener) < 0) {
+      console.info('add listener')
+      this.listeners.push(listener)
+    }
+  }
+
+  unregisterDataChangeListener(listener: DataChangeListener): void {
+    const pos = this.listeners.indexOf(listener);
+    if (pos >= 0) {
+      console.info('remove listener')
+      this.listeners.splice(pos, 1)
+    }
+  }
+
+  notifyDataReload(): void {
+    this.listeners.forEach(listener => {
+      listener.onDataReloaded()
+    })
+  }
+
+  notifyDataAdd(index: number): void {
+    this.listeners.forEach(listener => {
+      listener.onDataAdd(index)
+    })
+  }
+
+  notifyDataChange(index: number): void {
+    this.listeners.forEach(listener => {
+      listener.onDataChange(index)
+    })
+  }
+
+  notifyDataDelete(index: number): void {
+    this.listeners.forEach(listener => {
+      listener.onDataDelete(index)
+    })
+  }
+
+  notifyDataMove(from: number, to: number): void {
+    this.listeners.forEach(listener => {
+      listener.onDataMove(from, to)
+    })
+  }
+}
+
+class MyDataSource extends BasicDataSource {
+  private dataArray: Array<string> = new Array(100).fill('test')
+
+  public totalCount(): number {
+    return this.dataArray.length
+  }
+
+  public getData(index: number): any {
+    return this.dataArray[index]
+  }
+
+  public addData(index: number, data: string): void {
+    this.dataArray.splice(index, 0, data)
+    this.notifyDataAdd(index)
+  }
+
+  public pushData(data: string): void {
+    this.dataArray.push(data)
+    this.notifyDataAdd(this.dataArray.length - 1)
+  }
+}
+
+@Entry
+@Component
+struct MyComponent {
+  private data: MyDataSource = new MyDataSource()
+
+  build() {
+    Scroll() {
+      List() {
+        LazyForEach(this.data, (item: string, index: number) => {
+          ListItem() {
+            Row() {
+              Text('item value: ' + item + (index + 1)).fontSize(20).margin(10)
+            }
+          }
+        })
+      }
+    }
+  }
+}
+```
+
+因此，此场景下建议设置List子组件的宽高。
+
+```ts
+class BasicDataSource implements IDataSource {
+  private listeners: DataChangeListener[] = []
+
+  public totalCount(): number {
+    return 0
+  }
+
+  public getData(index: number): any {
+    return undefined
+  }
+
+  registerDataChangeListener(listener: DataChangeListener): void {
+    if (this.listeners.indexOf(listener) < 0) {
+      console.info('add listener')
+      this.listeners.push(listener)
+    }
+  }
+
+  unregisterDataChangeListener(listener: DataChangeListener): void {
+    const pos = this.listeners.indexOf(listener);
+    if (pos >= 0) {
+      console.info('remove listener')
+      this.listeners.splice(pos, 1)
+    }
+  }
+
+  notifyDataReload(): void {
+    this.listeners.forEach(listener => {
+      listener.onDataReloaded()
+    })
+  }
+
+  notifyDataAdd(index: number): void {
+    this.listeners.forEach(listener => {
+      listener.onDataAdd(index)
+    })
+  }
+
+  notifyDataChange(index: number): void {
+    this.listeners.forEach(listener => {
+      listener.onDataChange(index)
+    })
+  }
+
+  notifyDataDelete(index: number): void {
+    this.listeners.forEach(listener => {
+      listener.onDataDelete(index)
+    })
+  }
+
+  notifyDataMove(from: number, to: number): void {
+    this.listeners.forEach(listener => {
+      listener.onDataMove(from, to)
+    })
+  }
+}
+
+class MyDataSource extends BasicDataSource {
+  private dataArray: Array<string> = new Array(100).fill('test')
+
+  public totalCount(): number {
+    return this.dataArray.length
+  }
+
+  public getData(index: number): any {
+    return this.dataArray[index]
+  }
+
+  public addData(index: number, data: string): void {
+    this.dataArray.splice(index, 0, data)
+    this.notifyDataAdd(index)
+  }
+
+  public pushData(data: string): void {
+    this.dataArray.push(data)
+    this.notifyDataAdd(this.dataArray.length - 1)
+  }
+}
+
+@Entry
+@Component
+struct MyComponent {
+  private data: MyDataSource = new MyDataSource()
+
+  build() {
+    Scroll() {
+      List() {
+        LazyForEach(this.data, (item: string, index: number) => {
+          ListItem() {
+            Text('item value: ' + item + (index + 1)).fontSize(20).margin(10)
+          }.width('100%')
+        })
+      }.width('100%').height(500)
+    }.backgroundColor(Color.Pink)
+  }
+}
+```
+
+![list1](figures/list1.gif)
+
 ## 使用条件渲染替代显隐控制
 
 如下所示，开发者在使用visibility通用属性控制组件的显隐状态时，仍存在组件的重新创建过程，造成性能上的损耗。