本文旨在深入探討華為鴻蒙HarmonyOS Next系統（截止目前 API12）在開發多語言電商平臺方面的技術細節，基於實際開發實踐進行總結。主要作為技術分享與交流載體，難免錯漏，歡迎各位同仁提出寶貴意見和問題，以便共同進步。本文為原創內容，任何形式的轉載必須註明出處及原作者。
在鴻蒙 Next 系統的安全體系中，安全控制元件扮演著至關重要的角色，為應用提供了便捷且安全的使用者互動方式，有效保護使用者隱私。今天，我們將聚焦於其中的貼上控制元件和儲存控制元件，深入剖析它們的功能與使用方法。
一、貼上控制元件：簡化剪貼簿資料讀取
（一）貼上控制元件的作用
貼上控制元件是一種特殊的系統安全控制元件，其主要功能是在使用者授權的情況下，實現應用無提示地讀取剪貼簿資料。在日常使用中，我們經常需要在不同應用之間複製和貼上資訊，如複製驗證碼、文字段落等。貼上控制元件的出現，使得這一過程更加流暢和便捷，同時也保障了使用者資料的安全性。它就像是一座橋樑，在使用者明確授權的前提下，安全地將剪貼簿中的資料傳遞給應用，避免了彈窗提示對使用者操作的干擾。
（二）使用貼上控制元件讀取剪貼簿資料的方法
- 匯入依賴
首先，在應用的程式碼檔案中匯入與剪貼簿相關的依賴模組。例如：
import { pasteboard } from '@kit.BasicServicesKit';
這一步驟就像是準備好工具，確保應用能夠與剪貼簿進行互動。
- 新增貼上控制元件到介面
在應用的使用者介面佈局中新增貼上控制元件。貼上控制元件通常以按鈕的形式呈現，由圖示、文字和背景組成，其中圖示和文字至少需要有一個，背景是必選的。例如：
@Entry
@Component
struct Index {
@State message: string = '';
build() {
Row() {
Column({ space: 10 }) {
TextInput({ placeholder: '請輸入驗證碼', text: this.message })
PasteButton()
.padding({ top: 12, bottom: 12, left: 24, right: 24 })
// 後續新增點選事件處理邏輯
}
.width('100%')
}
.height('100%')
}
}
在上述程式碼中，我們在一個包含輸入框的佈局中新增了貼上控制元件，為後續讀取剪貼簿資料並填充到輸入框做好準備。
- 處理貼上控制元件點選事件
當使用者點選貼上控制元件時，應用需要處理相應的點選事件，以獲取剪貼簿中的資料並進行處理。例如：
.onClick((event: ClickEvent, result: PasteButtonOnClickResult) => {
if (PasteButtonOnClickResult.SUCCESS === result) {
pasteboard.getSystemPasteboard().getData((err: BusinessError, pasteData: pasteboard.PasteData) => {
if (err) {
console.error(`Failed to get paste data. Code is ${err.code}, message is ${err.message}`);
return;
}
// 將剪貼簿內容設定為輸入框的文字
this.message = pasteData.getPrimaryText();
});
}
})
在點選事件處理函式中，透過pasteboard.getSystemPasteboard().getData()方法獲取剪貼簿資料。如果獲取成功，將資料中的主要文字內容設定為輸入框的文字，實現了快速貼上功能。
（三）貼上控制元件使用限制和開發步驟表格展示
| 使用限制 | 開發步驟 |
|---|---|
| 臨時授權會持續到滅屏、應用切後臺、應用退出情況發生。 應用在授權期間沒有呼叫次數限制。 為保障使用者隱私，應用需確保安全控制元件可見且使用者能識別，避免因控制元件樣式問題導致授權失敗。 |
1. 匯入剪貼簿依賴。 2. 新增輸入框和貼上控制元件到介面。 3. 處理貼上控制元件點選事件，獲取並處理剪貼簿資料。 |
（四）示例程式碼：使用貼上控制元件讀取驗證碼
以下是一個完整的使用貼上控制元件讀取驗證碼的示例程式碼：
import { pasteboard, BusinessError } from '@kit.BasicServicesKit';
import { Component, State, ClickEvent, PasteButtonOnClickResult } from '@ohos.arkui.extension.component';
@Entry
@Component
struct Index {
@State message: string = '';
build() {
Row() {
Column({ space: 10 }) {
TextInput({ placeholder: '請輸入驗證碼', text: this.message })
PasteButton()
.padding({ top: 12, bottom: 12, left: 24, right: 24 })
.onClick((event: ClickEvent, result: PasteButtonOnClickResult) => {
if (PasteButtonOnClickResult.SUCCESS === result) {
pasteboard.getSystemPasteboard().getData((err: BusinessError, pasteData: pasteboard.PasteData) => {
if (err) {
console.error(`Failed to get paste data. Code is ${err.code}, message is ${err.message}`);
return;
}
this.message = pasteData.getPrimaryText();
});
}
})
}
.width('100%')
}
.height('100%')
}
}
在這個示例中，使用者在輸入驗證碼的輸入框旁點選貼上控制元件，應用將讀取剪貼簿中的資料並填充到輸入框中，方便使用者快速輸入驗證碼。
二、儲存控制元件：便捷檔案儲存到媒體庫
（一）儲存控制元件的作用
儲存控制元件為應用提供了一種快速、便捷的方式將檔案儲存到媒體庫中。與傳統的儲存方式相比，它無需使用者手動選擇儲存路徑，而是直接將檔案儲存到指定的媒體庫路徑，大大提高了操作效率。無論是儲存圖片、影片還是其他型別的檔案，儲存控制元件都能在使用者點選後迅速完成儲存操作，同時確保了操作的安全性和許可權的合理控制。
（二）使用儲存控制元件儲存檔案到媒體庫的方法
- 匯入相關依賴
在使用儲存控制元件之前，需要匯入與檔案操作和媒體庫訪問相關的依賴模組。例如：
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { fileIo } from '@kit.CoreFileKit';
這些依賴模組提供了訪問媒體庫和進行檔案讀寫操作的必要功能。
- 設定要儲存的檔案資源並新增儲存控制元件
首先，確定要儲存的檔案資源，並在應用介面中新增儲存控制元件。例如，以下程式碼展示瞭如何在一個包含圖片的介面中新增儲存控制元件：
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { fileIo } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { promptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct Index {
build() {
Row() {
Column({ space: 10 }) {
// 假設這裡有一個圖片資源，實際應用中應替換為真實的圖片資源
Image($r('app.media.startIcon'))
.height(400)
.width('100%')
SaveButton()
.padding({ top: 12, bottom: 12, left: 24, right: 24 })
// 後續新增點選事件處理邏輯
}
.width('100%')
}
.height('100%')
.backgroundColor(0xF1F3F5)
}
}
在上述程式碼中，我們在顯示圖片的介面中新增了儲存控制元件，以便使用者在檢視圖片後能夠方便地儲存圖片到媒體庫。
- 處理儲存控制元件點選事件
當使用者點選儲存控制元件時，應用需要處理點選事件，執行儲存檔案到媒體庫的操作。例如：
.onClick(async (event: ClickEvent, result: SaveButtonOnClickResult) => {
if (result === SaveButtonOnClickResult.SUCCESS) {
const context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
let helper = photoAccessHelper.getPhotoAccessHelper(context);
try {
// 建立圖片檔案，這裡使用預設的圖片型別和格式，實際應用中可根據需求調整
let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'jpg');
// 開啟檔案，準備寫入內容
let file = await fileIo.open(uri, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE);
// 假設這裡有一個圖片資源，實際應用中應替換為真實的圖片資源
context.resourceManager.getMediaContent($r('app.media.startIcon').id, 0)
.then(async value => {
let media = value.buffer;
// 將圖片資料寫入媒體庫檔案
await fileIo.write(file.fd, media);
await fileIo.close(file.fd);
promptAction.showToast({ message: '已儲存至相簿!' });
});
} catch (error) {
const err: BusinessError = error as BusinessError;
console.error(`Failed to save photo. Code is ${err.code}, message is ${err.message}`);
}
} else {
promptAction.showToast({ message: '設定許可權失敗!' });
}
})
在點選事件處理函式中，首先獲取應用上下文，然後透過photoAccessHelper建立圖片檔案的資源路徑（uri），接著使用fileIo開啟檔案並寫入圖片資料。如果儲存成功，顯示提示資訊告知使用者檔案已儲存到相簿；如果儲存失敗，顯示相應的錯誤資訊。
（三）儲存控制元件使用限制和開發步驟表格展示
| 使用限制 | 開發步驟 |
|---|---|
| 當使用者首次點選儲存控制元件，系統將彈窗請求使用者授權，若點選“取消”，再次點選會重新彈窗；點選“允許”，應用將被授予臨時儲存許可權，此後點選不再彈窗。 應用在 onClick()觸發回撥到呼叫媒體庫特權介面的時間間隔不能大於 10 秒。 使用者點選一次控制元件，僅獲取一次授權呼叫。 為保障使用者隱私，應用需確保安全控制元件可見且使用者能識別，避免因控制元件樣式問題導致授權失敗。 |
1. 匯入檔案和媒體庫依賴。 2. 設定圖片資源（或其他檔案資源），並新增儲存控制元件。 3. 處理儲存控制元件點選事件，執行儲存檔案到媒體庫的操作。 |
（四）示例程式碼：使用儲存控制元件儲存照片
以下是一個使用儲存控制元件儲存照片的完整示例程式碼：
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { fileIo } from '@kit.CoreFileKit';
import { common } from '@kit.AbilityKit';
import { promptAction } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';
@Entry
@Component
struct Index {
build() {
Row() {
Column({ space: 10 }) {
// 假設這裡有一個圖片資源，實際應用中應替換為真實的圖片資源
Image($r('app.media.startIcon'))
.height(400)
.width('100%')
SaveButton()
.padding({ top: 12, bottom: 12, left: 24, right: 24 })
.onClick(async (event: ClickEvent, result: SaveButtonOnClickResult) => {
if (result === SaveButtonOnClickResult.SUCCESS) {
const context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;
let helper = photoAccessHelper.getPhotoAccessHelper(context);
try {
// 建立圖片檔案，這裡使用預設的圖片型別和格式，實際應用中可根據需求調整
let uri = await helper.createAsset(photoAccessHelper.PhotoType.IMAGE, 'jpg');
// 開啟檔案，準備寫入內容
let file = await fileIo.open(uri, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE);
// 假設這裡有一個圖片資源，實際應用中應替換為真實的圖片資源
context.resourceManager.getMediaContent($r('app.media.startIcon').id, 0)
.then(async value => {
let media = value.buffer;
// 將圖片資料寫入媒體庫檔案
await fileIo.write(file.fd, media);
await fileIo.close(file.fd);
promptAction.showToast({ message: '已儲存至相簿!' });
});
} catch (error) {
const err: BusinessError = error as BusinessError;
console.error(`Failed to save photo. Code is ${err.code}, message is ${err.message}`);
}
} else {
promptAction.showToast({ message: '設定許可權失敗!' });
}
})
}
.width('100%')
}
.height('100%')
.backgroundColor(0xF1F3F5)
}
}
在這個示例中，使用者在檢視圖片時，點選儲存控制元件，應用將圖片儲存到媒體庫（相簿）中，並顯示相應的提示資訊告知使用者儲存結果。
總之，貼上控制元件和儲存控制元件為鴻蒙 Next 應用提供了更加便捷、安全的使用者互動功能。我們透過合理運用這些控制元件，能夠提升應用的使用者體驗，同時遵循系統的安全規範，保護使用者隱私。希望本文能夠幫助各位同行者深入理解和熟練運用貼上控制元件和儲存控制元件，為使用者打造更加出色的應用。