Image
Image為圖片組件,常用于在應用中顯示圖片。Image支持加載[PixelMap]、[ResourceStr]和[DrawableDescriptor]類型的數據源,支持png、jpg、bmp、svg和gif類型的圖片格式。
說明:
開發前請熟悉鴻蒙開發指導文檔 :[gitee.com/li-shizhen-skin/harmony-os/blob/master/README.md
]
該組件從API Version 7開始支持。后續版本如有新增內容,則采用上角標單獨標記該內容的起始版本。
需要權限
使用網絡圖片時,需要申請權限ohos.permission.INTERNET。
子組件
無
接口
Image(src: PixelMap | ResourceStr | DrawableDescriptor)
通過圖片數據源獲取圖片,用于后續渲染展示。
Image組件加載圖片失敗或圖片尺寸為0時,圖片組件大小自動為0,不跟隨父組件的布局約束。
從API version 9開始,該接口支持在ArkTS卡片中使用。
參數:
參數名 | 參數類型 | 必填 | 參數描述 |
---|---|---|---|
src | [PixelMap] | [ResourceStr] | [DrawableDescriptor] |
屬性
屬性的詳細使用指導請參考[添加屬性]。除支持[通用屬性]外,還支持以下屬性:
名稱 | 參數類型 | 描述 |
---|---|---|
alt | string | [Resource] |
objectFit | [ImageFit] | 設置圖片的填充效果。默認值:ImageFit.Cover從API version 9開始,該接口支持在ArkTS卡片中使用。 |
objectRepeat | [ImageRepeat] | 設置圖片的重復樣式。從中心點向兩邊重復,剩余空間不足放下一張圖片時會截斷。默認值:ImageRepeat.NoRepeat從API version 9開始,該接口支持在ArkTS卡片中使用。**說明:**svg類型圖源不支持該屬性。 |
interpolation | [ImageInterpolation] | 設置圖片的插值效果,即緩解圖片在縮放時的鋸齒問題。默認值:ImageInterpolation.None從API version 9開始,該接口支持在ArkTS卡片中使用。**說明:**圖片縮小顯示時,High級別的interpolation算法不適用,建議使用Medium / Low。svg類型圖源不支持該屬性。 |
renderMode | [ImageRenderMode] | 設置圖片的渲染模式為原色或黑白。默認值:ImageRenderMode.Original從API version 9開始,該接口支持在ArkTS卡片中使用。**說明:**svg類型圖源不支持該屬性。 |
sourceSize | {width: number,height: number} | 設置圖片解碼尺寸,降低圖片的分辨率,常用于需要讓圖片顯示尺寸比組件尺寸更小的場景。和ImageFit.None配合使用時可在組件內顯示小圖。單位:px從API version 9開始,該接口支持在ArkTS卡片中使用。**說明:**僅在目標尺寸小于圖源尺寸時生效。svg類型圖源不支持該屬性。PixelMap資源不支持該屬性。 |
matchTextDirection | boolean | 設置圖片是否跟隨系統語言方向,在RTL語言環境下顯示鏡像翻轉顯示效果。默認值:false從API version 9開始,該接口支持在ArkTS卡片中使用。 |
fitOriginalSize | boolean | 圖片組件尺寸未設置時,其顯示尺寸是否跟隨圖源尺寸。默認值:false從API version 9開始,該接口支持在ArkTS卡片中使用。 |
fillColor | [ResourceColor] | 設置填充顏色,設置后填充顏色會覆蓋在圖片上。從API version 9開始,該接口支持在ArkTS卡片中使用。**說明:**僅對svg圖源生效,設置后會替換svg圖片的填充顏色。 |
autoResize | boolean | 設置圖片解碼過程中是否對圖源自動縮放。設置為true時,組件會根據顯示區域的尺寸決定用于繪制的圖源尺寸,有利于減少內存占用。如原圖大小為1920x1080,而顯示區域大小為200x200,則圖片會降采樣解碼到200x200的尺寸,大幅度節省圖片占用的內存。默認值:true從API version 9開始,該接口支持在ArkTS卡片中使用。**說明:**降采樣解碼時圖片的部分信息丟失,因此可能會導致圖片質量的下降(如:出現鋸齒),這時可以選擇把autoResize設為false,按原圖尺寸解碼,提升顯示效果。 |
syncLoad^8+^ | boolean | 設置是否同步加載圖片,默認是異步加載。同步加載時阻塞UI線程,不會顯示占位圖。默認值:false從API version 9開始,該接口支持在ArkTS卡片中使用。**說明:**建議加載尺寸較小的本地圖片時將syncLoad設為true,因為耗時較短,在主線程上執行即可。 |
copyOption^9+^ | [CopyOptions] | 設置圖片是否可復制。當copyOption設置為非CopyOptions.None時,支持使用長按、鼠標右擊、快捷組合鍵'CTRL+C'等方式進行復制。默認值:CopyOptions.None從API version 9開始,該接口支持在ArkTS卡片中使用。**說明:**svg圖片不支持復制。 |
colorFilter^9+^ | [ColorFilter] | 給圖像設置顏色濾鏡效果,入參為一個的4x5的RGBA轉換矩陣。矩陣第一行表示R(紅色)的向量值,第二行表示G(綠色)的向量值,第三行表示B(藍色)的向量值,第四行表示A(透明度)的向量值,4行分別代表不同的RGBA的向量值。RGBA值分別是0和1之間的浮點數字,當矩陣對角線值為1時,保持圖片原有色彩。**計算規則:**如果輸入的濾鏡矩陣為:![image-matrix-1]像素點為[R, G, B, A]則過濾后的顏色為 [R’, G’, B’, A’]![image-matrix-2]從API version 9開始,該接口支持在ArkTS卡片中使用。 |
說明:
- 使用快捷組合鍵對Image組件復制時,Image組件必須處于[獲焦狀態]。Image組件默認不獲焦,需將[focusable]屬性設置為true,即可使用TAB鍵將焦點切換到組件上,再將[focusOnTouch]屬性設置為true,即可實現點擊獲焦。
- 圖片設置為svg圖源時,當前支持的標簽是svg、rect、circle、ellipse、path、line、polyline和polygon。
ImageInterpolation
從API version 9開始,該接口支持在ArkTS卡片中使用。
名稱 | 描述 |
---|---|
None | 不使用圖片插值。 |
High | 高圖片插值,插值質量最高,可能會影響圖片渲染的速度。 |
Medium | 中圖片插值。 |
Low | 低圖片插值。 |
ImageRenderMode
從API version 9開始,該接口支持在ArkTS卡片中使用。
名稱 | 描述 |
---|---|
Original | 原色渲染模式。 |
Template | 黑白渲染模式。 |
事件
除支持[通用事件]外,還支持以下事件:
onComplete
onComplete(callback: (event?: { width: number, height: number, componentWidth: number, componentHeight: number, loadingStatus: number,contentWidth: number, contentHeight: number, contentOffsetX: number, contentOffsetY: number}) => void) }) => void)
圖片數據加載成功和解碼成功時均觸發該回調,返回成功加載的圖片尺寸。
從API version 9開始,該接口支持在ArkTS卡片中使用。
參數:
參數名 | 類型 | 說明 |
---|---|---|
width | number | 圖片的寬。單位:像素 |
height | number | 圖片的高。單位:像素 |
componentWidth | number | 組件的寬。單位:像素 |
componentHeight | number | 組件的高。單位:像素 |
loadingStatus | number | 圖片加載成功的狀態值。**說明:**返回的狀態值為0時,表示圖片數據加載成功。返回的狀態值為1時,表示圖片解碼成功。 |
contentWidth^10+^ | number | 圖片實際繪制的寬度。單位:像素**說明:**僅在loadingStatus返回1時有效。 |
contentHeight^10+^ | number | 圖片實際繪制的高度。單位:像素**說明:**僅在loadingStatus返回1時有效。 |
contentOffsetX^10+^ | number | 實際繪制內容相對于組件自身的x軸偏移。單位:像素**說明:**僅在loadingStatus返回1時有效。 |
contentOffsetY^10+^ | number | 實際繪制內容相對于組件自身的y軸偏移。單位:像素**說明:**僅在loadingStatus返回1時有效。 |
onError
onError(callback: (event?: { componentWidth: number, componentHeight: number , message: string }) => void)
圖片加載異常時觸發該回調。
從API version 9開始,該接口支持在ArkTS卡片中使用。
參數:
參數名 | 類型 | 說明 |
---|---|---|
componentWidth | number | 組件的寬。單位:像素 |
componentHeight | number | 組件的高。單位:像素 |
message^9+^ | string | 報錯信息。 |
onFinish
onFinish(event: () => void)
當加載的源文件為帶動效的svg格式圖片時,svg動效播放完成時會觸發這個回調。如果動效為無限循環動效,則不會觸發這個回調。
僅支持svg格式的圖片。
從API version 9開始,該接口支持在ArkTS卡片中使用。
示例
加載基本類型圖片
@Entry
@Component
struct ImageExample1 {
build() {
Column() {
Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Start }) {
Row() {
// 加載png格式圖片
Image($r('app.media.ic_camera_master_ai_leaf'))
.width(110).height(110).margin(15)
.overlay('png', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
// 加載gif格式圖片
Image($r('app.media.loading'))
.width(110).height(110).margin(15)
.overlay('gif', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
}
Row() {
// 加載svg格式圖片
Image($r('app.media.ic_camera_master_ai_clouded'))
.width(110).height(110).margin(15)
.overlay('svg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
// 加載jpg格式圖片
Image($r('app.media.ic_public_favor_filled'))
.width(110).height(110).margin(15)
.overlay('jpg', { align: Alignment.Bottom, offset: { x: 0, y: 20 } })
}
}
}.height(320).width(360).padding({ right: 10, top: 10 })
}
}
加載網絡圖片
加載網絡圖片時,默認網絡超時是5分鐘,建議使用alt配置加載時的占位圖。如果需要更靈活的網絡配置,可以使用[HTTP]工具包發送網絡請求,接著將返回的數據解碼為Image組件中的PixelMap
,圖片開發可參考[圖片處理]。HarmonyOS與OpenHarmony鴻蒙文檔籽料:mau123789是v直接拿
使用網絡圖片時,需要申請權限ohos.permission.INTERNET。
@Entry
@Component
struct ImageExample2 {
build() {
Column({ space: 10 }) {
Image("https://www.example.com/xxx.png")// 直接加載網絡地址,請填寫一個具體的網絡圖片地址
.alt($r('app.media.icon'))// 使用alt,在網絡圖片加載成功前使用占位圖
.width(100)
.height(100)
}
}
}
為圖片添加事件
class tmp{
width: number = 0
height: number = 0
}
let msg:tmp = new tmp()
@Entry
@Component
struct ImageExample3 {
@State widthValue: number = 0;
@State heightValue: number = 0;
private on: Resource = $r('app.media.image_on');
private off: Resource = $r('app.media.image_off');
private on2off: Resource = $r('app.media.image_on2off');
private off2on: Resource = $r('app.media.image_off2on');
@State src: Resource = this.on;
build() {
Column() {
Row({ space: 20 }) {
Column() {
Image($r('app.media.img_example1'))
.alt($r('app.media.ic_public_picture'))
.sourceSize({
width: 900,
height: 900
})
.objectFit(ImageFit.Cover)
.height(180).width(180)
// 圖片加載完成后,獲取圖片尺寸。
.onComplete(msg = > {
if(msg){
this.widthValue = msg.width
this.heightValue = msg.height
}
})
.onError(() = > {
console.log('load image fail')
})
.overlay('nwidth: ' + String(this.widthValue) + ' height: ' + String(this.heightValue), {
align: Alignment.Bottom,
offset: { x: 0, y: 20 }
})
}
// 為圖片添加點擊事件,點擊完成后加載特定圖片
Image(this.src)
.width(120).height(120)
.onClick(() = > {
if (this.src == this.on || this.src == this.off2on) {
this.src = this.on2off
} else {
this.src = this.off2on
}
})
.onFinish(() = > {
if (this.src == this.off2on) {
this.src = this.on
} else {
this.src = this.off
}
})
}
}.width('100%')
}
}
審核編輯 黃宇
-
Image
+關注
關注
0文章
32瀏覽量
11896 -
組件
+關注
關注
1文章
512瀏覽量
17815 -
鴻蒙
+關注
關注
57文章
2345瀏覽量
42822
發布評論請先 登錄
相關推薦
評論