博客 / 詳情

返回

鴻蒙開發終極指南：13種碼圖一鍵生成，從基礎實現到自定義全解析

目錄

  • 前言
  • 碼圖技術概述
  • 關於文本生成碼圖
  • 核心使用場景深度解析
  • 文本生成碼圖的約束與限制
  • 手把手實現文本生成碼圖
  • 自定義碼圖：樣式、尺寸與個性化配置
  • 結束語

前言

在數字化浪潮席捲全球的今天，碼圖（二維碼與條形碼的統稱）已成為連接物理世界與數字信息的核心橋樑。從日常購物的掃碼支付、快遞物流的單號追蹤，到政務服務的掃碼認證、企業內部的數據流轉，碼圖憑藉“快速識別、高效傳參”的特性，滲透到生活與工作的每一個場景。尤其是隨着鴻蒙生態的持續擴張，原生應用對碼圖功能的需求呈爆發式增長。無論是社交應用的信息分享、辦公應用的文件傳輸，還是物聯網設備的配網激活，都離不開文本到碼圖的快速轉換。值得一提的是，HarmonyOS為開發者提供了高度封裝、功能強大的原生API支持，無需依賴第三方庫，就能輕鬆實現從文本到13種主流碼圖的生成，極大降低了開發門檻，那麼接下來就來詳細分享一下。

碼圖技術概述

碼圖技術本質是一種“數據可視化編碼”方案，通過特定的圖形排列規則，將文本、數字等結構化/非結構化數據轉換為機器可識別的圖形符號，核心分為二維碼與條形碼兩大類別：

  • 條形碼：以黑白條紋的寬度變化編碼數據，結構簡單、識別速度快，但存儲容量有限，主要用於商品標識、物流單號等場景；
  • 二維碼：以矩陣式的黑白方塊組合編碼數據，存儲密度遠超條形碼，支持中文、特殊符號等複雜內容，且具備容錯能力，成為當前主流的碼圖形式。

在HarmonyOS生態中，碼圖生成能力進一步升級：不僅覆蓋二維碼、條形碼的全場景需求，還支持自定義碼圖尺寸、邊距等參數，開發者可根據業務場景靈活選擇編碼類型，將任意合法字符串快速轉換為標準化或個性化的碼圖。

關於文本生成碼圖

在HarmonyOS原生應用開發中，文本生成碼圖的核心邏輯是“參數配置+API調用”，整個流程簡潔高效，無需複雜的編碼算法實現，具體分為四大關鍵步驟：

  1. 集成碼圖生成庫：HarmonyOS通過@kit.ScanKit等官方套件提供原生碼圖生成能力，無需額外引入第三方依賴，直接導入相關模塊即可使用；
  2. 配置碼圖核心參數：根據業務需求設置關鍵參數，包括碼圖類型、待編碼文本內容、碼圖尺寸（寬高）、邊距等；
  3. 調用API生成碼圖：通過generateBarcode.createBarcode接口，傳入配置參數，即可快速生成PixelMap格式的碼圖對象；
  4. 碼圖的顯示與拓展使用：將生成的PixelMap對象通過Image組件在界面展示，或進一步用於保存本地、分享給其他應用、打印輸出等場景。

這一流程的核心優勢在於“原生適配+低代碼”，官方API已處理好編碼算法、兼容性優化等底層邏輯，開發者只需聚焦業務參數配置，即可快速落地功能。

核心使用場景深度解析

