1# @ohos.arkui.drawableDescriptor (DrawableDescriptor)
2
3本模块提供获取pixelMap的能力，包括前景、背景、蒙版和分层图标。
4
5> **说明：**
6>
7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 示例效果请以真机运行为准，当前IDE预览器不支持。
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### getForeground
164getForeground(): DrawableDescriptor;
165
166获取前景的DrawableDescriptor对象。
167
168**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
169
170**系统能力：** SystemCapability.ArkUI.ArkUI.Full
171
172**返回值：**
173
174| 类型                                       | 说明                   |
175| ---------------------------------------- | -------------------- |
176| [DrawableDescriptor](#drawabledescriptor) | DrawableDescriptor对象 |
177
178**示例：**
179  ```ts
180import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
181let resManager = getContext().resourceManager
182let drawable: LayeredDrawableDescriptor = (resManager.getDrawableDescriptor($r('app.media.drawable')
183    .id)) as LayeredDrawableDescriptor;
184let drawableNew: object = drawable.getForeground()
185  ```
186
187### getBackground
188
189getBackground(): DrawableDescriptor;
190
191获取背景的DrawableDescriptor对象。
192
193**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
194
195**系统能力：** SystemCapability.ArkUI.ArkUI.Full
196
197**返回值：**
198
199| 类型                                       | 说明                   |
200| ---------------------------------------- | -------------------- |
201| [DrawableDescriptor](#drawabledescriptor) | DrawableDescriptor对象 |
202
203**示例：**
204  ```ts
205import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
206let resManager = getContext().resourceManager
207let drawable: LayeredDrawableDescriptor = (resManager.getDrawableDescriptor($r('app.media.drawable')
208    .id)) as LayeredDrawableDescriptor;
209let drawableNew: object = drawable.getBackground()
210  ```
211
212### getMask
213
214getMask(): DrawableDescriptor
215
216获取蒙版的DrawableDescriptor对象。
217
218**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
219
220**系统能力：** SystemCapability.ArkUI.ArkUI.Full
221
222**返回值：**
223
224| 类型                                       | 说明                   |
225| ---------------------------------------- | -------------------- |
226| [DrawableDescriptor](#drawabledescriptor) | DrawableDescriptor对象 |
227
228**示例：**
229  ```ts
230import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
231let resManager = getContext().resourceManager
232let drawable: LayeredDrawableDescriptor = (resManager.getDrawableDescriptor($r('app.media.drawable')
233    .id)) as LayeredDrawableDescriptor;
234let drawableNew: object = drawable.getMask()
235  ```
236### getMaskClipPath
237
238static getMaskClipPath(): string
239
240LayeredDrawableDescriptor的静态方法，获取系统内置的裁切路径参数。
241
242**原子化服务API：** 从API version 11开始，该接口支持在原子化服务中使用。
243
244**系统能力：** SystemCapability.ArkUI.ArkUI.Full
245
246**返回值：**
247
248| 类型                                       | 说明                   |
249| ---------------------------------------- | -------------------- |
250| string | 返回裁切路径的命令字符串 |
251
252**示例：**
253
254  ```ts
255// xxx.ets
256import { DrawableDescriptor, LayeredDrawableDescriptor } from '@kit.ArkUI'
257
258@Entry
259@Component
260struct Index {
261  build() {
262    Row() {
263      Column() {
264        Image($r('app.media.icon'))
265          .width('200px').height('200px')
266          .clip(new Path({commands:LayeredDrawableDescriptor.getMaskClipPath()}))
267        Text(`获取系统内置的裁剪路径参数：`)
268          .fontWeight(800)
269        Text(JSON.stringify(LayeredDrawableDescriptor.getMaskClipPath()))
270          .padding({ left: 20, right: 20 })
271      }.height('100%').justifyContent(FlexAlign.Center)
272    }.width('100%')
273  }
274}
275  ```
276
277## AnimationOptions<sup>12+</sup>
278
279PixelMap 数组通过Image组件显示时用来控制动画的播放。
280
281**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
282
283**系统能力：** SystemCapability.ArkUI.ArkUI.Full
284
285| 名称      | 类型    | 必填  | 说明                                    |
286| ---------- | ------ | -----| --------------------------------------- |
287| duration   | number | 否   | 设置图片数组播放总时间。默认每张图片1秒。      |
288| iterations | number | 否   | 设置图片数组播放次数。默认为1，为-1时无限播放。 |
289
290**示例：**
291
292```ts
293import { AnimationOptions } from '@kit.ArkUI'
294@Entry
295@Component
296struct Example {
297  options: AnimationOptions = { duration: 2000, iterations: 1 }
298  build() {
299  }
300}
301```
302
303## AnimatedDrawableDescriptor<sup>12+</sup>
304
305Image组件播放PixelMap数组时传入AnimatedDrawableDescriptor对象。继承自[DrawableDescriptor](#drawabledescriptor)。
306
307### constructor<sup>12+</sup>
308
309constructor(pixelMaps: Array\<image.PixelMap>, options?: AnimationOptions)
310
311AnimatedDrawableDescriptor的构造函数。
312
313**原子化服务API：** 从API version 12开始，该接口支持在原子化服务中使用。
314
315**系统能力：** SystemCapability.ArkUI.ArkUI.Full
316
317**参数：**
318
319| 参数名     | 类型              | 必填  | 说明                                       |
320| --------- | ---------------- | ---- | ------------------------------------------ |
321| pixelMaps | Array\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)>  | 是   | PixelMap 数组类型参数，存储 PixelMap 图片数据。 |
322| options   | [AnimationOptions](#animationoptions12) | 否   | 动画控制选项。                               |
323
324**示例：**
325
326```ts
327import { AnimationOptions, AnimatedDrawableDescriptor } from '@kit.ArkUI'
328import { image } from '@kit.ImageKit'
329
330@Entry
331@Component
332struct Example {
333  pixelmaps: Array<image.PixelMap>  = [];
334  options: AnimationOptions = {duration:1000, iterations:-1};
335  @State animated: AnimatedDrawableDescriptor  = new AnimatedDrawableDescriptor(this.pixelmaps, this.options);
336  async aboutToAppear() {
337    this.pixelmaps.push(await this.getPixmapFromMedia($r('app.media.icon')))
338    this.animated = new AnimatedDrawableDescriptor(this.pixelmaps, this.options);
339  }
340  build() {
341    Column() {
342      Row() {
343        Image(this.animated)
344      }
345    }
346  }
347  private async getPixmapFromMedia(resource: Resource) {
348    let unit8Array = await getContext(this)?.resourceManager?.getMediaContent({
349      bundleName: resource.bundleName,
350      moduleName: resource.moduleName,
351      id: resource.id
352    })
353    let imageSource = image.createImageSource(unit8Array.buffer.slice(0, unit8Array.buffer.byteLength))
354    let createPixelMap: image.PixelMap = await imageSource.createPixelMap({
355      desiredPixelFormat: image.PixelMapFormat.RGBA_8888
356    })
357    await imageSource.release()
358    return createPixelMap
359  }
360}
361
362```