!16670 球面、渐亮、像素扩展接口文档

Merge pull request !16670 from aryawang/329master

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

@@ -42,6 +42,9 @@
     - [背景模糊设置](ts-universal-attributes-backgroundBlurStyle.md)
     - [分布式迁移标识](ts-universal-attributes-restoreId.md)
     - [前景色设置](ts-universal-attributes-foreground-color.md)
+    - [图像球面效果设置](ts-universal-attributes-sphericalEffect.md)
+    - [图像渐亮效果设置](ts-universal-attributes-lightUpEffect.md)
+    - [图像像素扩展效果设置](ts-universal-attributes-pixelStretchEffect.md)
   - [文本通用属性](ts-universal-attributes-text-style.md)
   - 手势处理
     - [绑定手势方法](ts-gesture-settings.md)

zh-cn/application-dev/reference/arkui-ts/ts-types.md

@@ -224,3 +224,13 @@
 | ------------- | ---------------------- | ---------------------------------------- |
 | CustomBuilder | () => any | 该方法类型必须使用@Builder装饰器修饰。具体用法见[@Builder](../../quick-start/arkts-dynamic-ui-elememt-building.md#builder)。 |
 
+## PixelStretchEffectOptions<sup>10+</sup>
+
+像素扩展属性集合,用于描述像素扩展的信息。
+
+| 名称          | 类型     | 必填   | 说明         |
+| ----------- | ------ | ---- | ---------- |
+| left     | [Length](#length) | 否    | 组件图像左边沿扩展距离。 |
+| right    | [Length](#length) | 否    | 组件图像右边沿像素扩展距离。 |
+| top  | [Length](#length) | 否    | 组件图像上边沿像素扩展距离。 |
+| bottom | [Length](#length) | 否    | 组件图像下边沿像素扩展距离。 |
\ No newline at end of file

zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-lightUpEffect.md

+# 图像渐亮效果
+
+设置组件的图像渐亮效果。
+
+>  **说明：**
+>
+>  从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。此接口为系统接口。
+
+## 属性
+
+| 名称 | 参数类型 | 描述 |
+| -------- | -------- | -------- |
+| lightUpEffect | [number]&nbsp;| 设置组件图像亮起程度。<br>取值范围：[0,1]。<br>如果value等于0则图像为全黑，如果value等于1则图像为全亮效果。0到1之间数值越大，表示图像亮度越高。`value < 0` 或者 `value > 1`为异常情况，`value < 0`按0处理，`value > 1`按1处理。 |
+
+## 示例
+
+### 示例1
+```ts
+// xxx.ets
+@Entry
+@Component
+struct LightUpExample {
+  build() {
+    Stack() {
+      Text('This is the text content with letterSpacing 0.')
+        .letterSpacing(0)
+        .fontSize(12)
+        .border({ width: 1 })
+        .padding(10)
+        .width('50%')
+        .lightUpEffect(0.6)
+    }.alignContent(Alignment.Center).width("100%").height("100%")
+  }
+}
+
+```
+效果图如下：
+
+![textLightUp3](figures/textLightUp3.png)
+
+修改lightUpEffect参数值为0.2：
+
+![textLightUp2](figures/textLightUp2.png)
+
+去掉lightUpEffect的设置，效果如下：
+
+![textLightUp1](figures/textLightUp1.png)
+### 示例2
+
+```ts
+// xxx.ets
+@Entry
+@Component
+struct LightUpExample {
+  @State isLunar: boolean = false
+  private selectedDate: Date = new Date('2028-08-08')
+  build() {
+    Stack() {
+      DatePicker({
+        start: new Date('1970-1-1'),
+        end: new Date('2100-1-1'),
+        selected: this.selectedDate
+      })
+        .lunar(this.isLunar)
+        .onChange((value: DatePickerResult) => {
+          this.selectedDate.setFullYear(value.year, value.month, value.day)
+          console.info('select current date is: ' + JSON.stringify(value))
+        })
+        .lightUpEffect(0.6)
+
+    }.alignContent(Alignment.Center).width("100%").height("100%")
+  }
+}
+```
+
+![datePickerLightUp2](figures/datePickerLightUp2.png)
+
+去掉lightUpEffect的设置，效果如下：
+
+![datePickerLightUp1](figures/datePickerLightUp1.png)
\ No newline at end of file

zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-pixelStretchEffect.md

+# 图像边缘像素扩展效果
+
+设置组件的图像边缘像素扩展效果。
+
+>  **说明：**
+>
+>  从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。此接口为系统接口。
+
+## 属性
+
+| 名称 | 参数类型 | 描述 |
+| -------- | -------- | -------- |
+| pixelStretchEffect | [PixelStretchEffectOptions](ts-types.md#PixelStretchEffectOptions)&nbsp;| 设置组件的图像边缘像素扩展距离。<br>参数`options`包括上下左右四个方向的边缘像素扩展距离。<br>**说明：**<br>1、如果距离为正值，表示向外扩展，放大原来图像大小。上下左右四个方向分别用边缘像素填充，填充的距离即为设置的边缘扩展的距离。<br>2、如果距离为负值，表示内缩，但是最终图像大小不变。内缩方式：1、图像根据`options`的设置缩小，缩小大小为四个方向边缘扩展距离的绝对值。2、图像用边缘像素扩展到原来大小。<br>3、对`options`的输入约束：1、上下左右四个方向的扩展统一为非正值或者非负值。即四个边同时向外扩或者内缩，方向一致。2、所有方向的输入均为百分比或者具体值，不支持百分比和具体值混用。3、所有异常情况下，显示为{0，0，0，0}效果，即跟原图保持一致。|
+
+## 示例
+
+### 示例1
+
+```ts
+// xxx.ets
+@Entry
+@Component
+struct PixelStretchExample {
+  build() {
+    Stack() {
+      Text('This is the text content with letterSpacing 0.')
+        .letterSpacing(0)
+        .fontSize(12)
+        .border({ width: 1 })
+        .padding(10)
+        .width('50%')
+        .pixelStretchEffect({top:10,left:10,right:10,bottom:10 })
+    }.alignContent(Alignment.Center).width("100%").height("100%")
+  }
+}
+
+```
+效果图如下：
+
+![textPixelStretch1](figures/textPixelStretch1.png)
+
+去掉pixelStretchEffect的设置，原图效果如下：
+
+![textPixelStretch2](figures/textPixelStretch2.png)
+
+对比发现，如果边缘扩展距离设置为正值，图像向外扩展了边缘距离。
+
+### 示例2
+
+基于示例1，现在把边缘扩展距离改为非正值。
+
+```ts
+// xxx.ets
+@Entry
+@Component
+struct PixelStretchExample {
+  build() {
+    Stack() {
+      Text('This is the text content with letterSpacing 0.')
+        .letterSpacing(0)
+        .fontSize(12)
+        .border({ width: 1 })
+        .padding(10)
+        .width('50%')
+        .pixelStretchEffect({top:-10,left:-10,right:-10,bottom:-10 })
+    }.alignContent(Alignment.Center).width("100%").height("100%")
+  }
+}
+```
+效果图如下:
+
+![textPixelStretch3](figures/textPixelStretch3.png)
+
+跟原图对比发现，效果图分两步实现：<br>1、原图大小缩小，缩小后的大小为原图大小减去像素
+收缩的距离。例如，原图大小为`100*100`，设置了`pixelStretchEffect({top:-10,left:-10,
+right:-10,bottom:-10 })`，则缩小后的大小为`(100-10-10)*(100-10-10)`，即`80*80`。<br>2、使用边缘像素扩展，将图像扩展为原图大小。

zh-cn/application-dev/reference/arkui-ts/ts-universal-attributes-sphericalEffect.md

+# 图像球面效果
+
+设置组件的图像球面效果。
+
+>  **说明：**
+>
+>  从API Version 10开始支持。后续版本如有新增内容，则采用上角标单独标记该内容的起始版本。此接口为系统接口。
+
+## 属性
+
+| 名称 | 参数类型 | 描述 |
+| -------- | -------- | -------- |
+| sphericalEffect | [number]&nbsp;| 设置组件的图像球面化程度。<br>取值范围：[0,1]。<br>**说明：**<br>1、如果value等于0则图像保持原样，如果value等于1则图像为完全球面化效果。在0和1之间，数值越大，则球面化程度越高。<br>`value < 0 `或者` value > 1`为异常情况，`value < 0`按0处理，`value > 1`按1处理。<br> 2、如果组件的图像使用异步加载，则不支持球面效果。例如Image组件默认使用异步加载，如果要使用球面效果，就要设置`syncLoad`为`true`，但是这种做法不推荐。`backgroundImage`也是使用异步加载，所以如果设置了`backgroundImage`，不支持球面效果。<br>3、如果组件设置了阴影，不支持球面效果。|
+
+## 示例
+
+### 示例1
+```ts
+// xxx.ets
+@Entry
+@Component
+struct SphericalEffectExample {
+  build() {
+    Stack() {
+      TextInput({ placeholder: "请输入变化范围百分比（[0%,100%]）"})
+        .width('50%')
+        .height(35)
+        .type(InputType.Number)
+        .enterKeyType(EnterKeyType.Done)
+        .caretColor(Color.Red)
+        .placeholderColor(Color.Blue)
+        .placeholderFont({
+          size: 20,
+          style: FontStyle.Italic,
+          weight: FontWeight.Bold
+        })
+        .sphericalEffect(0.5)
+    }.alignContent(Alignment.Center).width("100%").height("100%")
+  }
+}
+
+```
+效果图如下：
+
+![textInputSpherical1](figures/textInputSpherical1.png)
+
+去掉sphericalEffect的设置，效果如下：
+
+![textInputSpherical2](figures/textInputSpherical2.png)
\ No newline at end of file