• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.arkui.drawableDescriptor (DrawableDescriptor)
2
3本模块提供获取pixelMap的能力，包括前景、背景、蒙版和分层图标。
4
5> **说明：**
6>
7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 示例效果请以真机运行为准，当前DevEco Studio预览器不支持。
10
11## 导入模块
12
13```ts
14import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI';
15```
16
17## DrawableDescriptor
18
19支持传入png、jpg、bmp、svg、gif、webp、astc、sut格式的资源类型。
20
21### getPixelMap
22
23getPixelMap(): image.PixelMap
24
25获取pixelMap。
26
27**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
28
29**系统能力：** SystemCapability.ArkUI.ArkUI.Full
30
31**返回值：**
32
33| 类型                                       | 说明       |
34| ---------------------------------------- | -------- |
35| [image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md) | PixelMap |
36
37**示例：**
38  ```ts
39import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
40import { image } from '@kit.ImageKit'
41let resManager = this.getUIContext().getHostContext()?.resourceManager;
42// $r('app.media.app_icon')需要替换为开发者所需的图像资源文件。
43let pixmap: DrawableDescriptor = (resManager?.getDrawableDescriptor($r('app.media.icon')
44    .id)) as DrawableDescriptor; // 当传入资源id或name为普通图片时，生成DrawableDescriptor对象。
45let pixmapNew: image.PixelMap | undefined = pixmap?.getPixelMap();
46  ```
47
48## PixelMapDrawableDescriptor<sup>12+</sup>
49
50支持通过传入pixelMap创建PixelMapDrawableDescriptor对象。继承自[DrawableDescriptor](#drawabledescriptor)。
51
52### constructor<sup>12+</sup>
53
54constructor(src?: image.PixelMap)
55
56PixelMapDrawableDescriptor的构造函数。
57
58**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
59
60**系统能力：** SystemCapability.ArkUI.ArkUI.Full
61
62**参数：**
63
64| 参数名     | 类型              | 必填  | 说明                                       |
65| --------- | ---------------- | ---- | ------------------------------------------ |
66| src | [image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)  | 否 | PixelMap类型参数，存储 PixelMap 图片数据。 |
67
68
69## LayeredDrawableDescriptor
70
71当传入资源id或name为包含前景和背景资源的json文件时，生成LayeredDrawableDescriptor对象。继承自[DrawableDescriptor](#drawabledescriptor)。
72
73drawable.json位于项目工程entry/src/main/resources/base/media目录下。定义请参考：
74
75```json
76{
77  "layered-image":
78  {
79    "background" : "$media:background",
80    "foreground" : "$media:foreground"
81  }
82}
83```
84
85**示例：**
86
871. 使用json文件创建LayeredDrawableDescriptor。
88
89    ```ts
90    // xxx.ets
91    import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI';
92
93    @Entry
94    @Component
95    struct Index {
96      private resManager = this.getUIContext().getHostContext()?.resourceManager;
97      // $r('app.media.drawable')需要替换为开发者所需的图像资源文件。
98      private layeredDrawableDescriptor: DrawableDescriptor | undefined =
99        this.resManager?.getDrawableDescriptor($r('app.media.drawable').id);
100
101      build() {
102        Row() {
103          Column() {
104            Image((this.layeredDrawableDescriptor instanceof LayeredDrawableDescriptor) ?
105              this.layeredDrawableDescriptor : undefined)
106            Image((this.layeredDrawableDescriptor instanceof LayeredDrawableDescriptor) ?
107              this.layeredDrawableDescriptor?.getForeground()?.getPixelMap() : undefined)
108          }.height('50%')
109        }.width('50%')
110      }
111    }
112    ```
1132. 使用PixelMapDrawableDescriptor创建LayeredDrawableDescriptor。
114
115    ```ts
116    import { DrawableDescriptor, LayeredDrawableDescriptor, PixelMapDrawableDescriptor } from '@kit.ArkUI';
117    import { image } from '@kit.ImageKit';
118
119    @Entry
120    @Component
121    struct Index {
122      @State fore1: image.PixelMap | undefined = undefined;
123      @State back1: image.PixelMap | undefined = undefined;
124
125      @State foregroundDraw:DrawableDescriptor|undefined=undefined;
126      @State backgroundDraw:DrawableDescriptor|undefined=undefined;
127      @State maskDraw:DrawableDescriptor|undefined=undefined;
128      @State maskPixel: image.PixelMap | undefined = undefined;
129      @State draw : LayeredDrawableDescriptor | undefined = undefined;
130      async aboutToAppear() {
131        // $r('app.media.foreground')需要替换为开发者所需的图像资源文件。
132        this.fore1 = await this.getPixmapFromMedia($r('app.media.foreground'));
133        // $r('app.media.background')需要替换为开发者所需的图像资源文件。
134        this.back1 = await this.getPixmapFromMedia($r('app.media.background'));
135        // $r('app.media.ohos_icon_mask')需要替换为开发者所需的图像资源文件。
136        this.maskPixel = await this.getPixmapFromMedia($r('app.media.ohos_icon_mask'));
137        // 使用PixelMapDrawableDescriptor创建LayeredDrawableDescriptor
138        this.foregroundDraw = new PixelMapDrawableDescriptor(this.fore1);
139        this.backgroundDraw = new PixelMapDrawableDescriptor(this.back1);
140        this.maskDraw = new PixelMapDrawableDescriptor(this.maskPixel);
141
142        this.draw = new LayeredDrawableDescriptor(this.foregroundDraw,this.backgroundDraw,this.maskDraw);
143      }
144      build() {
145        Row() {
146          Column() {
147              Image(this.draw)
148                .width(300)
149                .height(300)
150          }.height('100%').justifyContent(FlexAlign.Center)
151        }.width('100%').height("100%").backgroundColor(Color.Pink)
152      }
153      // 根据资源，通过图片框架获取pixelMap
154      private async getPixmapFromMedia(resource: Resource) {
155        let unit8Array = await this.getUIContext().getHostContext()?.resourceManager?.getMediaContent(resource.id);
156        let imageSource = image.createImageSource(unit8Array?.buffer.slice(0, unit8Array.buffer.byteLength));
157        let createPixelMap: image.PixelMap = await imageSource.createPixelMap({
158          desiredPixelFormat: image.PixelMapFormat.BGRA_8888
159        });
160        await imageSource.release();
161        return createPixelMap;
162      }
163    }
164    ```
165
166### constructor<sup>12+</sup>
167
168constructor(foreground?: DrawableDescriptor, background?: DrawableDescriptor, mask?: DrawableDescriptor)
169
170LayeredDrawableDescriptor的构造函数。
171
172**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
173
174**系统能力：** SystemCapability.ArkUI.ArkUI.Full
175
176**参数：**
177
178| 参数名     | 类型              | 必填  | 说明                                       |
179| --------- | ---------------- | ---- | ------------------------------------------ |
180| foreground | [DrawableDescriptor](#drawabledescriptor)  | 否   | 分层图标的前景图片选项。 |
181| background   | [DrawableDescriptor](#drawabledescriptor) | 否   | 分层图标的背景图片选项。  |
182| mask | [DrawableDescriptor](#drawabledescriptor) | 否 | 分层图标的遮罩选项。 |
183
184### getForeground
185getForeground(): DrawableDescriptor
186
187获取前景的DrawableDescriptor对象。
188
189**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
190
191**系统能力：** SystemCapability.ArkUI.ArkUI.Full
192
193**返回值：**
194
195| 类型                                       | 说明                   |
196| ---------------------------------------- | -------------------- |
197| [DrawableDescriptor](#drawabledescriptor) | DrawableDescriptor对象。 |
198
199**示例：**
200  ```ts
201  import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI';
202
203  @Entry
204  @Component
205  struct Index {
206    @State drawableDescriptor: DrawableDescriptor | undefined = undefined;
207
208    private getForeground(): DrawableDescriptor | undefined {
209      let resManager = this.getUIContext().getHostContext()?.resourceManager;
210      // $r('app.media.drawable')需要替换为开发者所需的图像资源文件。
211      let drawable: DrawableDescriptor | undefined = resManager?.getDrawableDescriptor($r('app.media.drawable').id);
212      if (!drawable) {
213        return undefined;
214      }
215      if (drawable instanceof LayeredDrawableDescriptor) {
216        let layeredDrawableDescriptor = (drawable as LayeredDrawableDescriptor).getForeground();
217        return layeredDrawableDescriptor;
218      }
219      return undefined;
220    }
221
222    aboutToAppear(): void {
223      this.drawableDescriptor = this.getForeground();
224    }
225
226    build() {
227      RelativeContainer() {
228        if (this.drawableDescriptor) {
229          Image(this.drawableDescriptor)
230            .width(100)
231            .height(100)
232            .borderWidth(1)
233            .backgroundColor(Color.Green);
234        }
235      }
236      .height('100%')
237      .width('100%')
238    }
239  }
240  ```
241
242### getBackground
243
244getBackground(): DrawableDescriptor
245
246获取背景的DrawableDescriptor对象。
247
248**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
249
250**系统能力：** SystemCapability.ArkUI.ArkUI.Full
251
252**返回值：**
253
254| 类型                                       | 说明                   |
255| ---------------------------------------- | -------------------- |
256| [DrawableDescriptor](#drawabledescriptor) | DrawableDescriptor对象。 |
257
258**示例：**
259  ```ts
260  import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI';
261
262  @Entry
263  @Component
264  struct Index {
265    @State drawableDescriptor: DrawableDescriptor | undefined = undefined;
266
267    private getBackground(): DrawableDescriptor | undefined {
268      let resManager = this.getUIContext().getHostContext()?.resourceManager;
269      // $r('app.media.drawable')需要替换为开发者所需的图像资源文件。
270      let drawable: DrawableDescriptor | undefined = resManager?.getDrawableDescriptor($r('app.media.drawable').id);
271      if (!drawable) {
272        return undefined;
273      }
274      let layeredDrawableDescriptor = (drawable as LayeredDrawableDescriptor).getBackground();
275      return layeredDrawableDescriptor;
276    }
277
278    aboutToAppear(): void {
279      this.drawableDescriptor = this.getBackground();
280    }
281
282    build() {
283      RelativeContainer() {
284        if (this.drawableDescriptor) {
285          Image(this.drawableDescriptor)
286            .width(100)
287            .height(100)
288        }
289      }
290      .height('100%')
291      .width('100%')
292    }
293  }
294  ```
295
296### getMask
297
298getMask(): DrawableDescriptor
299
300获取蒙版的DrawableDescriptor对象。
301
302**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
303
304**系统能力：** SystemCapability.ArkUI.ArkUI.Full
305
306**返回值：**
307
308| 类型                                       | 说明                   |
309| ---------------------------------------- | -------------------- |
310| [DrawableDescriptor](#drawabledescriptor) | DrawableDescriptor对象。 |
311
312**示例：**
313  ```ts
314  import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI';
315
316  @Entry
317  @Component
318  struct Index {
319    @State drawableDescriptor: DrawableDescriptor | undefined = undefined;
320
321    private getMask(): DrawableDescriptor | undefined {
322      let resManager = this.getUIContext().getHostContext()?.resourceManager;
323      // $r('app.media.drawable')需要替换为开发者所需的图像资源文件。
324      let drawable: DrawableDescriptor | undefined = resManager?.getDrawableDescriptor($r('app.media.drawable').id);
325      if (!drawable) {
326        return undefined;
327      }
328      let layeredDrawableDescriptor = (drawable as LayeredDrawableDescriptor).getMask();
329      return layeredDrawableDescriptor;
330    }
331
332    aboutToAppear(): void {
333      this.drawableDescriptor = this.getMask();
334    }
335
336    build() {
337      RelativeContainer() {
338        if (this.drawableDescriptor) {
339          Image(this.drawableDescriptor)
340            .width(100)
341            .height(100)
342        }
343      }
344      .height('100%')
345      .width('100%')
346    }
347  }
348  ```
349### getMaskClipPath
350
351static getMaskClipPath(): string
352
353LayeredDrawableDescriptor的静态方法，获取系统内置的裁切路径参数。
354
355**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
356
357**系统能力：** SystemCapability.ArkUI.ArkUI.Full
358
359**返回值：**
360
361| 类型                                       | 说明                   |
362| ---------------------------------------- | -------------------- |
363| string | 返回裁切路径的命令字符串。 |
364
365**示例：**
366
367  ```ts
368// xxx.ets
369import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI';
370
371@Entry
372@Component
373struct Index {
374  build() {
375    Row() {
376      Column() {
377        // $r('app.media.icon')需要替换为开发者所需的图像资源文件。
378        Image($r('app.media.icon'))
379          .width('200px').height('200px')
380          .clipShape(new Path({commands:LayeredDrawableDescriptor.getMaskClipPath()}))
381        Text(`获取系统内置的裁剪路径参数：`)
382          .fontWeight(800)
383        Text(JSON.stringify(LayeredDrawableDescriptor.getMaskClipPath()))
384          .padding({ left: 20, right: 20 })
385      }.height('100%').justifyContent(FlexAlign.Center)
386    }.width('100%')
387  }
388}
389  ```
390
391## AnimationOptions<sup>12+</sup>
392
393用于控制通过Image组件显示的PixelMap数组动画的播放行为。
394
395**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
396
397**系统能力：** SystemCapability.ArkUI.ArkUI.Full
398
399| 名称      | 类型    | 只读  | 可选  | 说明                                    |
400| ---------- | ------ | -----| ----- | --------------------------------------- |
401| duration   | number | 否   |  是   | 设置图片数组播放总时间。默认每张图片播放1秒。<br/> 取值范围：[0, +∞)      |
402| iterations | number | 否   |  是   | 设置图片数组播放次数。默认为1，值为-1时表示无限播放，值为0时表示不播放，值大于0时表示播放次数。 |
403
404**示例：**
405
406```ts
407import { AnimationOptions } from '@kit.ArkUI';
408@Entry
409@Component
410struct Example {
411  options: AnimationOptions = { duration: 2000, iterations: 1 };
412  build() {
413  }
414}
415```
416
417## AnimatedDrawableDescriptor<sup>12+</sup>
418
419使用Image组件播放PixelMap数组时传入AnimatedDrawableDescriptor对象，该对象继承自[DrawableDescriptor](#drawabledescriptor)。
420
421### constructor<sup>12+</sup>
422
423constructor(pixelMaps: Array\<image.PixelMap>, options?: AnimationOptions)
424
425AnimatedDrawableDescriptor的构造函数。
426
427**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
428
429**系统能力：** SystemCapability.ArkUI.ArkUI.Full
430
431**参数：**
432
433| 参数名     | 类型              | 必填  | 说明                                       |
434| --------- | ---------------- | ---- | ------------------------------------------ |
435| pixelMaps | Array\<[image.PixelMap](../apis-image-kit/arkts-apis-image-PixelMap.md)>  | 是   | PixelMap 数组类型参数，存储 PixelMap 图片数据。 |
436| options   | [AnimationOptions](#animationoptions12) | 否   | 动画控制选项。                               |
437
438**示例：**
439
440```ts
441import { AnimationOptions, AnimatedDrawableDescriptor } from '@kit.ArkUI';
442import { image } from '@kit.ImageKit';
443
444@Entry
445@Component
446struct Example {
447  pixelMaps: Array<image.PixelMap> = [];
448  options: AnimationOptions = { duration: 1000, iterations: -1 };
449  @State animated: AnimatedDrawableDescriptor = new AnimatedDrawableDescriptor(this.pixelMaps, this.options);
450
451  async aboutToAppear() {
452    // $r('app.media.icon')需要替换为开发者所需的图像资源文件。
453    this.pixelMaps.push(await this.getPixmapFromMedia($r('app.media.icon')));
454    this.animated = new AnimatedDrawableDescriptor(this.pixelMaps, this.options);
455  }
456
457  build() {
458    Column() {
459      Row() {
460        Image(this.animated)
461      }
462    }
463  }
464
465  private async getPixmapFromMedia(resource: Resource) {
466    let unit8Array = await this.getUIContext().getHostContext()?.resourceManager?.getMediaContent(resource.id);
467    let imageSource = image.createImageSource(unit8Array?.buffer.slice(0, unit8Array.buffer.byteLength));
468    let createPixelMap: image.PixelMap = await imageSource.createPixelMap({
469      desiredPixelFormat: image.PixelMapFormat.RGBA_8888
470    });
471    await imageSource.release();
472    return createPixelMap;
473  }
474}
475
476```