• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Class (PathEffect)
2
3<!--Kit: ArkGraphics 2D-->
4<!--Subsystem: Graphics-->
5<!--Owner: @hangmengxin-->
6<!--Designer: @wangyanglan-->
7<!--Tester: @nobuggers-->
8<!--Adviser: @ge-yafang-->
9
10> **说明：**
11>
12> - 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
13>
14> - 本Class首批接口从API version 12开始支持。
15>
16> - 本模块使用屏幕物理像素单位px。
17>
18> - 本模块为单线程模型策略，需要调用方自行管理线程安全和上下文状态的切换。
19
20路径效果对象。
21
22## 导入模块
23
24```ts
25import { drawing } from '@kit.ArkGraphics2D';
26```
27
28## createDashPathEffect<sup>12+</sup>
29
30static createDashPathEffect(intervals:  Array\<number>, phase: number): PathEffect
31
32创建将路径变为虚线的路径效果对象。
33
34**系统能力：** SystemCapability.Graphics.Drawing
35
36**参数：**
37
38| 参数名     | 类型           | 必填    | 说明                                               |
39| ---------- | ------------- | ------- | -------------------------------------------------- |
40| intervals  | Array\<number> | 是      | 表示虚线的ON（实线部分）和OFF（空白部分）长度的数组，数组个数必须是偶数，且>=2，该参数为正整数。|
41| phase      | number         | 是      | 绘制时的偏移量，该参数为浮点数。                                     |
42
43**返回值：**
44
45| 类型                      | 说明                   |
46| ------------------------- | --------------------- |
47| [PathEffect](arkts-apis-graphics-drawing-PathEffect.md) | 返回创建的路径效果对象。 |
48
49**错误码：**
50
51以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
52
53| 错误码ID | 错误信息 |
54| ------- | --------------------------------------------|
55| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. |
56
57**示例：**
58
59```ts
60import { RenderNode } from '@kit.ArkUI';
61import { common2D, drawing } from '@kit.ArkGraphics2D';
62
63class DrawingRenderNode extends RenderNode {
64  draw(context : DrawContext) {
65    const canvas = context.canvas;
66    let intervals = [10, 5];
67    let effect = drawing.PathEffect.createDashPathEffect(intervals, 5);
68  }
69}
70```
71
72## createPathDashEffect<sup>18+</sup>
73
74static createPathDashEffect(path: Path, advance: number, phase: number, style: PathDashStyle): PathEffect
75
76通过路径描述的形状创建一个虚线路径效果。
77
78**系统能力：** SystemCapability.Graphics.Drawing
79
80**参数：**
81
82| 参数名     | 类型           | 必填    | 说明                                               |
83| ---------- | ------------- | ------- | -------------------------------------------------- |
84| path  | [Path](arkts-apis-graphics-drawing-Path.md) | 是 | 通过该路径生成一个图形，用来填充每个虚线段。|
85| advance | number | 是 | 虚线段的步长，该参数为大于0的浮点数，否则会抛错误码。 |
86| phase | number | 是 | 表示虚线段内图形在虚线步长范围内的偏移量，该参数为浮点数，效果为先对偏移量取绝对值，然后对步长取模。 |
87| style | [PathDashStyle](arkts-apis-graphics-drawing-e.md#pathdashstyle18) | 是 | 指定虚线效果的样式。 |
88
89**返回值：**
90
91| 类型                      | 说明                   |
92| ------------------------- | --------------------- |
93| [PathEffect](arkts-apis-graphics-drawing-PathEffect.md) | 返回创建的路径效果对象。 |
94
95**错误码：**
96
97以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
98
99| 错误码ID | 错误信息 |
100| ------- | --------------------------------------------|
101| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3. Parameter verification failed. |
102
103**示例：**
104
105```ts
106import { RenderNode } from '@kit.ArkUI';
107import { common2D, drawing } from '@kit.ArkGraphics2D';
108
109class DrawingRenderNode extends RenderNode {
110  draw(context : DrawContext) {
111    const canvas = context.canvas;
112    let pen = new drawing.Pen();
113    const penColor: common2D.Color = { alpha: 255, red: 255, green: 0, blue: 0 }
114    pen.setColor(penColor);
115    pen.setStrokeWidth(10);
116    canvas.attachPen(pen);
117    pen.setAntiAlias(true);
118
119    const path = new drawing.Path();
120    path.moveTo(100, 100);
121    path.lineTo(150, 50);
122    path.lineTo(200, 100);
123
124    const path1 = new drawing.Path();
125    path1.moveTo(0, 0);
126    path1.lineTo(10, 0);
127    path1.lineTo(20, 10);
128    path1.lineTo(0,10);
129
130    let pathEffect1: drawing.PathEffect = drawing.PathEffect.createPathDashEffect(path1, 50, -30,
131        drawing.PathDashStyle.MORPH);
132    pen.setPathEffect(pathEffect1);
133
134    canvas.attachPen(pen);
135    canvas.drawPath(path);
136    canvas.detachPen();
137  }
138}
139```
140
141## createSumPathEffect<sup>18+</sup>
142
143static createSumPathEffect(firstPathEffect: PathEffect, secondPathEffect: PathEffect): PathEffect
144
145创建一个叠加的路径效果。与createComposePathEffect不同，此接口会分别对两个参数的效果各自独立进行表现，然后将两个效果简单重叠显示。
146
147**系统能力：** SystemCapability.Graphics.Drawing
148
149**参数：**
150
151| 参数名     | 类型           | 必填    | 说明                                               |
152| ---------- | ------------- | ------- | -------------------------------------------------- |
153| firstPathEffect | [PathEffect](arkts-apis-graphics-drawing-PathEffect.md) | 是 | 表示第一个路径效果。 |
154| secondPathEffect | [PathEffect](arkts-apis-graphics-drawing-PathEffect.md) | 是 | 表示第二个路径效果。 |
155
156**返回值：**
157
158| 类型                      | 说明                   |
159| ------------------------- | --------------------- |
160| [PathEffect](arkts-apis-graphics-drawing-PathEffect.md) | 返回创建的路径效果对象。 |
161
162**示例：**
163
164```ts
165import { RenderNode } from '@kit.ArkUI';
166import { drawing } from '@kit.ArkGraphics2D';
167
168class DrawingRenderNode extends RenderNode {
169  draw(context : DrawContext) {
170    const canvas = context.canvas;
171    let intervals = [10, 5];
172    let pathEffectOne = drawing.PathEffect.createDashPathEffect(intervals, 5);
173    let pathEffectTwo = drawing.PathEffect.createDashPathEffect(intervals, 10);
174    let effect = drawing.PathEffect.createSumPathEffect(pathEffectOne, pathEffectTwo);
175  }
176}
177```
178
179## createCornerPathEffect<sup>12+</sup>
180
181static createCornerPathEffect(radius: number): PathEffect
182
183创建将路径的夹角变成指定半径的圆角的路径效果对象。
184
185**系统能力：** SystemCapability.Graphics.Drawing
186
187**参数：**
188
189| 参数名     | 类型           | 必填    | 说明                                               |
190| ---------- | ------------- | ------- | -------------------------------------------------- |
191| radius     | number        | 是      | 圆角的半径，必须大于0，该参数为浮点数。                |
192
193**返回值：**
194
195| 类型                      | 说明                   |
196| ------------------------- | --------------------- |
197| [PathEffect](arkts-apis-graphics-drawing-PathEffect.md) | 返回创建的路径效果对象。 |
198
199**错误码：**
200
201以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。
202
203| 错误码ID | 错误信息 |
204| ------- | --------------------------------------------|
205| 401 | Parameter error.Possible causes:1.Mandatory parameters are left unspecified;2.Incorrect parameter types;3.Parameter verification failed. |
206
207**示例：**
208
209```ts
210import { RenderNode } from '@kit.ArkUI';
211import { drawing } from '@kit.ArkGraphics2D';
212
213class DrawingRenderNode extends RenderNode {
214  draw(context : DrawContext) {
215    const canvas = context.canvas;
216    let effect = drawing.PathEffect.createCornerPathEffect(30);
217  }
218}
219```
220
221## createDiscretePathEffect<sup>18+</sup>
222
223static createDiscretePathEffect(segLength: number, dev: number, seedAssist?: number): PathEffect
224
225创建一种将路径打散，并且在路径上产生不规则分布的效果。
226
227**系统能力：** SystemCapability.Graphics.Drawing
228
229**参数：**
230
231| 参数名     | 类型           | 必填    | 说明                                               |
232| ---------- | ------------- | ------- | -------------------------------------------------- |
233| segLength  | number        | 是      | 路径中每进行一次打散操作的长度，该长度为浮点数，负数和0时无效果。 |
234| dev        | number        | 是      | 绘制时的末端点的最大移动偏离量，该偏移量为浮点数。 |
235| seedAssist | number        | 否      | 生成效果伪随机种子辅助变量，默认值为0，该参数为32位无符号整数。 |
236
237**返回值：**
238
239| 类型                      | 说明                   |
240| ------------------------- | --------------------- |
241| [PathEffect](arkts-apis-graphics-drawing-PathEffect.md) | 返回创建的路径效果对象。 |
242
243**示例：**
244
245```ts
246import { RenderNode } from '@kit.ArkUI';
247import { drawing } from '@kit.ArkGraphics2D';
248
249class DrawingRenderNode extends RenderNode {
250  draw(context : DrawContext) {
251    const canvas = context.canvas;
252    let effect = drawing.PathEffect.createDiscretePathEffect(100, -50, 0);
253  }
254}
255```
256
257## createComposePathEffect<sup>18+</sup>
258
259static createComposePathEffect(outer: PathEffect, inner: PathEffect): PathEffect
260
261创建路径组合的路径效果对象，首先应用内部路径效果，然后应用外部路径效果。
262
263**系统能力：** SystemCapability.Graphics.Drawing
264
265**参数：**
266
267| 参数名 | 类型                        | 必填 | 说明                             |
268| ------ | --------------------------- | ---- | -------------------------------- |
269| outer  | [PathEffect](arkts-apis-graphics-drawing-PathEffect.md) | 是   | 组合路径效果中外部路径效果。 |
270| inner  | [PathEffect](arkts-apis-graphics-drawing-PathEffect.md) | 是   | 组合路径效果中内部路径效果。 |
271
272**返回值：**
273
274| 类型                      | 说明                   |
275| ------------------------- | --------------------- |
276| [PathEffect](arkts-apis-graphics-drawing-PathEffect.md) | 返回创建的路径效果对象。 |
277
278**示例：**
279
280```ts
281import { RenderNode } from '@kit.ArkUI';
282import { drawing } from '@kit.ArkGraphics2D';
283
284class DrawingRenderNode extends RenderNode {
285  draw(context : DrawContext) {
286    const canvas = context.canvas;
287    let pathEffect1 = drawing.PathEffect.createCornerPathEffect(100);
288    let pathEffect2 = drawing.PathEffect.createCornerPathEffect(10);
289    let effect = drawing.PathEffect.createComposePathEffect(pathEffect1, pathEffect2);
290  }
291}
292```