圖片視頻區(qū) AddMedia 詳解引言前兩篇分別講了本地選圖和跨設(shè)備拉取媒體這兩條通路最終都匯入同一個組件——AddMedia。它是發(fā)布頁的圖片視頻區(qū)橫向滾動的九宮格、虛線加號、長按菜單復(fù)制、點擊彈出粘貼、拖拽排序……所有與媒體相關(guān)的交互都發(fā)生在這個組件里。本文不再重復(fù)選圖邏輯而是聚焦AddMedia本身的結(jié)構(gòu)設(shè)計與交互實現(xiàn)數(shù)據(jù)從哪來StorageLink(mediaUriArray)全局媒體列表列表怎么展示List ListItem ForEach圖片/視頻雙分支數(shù)量上限如何貫穿所有入口9 的上限與各處 toast復(fù)制/粘貼菜單如何實現(xiàn)bindMenu PasteButton虛線加號addDefaultPic如何組裝。知識點講解StorageLink讓媒體列表全局共享AddMedia的媒體數(shù)據(jù)聲明為StorageLink(mediaUriArray)mediaUriArray: ArrayMediaInfo [];mediaUriArray掛在 AppStorage 的mediaUriArray鍵上。這意味著無論數(shù)據(jù)是本地選圖、跨設(shè)備拉取、剪貼板粘貼還是拖拽落下的圖片 push 進來的UI 都會自動刷新將來發(fā)布頁打包接續(xù)時也是直接讀這個全局數(shù)組。MediaInfo接口entry/src/main/ets/model/ContentInfo.ets有三個關(guān)鍵字段export interface MediaInfo { imagePixelMap?: PixelMap;//圖片PixelMap 縮略圖圖片分支優(yōu)先判斷 mediaName: string;//媒體名展示名或 UUID mediaType: MediaType;//image|videovideoUri?: string;//視頻uri視頻分支判斷 }List 橫向滾動 ForEachArkUI 的List默認縱向滾動設(shè)置.listDirection(Axis.Horizontal)即橫向。ForEach(this.mediaUriArray, (item) {...}, keyGenerator)遍歷數(shù)據(jù)渲染ListItem第三個參數(shù)是鍵生成器——本項目用JSON.stringify(item) index保證每個條目有穩(wěn)定唯一鍵避免復(fù)用錯亂。為什么九宮格用List而不是Grid因為需求是一行橫向滾動數(shù)量從 0 到 9 動態(tài)變化List的懶加載與滾動語義正好契合Grid更擅長多行多列的靜態(tài)網(wǎng)格。選型原則很簡單數(shù)據(jù)結(jié)構(gòu)決定布局組件。另外ForEach的鍵生成器不能省略或偷懶用裸index——一旦列表增刪錯位的鍵會導(dǎo)致條目復(fù)用錯誤、圖片閃爍。本項目用JSON.stringify(item) index把內(nèi)容 序號都編進鍵里雖然略重但保證了任何數(shù)據(jù)變化都能被正確識別。bindMenu長按/點擊彈出菜單bindMenu可以把一個Menu或Builder構(gòu)建的菜單內(nèi)容綁定到組件上。bindMenu(this.copy(...))表示長按該組件彈出復(fù)制菜單bindMenu(isShown, menuContent, options)是帶顯隱控制的重載第一個參數(shù)為 true 時菜單彈出options.onDisappear在菜單消失時回調(diào)——本項目用它做粘貼超量的延遲提示。PasteButton安全粘貼控件PasteButton是 HarmonyOS 的安全控件之一它看起來是個按鈕但點擊后由系統(tǒng)代為執(zhí)行讀取剪貼板動作應(yīng)用不需要也無法直接讀剪貼板從而規(guī)避了剪貼板權(quán)限。這類安全控件還有保存、麥克風(fēng)、相機等的共同特征是系統(tǒng)替應(yīng)用完成敏感操作應(yīng)用只在回調(diào)里拿結(jié)果用戶對什么時候讀了什么有完全知情權(quán)。本項目用它在菜單里提供粘貼入口——注意安全控件在某些場景下有使用限制這正是項目同時保留代碼級剪貼板讀取getPasteDataTest的原因之一系統(tǒng)控件受限時如某些浮窗場景仍有兜底路徑。StorageLink 數(shù)組增刪自動刷新mediaUriArray是StorageLink綁定的數(shù)組。當代碼執(zhí)行this.mediaUriArray.push(...)時ArkUI 的響應(yīng)式系統(tǒng)能感知到數(shù)組長度變化并觸發(fā)依賴該數(shù)組的 UIForEach重建——不需要手動 setState 或重新賦值整個數(shù)組。這是 ArkUI 狀態(tài)管理最小粒度刷新的體現(xiàn)。不過要提醒如果直接替換數(shù)組的某個下標元素arr[0] x部分版本需要先取出再放回才能觸發(fā)刷新穩(wěn)妥的做法是整體this.mediaUriArray [...this.mediaUriArray]——本工程代碼統(tǒng)一用push恰好避開了這個坑。結(jié)合本項目源碼分析組件外殼接收跨設(shè)備數(shù)據(jù) 整體拖拽文件路徑entry/src/main/ets/view/contentEditor/AddMedia.ets。build() {Column() {// 跨設(shè)備媒體接收器上一篇已講CollaborationServiceStateDialog({onState: (stateCode:number,bufferType:string,buffer:ArrayBuffer):voidthis.doInsertMedia(stateCode, bufferType, buffer) })this.addMedia();// 圖片視頻展示區(qū)}// 整個區(qū)域可拖出且允許接收圖片/PixelMap 落下.draggable(true) .allowDrop([uniformTypeDescriptor.UniformDataType.IMAGE, uniformTypeDescriptor.UniformDataType.OPENHARMONY_PIXEL_MAP]) .onDrop((dragEvent?: DragEvent) { ... })// 拖拽圖片落入的處理... }draggable(true)讓整個媒體區(qū)可以被拖起allowDrop聲明能接收哪些類型的數(shù)據(jù)系統(tǒng) IMAGE 與 PixelMaponDrop處理拖入?？缭O(shè)備拖拽的完整機制在模塊五詳解這里只需知道AddMedia 既是媒體展示區(qū)也是圖片拖放的接盤俠。展示區(qū)addMedia BuilderBuilderaddMedia() { Row() {// 橫向列表已添加的圖片/視頻List({ space: CommonConstants.LIST_COMM_SPACE }) { ForEach(this.mediaUriArray, (item: MediaInfo) { ListItem() {if(item.imagePixelMap) {// —— 圖片分支 ——Image(item.imagePixelMap) .width($r(app.integer.add_image_area_size))// 96vp 方格子.height($r(app.integer.add_image_area_size)) .borderRadius($r(app.integer.border_radius3)) .visibility(item ? Visibility.Visible : Visibility.None) .draggable(true)// 單張圖可拖出.onDragEnd((event) {// 拖出后對方未接收失敗則提示if(event.getResult() DragResult.DRAG_FAILED) {this.getUIContext().getPromptAction().showToast({ duration:100, message:Drag failed}); } }) .bindMenu(this.copy(item.imagePixelMap))// 長按 → 復(fù)制菜單}elseif(item.videoUri) {// —— 視頻分支 ——Video({ src: item.videoUri, posterOptions: { showFirstFrame:true}// 封面顯示首幀}) .width($r(app.integer.add_image_area_size)) .height($r(app.integer.add_image_area_size)) .borderRadius($r(app.integer.border_radius3)) .draggable(true) .controls(false)// 隱藏系統(tǒng)控制條格子太小.autoPlay(true)// 自動播放.loop(true)// 循環(huán)播放.bindMenu(this.copy(item.videoUri))// 長按 → 復(fù)制菜單} } }, (item: MediaInfo, index: number) JSON.stringify(item) index)// 列表末尾追加虛線加號this.addDefaultPic() } .listDirection(Axis.Horizontal)// 橫向滾動.scrollBar(BarState.Off)// 隱藏滾動條.width(CommonConstants.FULL_PERCENT) .height(CommonConstants.FULL_PERCENT) } .height($r(app.integer.add_image_area_size))// 96vp.width(CommonConstants.FULL_PERCENT) .alignItems(VerticalAlign.Center) .padding({ left: ..., right: ... })// 斷點響應(yīng)式左右 padding.onClick(() {// 點擊媒體區(qū)先關(guān)再開確保每次點擊都彈出粘貼菜單this.pasteShow false;this.pasteShow true; }) .bindMenu(this.pasteShow,this.paste(), { onDisappear: () {// 菜單消失時若曾觸發(fā)超量提示補一個 toastif(this.toastShow) {this.getUIContext().getPromptAction().showToast({ message: $r(app.string.add_picture_prompt) });this.toastShow false; } } }) }這段代碼信息量很大拆開看圖片/視頻雙分支用if (item.imagePixelMap)/else if (item.videoUri)區(qū)分兩種媒體。圖片用Image顯示 PixelMap視頻用Video組件showFirstFrame顯示首幀封面controls(false)隱藏控制條、autoPlay(true)loop(true)讓格子里的視頻自動循環(huán)播放——在 96vp 的小格子里營造輕預(yù)覽體驗。點擊彈粘貼菜單onClick里先 false 后 true的寫法是刻意為之——如果連續(xù)兩次點擊都保持 true第二次不會重新觸發(fā)菜單先置 false 再置 true 保證每次點擊都能彈出。菜單內(nèi)容由this.paste()構(gòu)建onDisappear兜底處理粘貼超量的提示時機。拖動反饋每張圖的onDragEnd檢查event.getResult()如果接收方返回DRAG_FAILED比如目標不可接收彈 100ms 的 Drag failed toast 提醒用戶。復(fù)制菜單copy BuilderBuilder copy(data: image.PixelMap|string) {Row(){Text($r(app.string.copy))//Copy .fontSize(16).fontWeight(FontWeight.Medium)} .padding({ left: 16 }) .height(48) .width(224) .onClick((){ this.setPasteDataTest(data);// 寫入系統(tǒng)剪貼板}) }長按圖片彈出Copy菜單點擊后把數(shù)據(jù)寫入剪貼板。setPasteDataTest按數(shù)據(jù)類型走不同 MIMEasync setPasteDataTest(data:image.PixelMap |string): Promisevoid {letpasteData: pasteboard.PasteData;if(typeof datastring) {// 視頻以 URI 文本形式寫入剪貼板pasteData pasteboard.createData(pasteboard.MIMETYPE_TEXT_URI,data); }else{// 圖片以 PixelMap 形式寫入剪貼板pasteData pasteboard.createData(pasteboard.MIMETYPE_PIXELMAP,data); }letsystemPasteBoard: pasteboard.SystemPasteboard pasteboard.getSystemPasteboard(); await systemPasteBoard.setData(pasteData).catch((err: BusinessError) {...}); }這樣復(fù)制出的數(shù)據(jù)可以在本應(yīng)用內(nèi)粘貼也可以借助跨設(shè)備剪貼板在另一臺設(shè)備上粘貼——這正是跨設(shè)備互通的一個縮影。粘貼菜單paste Builder 與 PasteButtonBuilder paste(){ Row(){//系統(tǒng)安全控件點擊由系統(tǒng)代為讀取剪貼板 PasteButton({ text: PasteDescription.PASTE }).fontSize(16).fontColor(Color.Black).fontWeight(FontWeight.Medium).backgroundColor(Color.White).padding({ right: 176 }).width(100%).onClick(() { this.getPasteDataTest();//讀取并處理剪貼板內(nèi)容 this.pasteShow false;//關(guān)閉菜單 }) }.height(48).width(224)}PasteButton點擊后由系統(tǒng)讀取剪貼板隨后應(yīng)用的onClick里調(diào)用getPasteDataTest主動獲取剪貼板數(shù)據(jù)。getPasteDataTest內(nèi)部分兩類處理MIMETYPE_PIXELMAP是圖片取出 PixelMap 加入列表、MIMETYPE_TEXT_URI是視頻 URI寫分布式文件 加入列表若列表已滿則置toastShow true由菜單的onDisappear統(tǒng)一彈提示。虛線加號addDefaultPic BuilderBuilder addDefaultPic(){Row(){Column(){// 加號圖標系統(tǒng) SymbolSymbolGlyph($r(sys.symbol.camera_badge_plus)) .fontSize($r(app.integer.add_icon_size))// 26vp.fontColor([$r(sys.color.font_primary)])// 文案隨已添加數(shù)量三態(tài)切換Text(this.mediaUriArray.length 0 ? $r(app.string.add_high_img):// 0 張Add Image(this.mediaUriArray.length CommonConstants.MAX_ADD_MEDIA_NUM ?$r(app.string.continue_add):// 未滿 9Continue Add$r(app.string.image_add)))// 已滿 9Upper Limit.fontSize($r(app.integer.text_size_body3)) .fontColor($r(app.color.add_image_background)) .margin({ top:$r(app.integer.comm_padding_margin_mini)}) } .justifyContent(FlexAlign.Center).width(CommonConstants.FULL_PERCENT) } .borderStyle(BorderStyle.Dashed)// 虛線邊框.borderWidth($r(app.integer.default_border_width)) .borderColor($r(app.color.add_image_border_color)) .borderRadius($r(app.integer.border_radius3)) .width($r(app.integer.add_image_area_size)) .height($r(app.integer.add_image_area_size)) .margin({ right:$r(app.integer.add_default_pic_right), bottom:$r(app.integer.add_default_pic_bottom)}) .bindMenu(this.MyTestMenu())// 點加號 → 彈出本地設(shè)備 跨設(shè)備菜單}三個細節(jié)值得一提三態(tài)文案mediaUriArray.length為 0 顯示 Add Image首圖引導(dǎo)、未滿 9 顯示 Continue Add鼓勵繼續(xù)加、滿 9 顯示 Upper Limit明示封頂。一行三元表達式把狀態(tài)機表達得清清楚楚。虛線加號視覺BorderStyle.Dashed 1vp 虛線邊框 圓角配合SymbolGlyph系統(tǒng)圖標構(gòu)成標準的添加占位樣式96vp 與圖片格子完全一致保證九宮格對齊。入口聚合bindMenu(this.MyTestMenu())把本地設(shè)備 跨設(shè)備拉取兩個入口都掛在這一個加號上菜單內(nèi)容見上一篇用戶心智單一。兩個補充通路粘貼與拖拽的數(shù)據(jù)處理除了復(fù)制菜單AddMedia 還有兩條加圖通路值得掃一眼它們的共同點是把各種來源的數(shù)據(jù)統(tǒng)一還原成 PixelMap 或 URI。粘貼通路getPasteDataTest從剪貼板讀PasteDatagetPrimaryMimeType()判斷類型——MIMETYPE_PIXELMAP直接取出getPrimaryPixelMap()加入列表MIMETYPE_TEXT_URI則把 URI 當作視頻源writeDistributedFile復(fù)制 加入列表。注意它用getRecordCount()和getPrimaryMimeType()先看一眼再決定怎么處理避免對未知類型做錯誤假設(shè)。拖拽通路onDropuri2pixelMap拖入的數(shù)據(jù)可能是OPENHARMONY_PIXEL_MAP類型的記錄跨進程傳輸?shù)?PixelMap也可能是Image類型只有 imageUri。前者需要按details里的寬高/像素格式信息重建 PixelMap// 從拖拽記錄里解析像素圖元數(shù)據(jù)constmWidth: number (pixelMapRecord.details?.width??-1) as number;constmPixelFormat:image.PixelMapFormat (pixelMapRecord.details?.[pixel-format] ??image.PixelMapFormat.UNKNOWN) asimage.PixelMapFormat;// 用這些信息初始化一張新 PixelMapconstopts:image.InitializationOptions { srcPixelFormat: mPixelFormat, pixelFormat: mPixelFormat,size: {width: mWidth,height: mHeight } };constpixelMap awaitimage.createPixelMap(buffer, opts);后者Image記錄走uri2pixelMapfileIo.openSync打開 URI →image.createImageSource(fd)解碼 → 縮放到 100×100 的小圖 → 加入列表。這條打開→解碼→縮放的管線與第 16 篇本地選圖的編碼管線正好互為鏡像——一個負責把外部數(shù)據(jù)變成 PixelMap一個負責把 PixelMap 變成文件字節(jié)流。數(shù)量上限如何貫穿全局MAX_ADD_MEDIA_NUM 9CommonConstants.ets在每個加媒體入口都有一道閘門形成多層防護selectImage截斷超出部分 toastMyTestMenu的本地設(shè)備入菜空前校驗doInsertMedia跨設(shè)備入數(shù)據(jù)前校驗getPasteDataTest粘貼入數(shù)據(jù)前校驗toastShow延遲提示uri2pixelMap拖拽 URI 轉(zhuǎn)圖入數(shù)據(jù)前校驗 toastonDrop拖拽 PixelMap入數(shù)據(jù)前校驗 toastaddDefaultPic文案三態(tài) 滿 9 時菜單仍可彈出但不放行。這種處處設(shè)防的寫法對演示工程來說略顯冗余但對真實產(chǎn)品而言是必要的健壯性——任何一條通路漏了校驗都可能讓數(shù)組突破 9 而撐爆九宮格布局。小結(jié)AddMedia是發(fā)布頁最多功能的子組件它的設(shè)計哲學(xué)可以概括為**入口多樣、出口統(tǒng)一**數(shù)據(jù)出口統(tǒng)一無論來自本地、遠端、剪貼板還是拖拽最終都 push 進mediaUriArray由同一個橫向 List 渲染交互出口統(tǒng)一復(fù)制、粘貼、拖拽、跨設(shè)備最終都產(chǎn)出MediaInfo約束統(tǒng)一MAX_ADD_MEDIA_NUM 9在每條通路上設(shè)卡保證九宮格永不超限。對初級開發(fā)者建議動手復(fù)現(xiàn)時重點體會三點StorageLink數(shù)組驅(qū)動 UI 刷新的爽快感、bindMenu的兩種用法內(nèi)容綁定/顯隱控制、以及PasteButton安全控件與普通按鈕在權(quán)限語義上的差異。此外AddMedia 還示范了一個組件邊界的設(shè)計判斷它既是數(shù)據(jù)源選圖、粘貼、拖拽、跨設(shè)備拉取都匯聚于此又是展示區(qū)九宮格還是拖放交互區(qū)draggable/allowDrop/onDrop。一個組件同時承擔三條職責看起來重但仔細想想這些職責都圍繞媒體這一個主題把它們內(nèi)聚在一起反而讓發(fā)布頁的其他部分文本區(qū)、工具欄保持純凈。當多個職責高度耦合于同一份數(shù)據(jù)時內(nèi)聚優(yōu)于拆分——這是組件設(shè)計里高內(nèi)聚的正面案例。下一篇輪到文字區(qū)——標題與正文的EditorComponent。本文引用源碼entry/src/main/ets/view/contentEditor/AddMedia.ets、entry/src/main/ets/model/ContentInfo.ets、entry/src/main/ets/constants/CommonConstants.ets