基於HarmonyOS文本生成碼圖的靈活特性，其應用場景幾乎覆蓋所有需要“高效信息傳遞”的業務場景，以下是最具代表性的落地場景：

  1. 信息快速分享場景：將聯繫人信息、WiFi賬號密碼、網頁鏈接、地理位置等文本數據生成碼圖，用户掃碼即可快速獲取，無需手動輸入。例如社交應用中“掃碼加好友”、辦公應用中“掃碼傳文件”；
  2. 設備互聯場景：在鴻蒙生態的多設備協同中，生成手機克隆碼圖，舊設備掃碼即可快速向新設備遷移數據；物聯網設備配網時，將WiFi信息、設備ID生成碼圖，設備掃碼即可完成聯網激活；
  3. 商業服務場景：電商應用中生成訂單支付碼、線下門店的會員碼、票務應用的電子票碼；
  4. 數據驗證場景：企業內部系統中，將員工工號、部門信息生成碼圖，用於考勤打卡、門禁通行；物流應用中，將運單號生成碼圖，用於包裹分揀、簽收確認；
  5. 個性化展示場景：將品牌名稱、Slogan、活動主題等文本生成碼圖，用於宣傳物料、產品包裝，用户掃碼可跳轉至活動頁面、官網等，提升品牌互動性。

例如將“HarmonyOS”字符串生成QR Code碼圖，可用於技術分享會的宣傳物料，參會者掃碼即可獲取鴻蒙開發資料合集，實現“一物一碼”的精準觸達。

文本生成碼圖的約束與限制

HarmonyOS原生支持13種主流碼圖類型，每種類型因編碼規則不同，對輸入內容、字符長度、數據格式等參數有明確約束。以下是官方規範的詳細説明，開發者需根據業務場景選擇適配的碼圖類型：
image.png

除上述類型專屬約束外，還有3個通用限制需重點注意：

  1. 顏色與背景約束：建議使用默認配置（黑色碼圖+白色背景），碼圖與背景的對比度直接影響識別率。若需自定義顏色，需確保對比度≥3:1（例如深綠色碼圖+白色背景），避免使用淺色系、相近色系組合；
  2. 邊距約束：默認邊距為1px，取值範圍為[1, 10]px。邊距過小會導致碼圖與周圍元素混淆，影響識別；邊距過大則浪費顯示空間，建議根據界面佈局靈活調整；

  3. 尺寸約束：

    • 二維碼類（QR Code、Data Matrix、Aztec）：寬高需保持一致，且取值範圍為[200, 4096]px，小於200px會因像素不足導致識別失敗；
    • 條形碼類（EAN-8、EAN-13、UPC-A、UPC-E、Codabar、Code 39、Code 93、Code 128、ITF-14、PDF417）：建議寬高比為2:1（例如寬度400px、高度200px），且寬度需≥400px，否則會因條紋過窄影響掃描識別。

手把手實現文本生成碼圖

以下將以最常用的QR Code為例，詳細拆解文本生成碼圖的完整實現步驟，包含模塊導入、API調用（兩種回調方式）、界面展示等核心環節，代碼可直接複製到鴻蒙應用中使用：

步驟1：導入核心模塊

首先需導入碼圖生成、錯誤處理、圖片處理、日誌打印相關的官方模塊，這些模塊是實現功能的基礎：

// 導入碼圖生成核心接口模塊
import { scanCore, generateBarcode } from '@kit.ScanKit';
// 導入業務錯誤處理模塊
import { BusinessError } from '@kit.BasicServicesKit';
// 導入圖片處理模塊
import { image } from '@kit.ImageKit';
// 導入日誌模塊
import { hilog } from '@kit.PerformanceAnalysisKit';

步驟2：調用碼圖生成接口

HarmonyOS提供Promise和Callback兩種回調方式，開發者可根據代碼風格選擇適配的方式，兩種方式的核心功能一致，僅回調邏輯不同：

方式1：通過Promise方式回調

@Entry
@Component
struct Index {
  // 用於存儲生成的碼圖對象，初始值為undefined
  @State pixelMap: image.PixelMap | undefined = undefined

