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/js-apis-image.md#pixelmap7) | PixelMap |
36
37**示例：**
38  ```ts
39import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
40let resManager = getContext().resourceManager
41let pixmap: DrawableDescriptor = (resManager.getDrawableDescriptor($r('app.media.icon')
42    .id)) as DrawableDescriptor;
43let pixmapNew: object = pixmap.getPixelMap()
44  ```
45
46当传入资源id或name为普通图片时，生成DrawableDescriptor对象。
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/js-apis-image.md#pixelmap7)  | 否 | 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 = getContext().resourceManager
97
98      build() {
99        Row() {
100          Column() {
101            Image((this.resManager.getDrawableDescriptor($r('app.media.drawable').id) as LayeredDrawableDescriptor))
102            Image(((this.resManager.getDrawableDescriptor($r('app.media.drawable')
103            .id) as LayeredDrawableDescriptor).getForeground()).getPixelMap())
104          }.height('50%')
105        }.width('50%')
106      }
107    }
108    ```
1092. 通过PixelMapDrawableDescriptor创建LayeredDrawableDescriptor。
110
111    ```ts
112    import { DrawableDescriptor, LayeredDrawableDescriptor, PixelMapDrawableDescriptor } from '@kit.ArkUI'
113    import { image } from '@kit.ImageKit'
114
115    @Entry
116    @Component
117    struct Index {
118      @State fore1: image.PixelMap | undefined = undefined
119      @State back1: image.PixelMap | undefined = undefined
120
121      @State foregroundDraw:DrawableDescriptor|undefined=undefined
122      @State backgroundDraw:DrawableDescriptor|undefined=undefined
123      @State maskDraw:DrawableDescriptor|undefined=undefined
124      @State maskPixel: image.PixelMap | undefined = undefined
125      @State draw : LayeredDrawableDescriptor | undefined = undefined
126      async aboutToAppear() {
127        this.fore1 = await this.getPixmapFromMedia($r('app.media.foreground'))
128        this.back1 = await this.getPixmapFromMedia($r('app.media.background'))
129        this.maskPixel = await this.getPixmapFromMedia($r('app.media.ohos_icon_mask'))
130        // 使用PixelMapDrawableDescriptor创建LayeredDrawableDescriptor
131        this.foregroundDraw = new PixelMapDrawableDescriptor(this.fore1)
132        this.backgroundDraw = new PixelMapDrawableDescriptor(this.back1)
133        this.maskDraw = new PixelMapDrawableDescriptor(this.maskPixel)
134
135        this.draw = new LayeredDrawableDescriptor(this.foregroundDraw,this.backgroundDraw,this.maskDraw)
136      }
137      build() {
138        Row() {
139          Column() {
140              Image(this.draw)
141                .width(300)
142                .height(300)
143          }.height('100%').justifyContent(FlexAlign.Center)
144        }.width('100%').height("100%").backgroundColor(Color.Pink)
145      }
146      // 根据资源，通过图片框架获取pixelMap
147      private async getPixmapFromMedia(resource: Resource) {
148        let unit8Array = await getContext(this)?.resourceManager?.getMediaContent({
149          bundleName: resource.bundleName,
150          moduleName: resource.moduleName,
151          id: resource.id
152        })
153        let imageSource = image.createImageSource(unit8Array.buffer.slice(0, unit8Array.buffer.byteLength))
154        let createPixelMap: image.PixelMap = await imageSource.createPixelMap({
155          desiredPixelFormat: image.PixelMapFormat.BGRA_8888
156        })
157        await imageSource.release()
158        return createPixelMap
159      }
160    }
161    ```
162
163### constructor<sup>12+</sup>
164
165constructor(foreground?: DrawableDescriptor, background?: DrawableDescriptor, mask?: DrawableDescriptor);
166
167LayeredDrawableDescriptor的构造函数。
168
169**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
170
171**系统能力：** SystemCapability.ArkUI.ArkUI.Full
172
173**参数：**
174
175| 参数名     | 类型              | 必填  | 说明                                       |
176| --------- | ---------------- | ---- | ------------------------------------------ |
177| foreground | [DrawableDescriptor](#drawabledescriptor)  | 否   | 分层图标的前景图片选项。 |
178| background   | [DrawableDescriptor](#drawabledescriptor) | 否   | 分层图标的背景图片选项。  |
179| mask | [DrawableDescriptor](#drawabledescriptor) | 否 | 分层图标的遮罩选项。 |
180
181### getForeground
182getForeground(): DrawableDescriptor;
183
184获取前景的DrawableDescriptor对象。
185
186**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
187
188**系统能力：** SystemCapability.ArkUI.ArkUI.Full
189
190**返回值：**
191
192| 类型                                       | 说明                   |
193| ---------------------------------------- | -------------------- |
194| [DrawableDescriptor](#drawabledescriptor) | DrawableDescriptor对象。 |
195
196**示例：**
197  ```ts
198import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
199let resManager = getContext().resourceManager
200let drawable: LayeredDrawableDescriptor = (resManager.getDrawableDescriptor($r('app.media.drawable')
201    .id)) as LayeredDrawableDescriptor;
202let drawableNew: object = drawable.getForeground()
203  ```
204
205### getBackground
206
207getBackground(): DrawableDescriptor;
208
209获取背景的DrawableDescriptor对象。
210
211**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
212
213**系统能力：** SystemCapability.ArkUI.ArkUI.Full
214
215**返回值：**
216
217| 类型                                       | 说明                   |
218| ---------------------------------------- | -------------------- |
219| [DrawableDescriptor](#drawabledescriptor) | DrawableDescriptor对象。 |
220
221**示例：**
222  ```ts
223import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
224let resManager = getContext().resourceManager
225let drawable: LayeredDrawableDescriptor = (resManager.getDrawableDescriptor($r('app.media.drawable')
226    .id)) as LayeredDrawableDescriptor;
227let drawableNew: object = drawable.getBackground()
228  ```
229
230### getMask
231
232getMask(): DrawableDescriptor
233
234获取蒙版的DrawableDescriptor对象。
235
236**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
237
238**系统能力：** SystemCapability.ArkUI.ArkUI.Full
239
240**返回值：**
241
242| 类型                                       | 说明                   |
243| ---------------------------------------- | -------------------- |
244| [DrawableDescriptor](#drawabledescriptor) | DrawableDescriptor对象。 |
245
246**示例：**
247  ```ts
248import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
249let resManager = getContext().resourceManager
250let drawable: LayeredDrawableDescriptor = (resManager.getDrawableDescriptor($r('app.media.drawable')
251    .id)) as LayeredDrawableDescriptor;
252let drawableNew: object = drawable.getMask()
253  ```
254### getMaskClipPath
255
256static getMaskClipPath(): string
257
258LayeredDrawableDescriptor的静态方法，获取系统内置的裁切路径参数。
259
260**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
261
262**系统能力：** SystemCapability.ArkUI.ArkUI.Full
263
264**返回值：**
265
266| 类型                                       | 说明                   |
267| ---------------------------------------- | -------------------- |
268| string | 返回裁切路径的命令字符串。 |
269
270**示例：**
271
272  ```ts
273// xxx.ets
274import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
275
276@Entry
277@Component
278struct Index {
279  build() {
280    Row() {
281      Column() {
282        Image($r('app.media.icon'))
283          .width('200px').height('200px')
284          .clipShape(new Path({commands:LayeredDrawableDescriptor.getMaskClipPath()}))
285        Text(`获取系统内置的裁剪路径参数：`)
286          .fontWeight(800)
287        Text(JSON.stringify(LayeredDrawableDescriptor.getMaskClipPath()))
288          .padding({ left: 20, right: 20 })
289      }.height('100%').justifyContent(FlexAlign.Center)
290    }.width('100%')
291  }
292}
293  ```
294
295## AnimationOptions<sup>12+</sup>
296
297PixelMap 数组通过Image组件显示时用来控制动画的播放。
298
299**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
300
301**系统能力：** SystemCapability.ArkUI.ArkUI.Full
302
303| 名称      | 类型    | 必填  | 说明                                    |
304| ---------- | ------ | -----| --------------------------------------- |
305| duration   | number | 否   | 设置图片数组播放总时间。默认每张图片1秒。      |
306| iterations | number | 否   | 设置图片数组播放次数。默认为1，为-1时无限播放。 |
307
308**示例：**
309
310```ts
311import { AnimationOptions } from '@kit.ArkUI'
312@Entry
313@Component
314struct Example {
315  options: AnimationOptions = { duration: 2000, iterations: 1 }
316  build() {
317  }
318}
319```
320
321## AnimatedDrawableDescriptor<sup>12+</sup>
322
323Image组件播放PixelMap数组时传入AnimatedDrawableDescriptor对象。继承自[DrawableDescriptor](#drawabledescriptor)。
324
325### constructor<sup>12+</sup>
326
327constructor(pixelMaps: Array\<image.PixelMap>, options?: AnimationOptions)
328
329AnimatedDrawableDescriptor的构造函数。
330
331**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
332
333**系统能力：** SystemCapability.ArkUI.ArkUI.Full
334
335**参数：**
336
337| 参数名     | 类型              | 必填  | 说明                                       |
338| --------- | ---------------- | ---- | ------------------------------------------ |
339| pixelMaps | Array\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)>  | 是   | PixelMap 数组类型参数，存储 PixelMap 图片数据。 |
340| options   | [AnimationOptions](#animationoptions12) | 否   | 动画控制选项。                               |
341
342**示例：**
343
344```ts
345import { AnimationOptions, AnimatedDrawableDescriptor } from '@kit.ArkUI'
346import { image } from '@kit.ImageKit'
347
348@Entry
349@Component
350struct Example {
351  pixelmaps: Array<image.PixelMap>  = [];
352  options: AnimationOptions = {duration:1000, iterations:-1};
353  @State animated: AnimatedDrawableDescriptor  = new AnimatedDrawableDescriptor(this.pixelmaps, this.options);
354  async aboutToAppear() {
355    this.pixelmaps.push(await this.getPixmapFromMedia($r('app.media.icon')))
356    this.animated = new AnimatedDrawableDescriptor(this.pixelmaps, this.options);
357  }
358  build() {
359    Column() {
360      Row() {
361        Image(this.animated)
362      }
363    }
364  }
365  private async getPixmapFromMedia(resource: Resource) {
366    let unit8Array = await getContext(this)?.resourceManager?.getMediaContent({
367      bundleName: resource.bundleName,
368      moduleName: resource.moduleName,
369      id: resource.id
370    })
371    let imageSource = image.createImageSource(unit8Array.buffer.slice(0, unit8Array.buffer.byteLength))
372    let createPixelMap: image.PixelMap = await imageSource.createPixelMap({
373      desiredPixelFormat: image.PixelMapFormat.RGBA_8888
374    })
375    await imageSource.release()
376    return createPixelMap
377  }
378}
379
380```