  build() {
    // 垂直佈局，居中展示按鈕和碼圖
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      // 生成碼圖的觸發按鈕
      Button('generateBarcode Promise')
        .onClick(() => {
          // 重置碼圖對象，避免重複顯示舊碼圖
          this.pixelMap = undefined;
          // 待編碼的文本內容（可替換為任意符合QR Code約束的文本，如鏈接、聯繫人信息等）
          let content: string = 'huawei';
          // 碼圖配置參數
          let options: generateBarcode.CreateOptions = {
            scanType: scanCore.ScanType.QR_CODE, // 碼圖類型：QR Code
            height: 400, // 碼圖高度（與寬度一致，符合二維碼尺寸約束）
            width: 400   // 碼圖寬度
            // 可選參數：margin（邊距），默認1px，如需調整可添加：margin: 2
          }
          try {
            // 調用碼圖生成API，傳入文本內容和配置參數
            generateBarcode.createBarcode(content, options)
              .then((pixelMap: image.PixelMap) => {
                // 生成成功，將返回的PixelMap對象賦值給狀態變量
                this.pixelMap = pixelMap;
                hilog.info(0x0000, 'BarcodeGenerate', '碼圖生成成功');
              })
              .catch((error: BusinessError) => {
                // 生成失敗，打印錯誤信息（錯誤碼+錯誤描述）
                hilog.error(0x0000, 'BarcodeGenerate', `碼圖生成失敗：錯誤碼${error.code}，錯誤信息${error.message}`);
              })
          } catch (error) {
            // 捕獲其他異常（如參數格式錯誤）
            hilog.error(0x0000, 'BarcodeGenerate', `未知錯誤：${JSON.stringify(error)}`);
          }
        })
        .margin({ bottom: 30 }) // 按鈕與碼圖區域的間距

      // 碼圖生成成功後，通過Image組件展示
      if (this.pixelMap) {
        Image(this.pixelMap)
          .width(300) // 展示寬度（可根據界面需求調整，建議不小於200px）
          .height(300) // 展示高度（與寬度一致）
          .objectFit(ImageFit.Contain) // 保持碼圖比例，避免拉伸變形
      }
    }
    .width('100%') // 佈局佔滿屏幕寬度
    .height('100%') // 佈局佔滿屏幕高度
  }
}

方式2：通過Callback方式回調

@Entry
@Component
struct Index {
  @State pixelMap: image.PixelMap | undefined = undefined

  build() {
    Flex({ direction: FlexDirection.Column, alignItems: ItemAlign.Center, justifyContent: FlexAlign.Center }) {
      Button('generateBarcode Callback')
        .onClick(() => {
          let content = 'huawei';
          let options: generateBarcode.CreateOptions = {
            scanType: scanCore.ScanType.QR_CODE,
            height: 400,
            width: 400
          }
          try {
            // 回調方式調用API，第三個參數為回調函數
            generateBarcode.createBarcode(content, options, (error: BusinessError, pixelMap: image.PixelMap) => {
              // 若存在錯誤，打印信息並返回
              if (error) {
                hilog.error(0x0000, 'BarcodeGenerate', `碼圖生成失敗：錯誤碼${error.code}，錯誤信息${error.message}`);
                return;
              }
              // 生成成功，賦值並展示
              this.pixelMap = pixelMap;
              hilog.info(0x0000, 'BarcodeGenerate', '碼圖生成成功');
            })
          } catch (error) {
            hilog.error(0x0000, 'BarcodeGenerate', `未知錯誤：${JSON.stringify(error)}`);
          }
        })
        .margin({ bottom: 30 })

      if (this.pixelMap) {
        Image(this.pixelMap)
          .width(300)
          .height(300)
          .objectFit(ImageFit.Contain)
      }
    }
    .width('100%')
    .height('100%')
  }
}

步驟3：特別説明：關於模擬器使用限制

需重點注意：當前HarmonyOS模擬器暫不支持文本生成碼圖功能，若在模擬器中調用上述代碼，會返回錯誤信息“Emulator is not supported.”。建議開發者使用真實鴻蒙設備進行功能調試與測試，確保功能正常落地。

自定義碼圖：樣式、尺寸與個性化配置

基礎碼圖生成滿足通用需求，而在實際業務中，往往需要根據品牌風格、界面設計進行個性化定製。以下是最常用的自定義方向及實現思路：

1. 自定義碼圖顏色與背景

默認碼圖為黑色前景、白色背景，若需調整顏色，可在CreateOptions中添加foregroundColor（前景色）和backgroundColor（背景色）參數，支持RGB、RGBA格式的顏色值：

let options: generateBarcode.CreateOptions = {
  scanType: scanCore.ScanType.QR_CODE,
  height: 400,
  width: 400,
  foregroundColor: '#0066CC', // 碼圖前景色（藍色）
  backgroundColor: '#F5F5F5', // 碼圖背景色（淺灰色）
  margin: 3 // 邊距調整為3px
};

注意：顏色組合需保證足夠對比度，避免使用“淺藍+白色”“深灰+黑色”等低對比度組合，否則會嚴重影響識別率。

2. 動態調整碼圖尺寸

根據不同設備屏幕尺寸、界面佈局，可動態計算碼圖寬高。例如根據屏幕寬度的80%設置碼圖尺寸，確保在不同設備上顯示效果一致：

// 獲取屏幕寬度
const screenWidth = px2vp(viewport.getWindowSize().width);
// 碼圖寬度設為屏幕寬度的80%，二維碼需保持寬高一致
const barcodeSize = screenWidth * 0.8;

let options: generateBarcode.CreateOptions = {
  scanType: scanCore.ScanType.QR_CODE,
  height: barcodeSize,
  width: barcodeSize
};

3. 多碼圖類型切換

若應用需支持多種碼圖類型，可通過下拉菜單或單選按鈕讓用户選擇，動態切換scanType參數：

// 定義支持的碼圖類型列表
const barcodeTypes = [
  { label: 'QR Code', type: scanCore.ScanType.QR_CODE },
  { label: 'Code 128', type: scanCore.ScanType.CODE_128 },
  { label: 'EAN-13', type: scanCore.ScanType.EAN_13 }
];

@State selectedType: scanCore.ScanType = scanCore.ScanType.QR_CODE;

// 界面中添加單選按鈕組
RadioGroup() {
  ForEach(barcodeTypes, (item) => {
    Radio(item.label)
      .value(item.type === this.selectedType)
      .onChange(() => {
        this.selectedType = item.type;
      });
  });
}

// 生成碼圖時使用選中的類型
let options: generateBarcode.CreateOptions = {
  scanType: this.selectedType,
  // 條形碼需調整寬高比為2:1
  height: this.selectedType === scanCore.ScanType.QR_CODE ? 400 : 200,
  width: 400
};

4. 碼圖保存與分享

生成碼圖後，可通過image模塊的API將PixelMap對象保存為圖片文件，或分享給其他應用：

// 保存碼圖到本地（需申請文件讀寫權限）
async function saveBarcode(pixelMap: image.PixelMap) {
  const filePath = `${getContext().filesDir}/barcode.png`;
  try {
    const file = await fs.open(filePath, fs.OpenMode.WRITE_ONLY | fs.OpenMode.CREATE);
    await image.encodeToFile(pixelMap, image.Format.PNG, file.fd);
    await file.close();
    hilog.info(0x0000, 'BarcodeSave', `碼圖保存成功：${filePath}`);
  } catch (error) {
    hilog.error(0x0000, 'BarcodeSave', `碼圖保存失敗：${JSON.stringify(error)}`);
  }
}

// 調用保存函數（在碼圖生成成功後調用）
generateBarcode.createBarcode(content, options)
  .then((pixelMap: image.PixelMap) => {
    this.pixelMap = pixelMap;
    saveBarcode(pixelMap); // 保存碼圖
  });

結束語

文本生成碼圖作為HarmonyOS原生開發的高頻實用功能，憑藉“原生適配、低代碼實現、多類型支持”的優勢，成為連接用户、設備、服務的重要橋樑。通過本文的詳細拆解，從技術原理、場景落地到代碼實現、個性化定製，相信開發者已能輕鬆掌握這一功能的核心邏輯。在實際開發中，建議大家根據業務場景選擇適配的碼圖類型，嚴格遵循官方約束規範，確保功能的穩定性與用户體驗。最後希望本文能為大家提供實用的技術參考，助力大家在鴻蒙生態開發中快速落地優質功能！

harmonyos-sdk , harmonyos-next , harmonyos先行者 , harmonyos
user avatar
0 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.