如何在 C# 中控制 2D 條碼的 UTF-8 ECI 標記

Ahmad Sohail
Ahmad Sohail
已更新: 2026年9月9日

生成的 2D 條碼尺寸與預期不同、舊款掃描器無法識別曾經可以讀取的符號,以及標準要求每個符號都必須宣告其編碼,這些問題歸根結底都是一個問題:條碼是否帶有 UTF-8 ECI (擴展通道解釋) 標頭?

該標頭告訴掃描器將內容解釋為 UTF-8,這對於中文、阿拉伯文、泰文或其他非 ASCII 字元的內容很重要。 這不是免費的。 標頭會消耗代碼字,這樣已經接近大小界限的內容可能會溢出到更大的符號,而在 ECI 存在之前構建的掃描器則會拒絕攜帶標頭的符號。 因此,IronBarcode 只在數據包含非 ASCII 字元時才寫入標頭,而 EciMode 設置則會在任一方向覆蓋該決定。

請注意: 需要 IronBarcode 2026.9.2 或更高版本。 API 不存在於 2026.8.6 或更早的版本中,在這些版本中,該呼叫會產生編譯錯誤而不是運行時故障。
快速入門:為每個 2D 條碼設置 ECI 策略

設置一次策略,然後像平常一樣生成條碼。 每個 2D 格式都遵循該策略,無需進一步參數。

  1. 1使用 IronBarcode 安裝 NuGet Package Manager

    PM > Install-Package BarCode

  2. 2複製並運行這段程式碼。

    IronBarCode.BarcodeWriter.DefaultEciMode = IronBarCode.EciMode.ForceUtf8;
    IronBarCode.BarcodeWriter.CreateBarcode("BK005|8389|0001", IronBarCode.BarcodeEncoding.QRCode).SaveAsPng("part-qr.png");
  3. 3部署到您的生產環境進行測試

    立即在您的項目中開始使用 IronBarcode,並使用 免費試用
    arrow pointer


IronBarcode 何時添加 ECI 標頭?

您已經撰寫的呼叫不會發生變化。 從 ASCII 部件號生成 DataMatrix,符號不帶標頭; 將相同的方法用於帶有變音符號的內容,標頭將出現,因為該值需要它。 呼叫中的 EciMode 參數會覆蓋該判斷。

using IronBarCode;

// Pure ASCII: no ECI header, smallest symbol
var ascii = DataMatrixWriter.CreateDataMatrix("BK005|8389|0001");
ascii.SaveAsPng("part-ascii.png");

// Non-ASCII: header written automatically
var unicode = DataMatrixWriter.CreateDataMatrix("BK005|8389|Bauteil-Größe");
unicode.SaveAsPng("part-unicode.png");

// Same ASCII value, header forced on
var tagged = DataMatrixWriter.CreateDataMatrix("BK005|8389|0001", 500, EciMode.ForceUtf8);
tagged.SaveAsPng("part-tagged.png");

上面三個符號只在內容和是否提供了模式上有所不同。 下面的圖像按固定模塊大小繪製,因此符號在總體大小上有所不同,就像打印標籤上的一樣。

在 EciMode.Auto 下編碼 ASCII 零件編號的 DataMatrix,為不含 ECI 標頭的 16×16 模組符號

ASCII, Auto - 16 × 16 模塊,無標頭

在 EciMode.Auto 下編碼含德文變音字母零件編號的 DataMatrix,為帶有 UTF-8 ECI 標頭的 22×22 模組符號

非 ASCII, Auto - 22 × 22 模塊,添加了標頭

在 EciMode.ForceUtf8 下編碼相同 ASCII 零件編號的 DataMatrix,為與純 ASCII 版本相同大小的 16×16 模組符號

ASCII, ForceUtf8 - 16 × 16 模塊,強制標頭


無論是否強制,有無標頭 ASCII 內容均編碼為 16 × 16 網格:此特定值具有足夠的額外容量,使得額外的代碼字不會增加成本。 非 ASCII 的內容需要完整一個等級的大小,更大的 22 × 22,因為標頭和多字節內容一起不再適合 16 × 16。當內容已接近大小界限時,標頭才會擴大符號,這對於給定的值是否如此,從字串本身是看不出來的。

三種 ECI 模式是什麼?

  • Auto: 只有當數據包含非 ASCII 字元時才寫入 UTF-8 ECI 標頭。 這是默認值,生成純 ASCII 內容時產生最小的符號。
  • ForceUtf8: 總是寫入標頭,包括純 ASCII。 用於嚴格的標準合規性,或每個符號必須聲明其編碼的情況。
  • Off: 從不寫入標頭。 僅在數據確定為 ASCII 或 Latin-1,且解碼器無法理解 ECI 時使用。
請注意: ECI 僅適用於 2D 格式。 EciMode 對於 Code 128、EAN 或 UPC 等 1D 條碼沒有影響。

如何設置 ECI 模式?

如何在整個應用程序中應用一個政策?

BarcodeWriter.DefaultEciMode 是 BarcodeWriter 上的公共靜態字段,默認為 EciMode.Auto。 一次設置,每個應用程序生成的 2D 條碼都會遵循它,無論是哪種格式以及代碼庫的哪個部分生成的。 它反映了現有的 BarcodeWriter.DefaultCharacterEncoding 字段:

using IronBarCode;

// Set once at startup
BarcodeWriter.DefaultEciMode = EciMode.Off;

// No mode argument passed anywhere below
GeneratedBarcode label = CreatePartLabel("BK005|8389|0001");
label.SaveAsPng("part-label.png");

GeneratedBarcode ticket = BarcodeWriter.CreateBarcode("TKT-77120", BarcodeEncoding.Aztec);
ticket.SaveAsPng("gate-ticket.png");

static GeneratedBarcode CreatePartLabel(string partNumber)
{
    // Follows DefaultEciMode
    return DataMatrixWriter.CreateDataMatrix(partNumber, 300);
}

如何覆蓋單個 DataMatrix 的模式?

每次呼叫 的 EciMode 在 CreateDataMatrix 重載中勝過 BarcodeWriter.DefaultEciMode,並僅應用於該次呼叫。

using IronBarCode;

// Application-wide policy
BarcodeWriter.DefaultEciMode = EciMode.Auto;

// Per-call override wins
var compliance = DataMatrixWriter.CreateDataMatrix("LOT-4471-A", 200, EciMode.ForceUtf8);
compliance.SaveAsPng("compliance-label.png");

// No override; follows DefaultEciMode
var standard = DataMatrixWriter.CreateDataMatrix("LOT-4471-B", 200);
standard.SaveAsPng("standard-label.png");

每個接受 EciMode 的 CreateDataMatrix 重載都遵循相同的模式。 數據首先以string、byte[]或Stream的形式輸入。 接下來是大小設置,或者是一個單一的像素大小,或者是一個明確寬度和高度的 DataMatrixWriter.DataMatrixShape。 EciMode 始終是最後一個參數。 上面的例子提供了一個大小;形狀重載在相同的最後位置採用相同的 EciMode:

using IronBarCode;

// Rectangular symbol, ECI forced on
var wide = DataMatrixWriter.CreateDataMatrix(
    "BK005|8389|0001",
    DataMatrixWriter.DataMatrixShape.Rectangular,
    400,
    100,
    EciMode.ForceUtf8);

wide.SaveAsPng("part-wide.png");

什麼控制 QR、Aztec 和 PDF417?

這三種格式沒有 EciMode 參數。 QRCodeWriter 上沒有這樣的參數,對通用的 BarcodeWriter.CreateBarcode 重載也沒有,所以 BarcodeWriter.DefaultEciMode 是唯一的控制方法。

using IronBarCode;

// QR, Aztec, PDF417: no per-call EciMode
BarcodeWriter.DefaultEciMode = EciMode.ForceUtf8;

var qr = BarcodeWriter.CreateBarcode("ORDER-88213", BarcodeEncoding.QRCode);
qr.SaveAsPng("order-qr.png");

var aztec = BarcodeWriter.CreateBarcode("ORDER-88213", BarcodeEncoding.Aztec);
aztec.SaveAsPng("order-aztec.png");

// New value applies to later calls
BarcodeWriter.DefaultEciMode = EciMode.Auto;

var qrAuto = BarcodeWriter.CreateBarcode("ORDER-88214", BarcodeEncoding.QRCode);
qrAuto.SaveAsPng("order-qr-auto.png");

當 QR 碼和 DataMatrix 在同一運行中需要不同的 ECI 行為時,DataMatrix 接受每次呼叫的參數,而 QR 碼則遵循靜態默認值。


設定在運行時如何表現?

DefaultEciMode 何時生效?

CreateBarcode、CreateDataMatrix和CreateQrCode返回的對象模式還未固定。 當條碼被保存或以其他方式渲染時,會讀取 DefaultEciMode,因此在運行期間分配新的值會影響之後保存的每個條碼,包括在更改之前創建的對象。

這會捕捉到常見的批次形狀:在呼叫之間更改 DefaultEciMode 後創建幾個條碼,然後在結尾一起保存。 它們都會採用最後設置的模式。保存每個條碼後再更改下一個條碼的模式,或者在每次呼叫中傳遞 EciMode 給 CreateDataMatrix,以使靜態默認無法達到。

警告: DefaultEciMode是一個可變的程式全域靜態,但不是執行緒安全的。 重新分配會立即被每個線程看到,因此在改變它時,當有其他線程正在生成或保存時,那個線程會在運行期間觀察到變更。 將它視為應用程序啟動政策,正如 BarcodeWriter.DefaultCharacterEncoding 一樣。

何時會拋出 EciMode.Off?

Off 是一個保證數據為 ASCII 的承諾。 打破此承諾會在兩個 BarcodeWriter.DefaultCharacterEncoding 設置下引發 IronBarCodeEncodingException。 UTF-8 默認情況下給出了更有用的信息:

IronBarCode Encoding Error for Barcode Format DataMatrix : EciMode.Off cannot be used with non-ASCII data while BarcodeWriter.DefaultCharacterEncoding is UTF-8, because the UTF-8 bytes require the ECI header to be decoded correctly and would otherwise be read as ISO-8859-1. Use EciMode.Auto or EciMode.ForceUtf8, or set BarcodeWriter.DefaultCharacterEncoding to a matching single-byte encoding.
Text

在 ISO_8859_1 下,這個相同的組合會顯示為一個低級的本機編碼器錯誤。

內容通常不完全受應用程序控制:用戶輸入、上游數據源、來自供應商目錄的產品名稱。 防禦性的包裝包圍了它:

using IronBarCode;
using IronBarCode.Exceptions;
using System;

public class LabelGenerator
{
    // Payload not guaranteed ASCII
    public bool TryCreateLabel(string payload, string outputPath)
    {
        try
        {
            var barcode = DataMatrixWriter.CreateDataMatrix(payload, 200, EciMode.Off);
            barcode.SaveAsPng(outputPath);
            return true;
        }
        catch (IronBarCodeEncodingException ex)
        {
            // Non-ASCII cannot round-trip without ECI
            Console.WriteLine("Payload is not ASCII, cannot generate with ECI disabled: {0}", ex.Message);
            return false;
        }
    }

    // Fall back to Auto
    public void CreateLabelWithFallback(string payload, string outputPath)
    {
        if (TryCreateLabel(payload, outputPath))
        {
            return;
        }

        var barcode = DataMatrixWriter.CreateDataMatrix(payload, 200, EciMode.Auto);
        barcode.SaveAsPng(outputPath);
    }
}

這裡的備份切換將該符號轉換為 Auto,認為正確的條碼到達支持 ECI 的掃描器勝過不帶條碼。 適當的恢復取決於部署:當掃描器確實無法讀取 ECI 時,拒絕記錄以進行人工處理是更安全的選擇。

該類型也在錯誤處理和調試指南中列出了該類型,該指南涵蓋了不包含此特定原因的異常家族。


如何選擇模式?

如何再次標記每個符號?

在啟動時,一行代碼:

using IronBarCode;

// Restore pre-2026.9.2 always-tagged output
BarcodeWriter.DefaultEciMode = EciMode.ForceUtf8;

// Both symbols carry the header
var dataMatrix = DataMatrixWriter.CreateDataMatrix("SKU-10045", 200);
dataMatrix.SaveAsPng("sku-datamatrix.png");

var qr = BarcodeWriter.CreateBarcode("SKU-10045", BarcodeEncoding.QRCode);
qr.SaveAsPng("sku-qr.png");

ForceUtf8 將每種 2D 格式返回到始終標記的行為,對於相同的輸入,生成與 2026.8.6 及更早版本字節相同的輸出。 這是針對那些下游系統建立在標記輸出上的應用程序的正確選擇,用於需要每個符號明確編碼聲明的標準,或者僅僅作為在評估其影響時推遲更改的方法。

反過來的情況也值得命名。 升級後發現其符號變小並對此感到滿意的應用程序不需要採取任何行動:Auto 已經是默認值。

哪種模式適合哪種情況?

按場景推薦的 ECI 模式,以及每個模式的配置位置

工作場景ECI 模式設置位置
通用生成,混合內容Auto無需操作; 這是默認值
老舊掃描器艦隊對 ECI 失效OffDefaultEciMode 在啟動時
標準要求每個符號的明確編碼ForceUtf8DefaultEciMode 在啟動時
一個符合性符號中,其他輸出為正常ForceUtf8每次呼叫,僅限 DataMatrix
內容不保證為 ASCIIAuto,或 Off 並帶有捕獲任意,有異常處理

下一步去向

這裡描述的行為是一個有三個值的設置,大多數應用程序設置一次後便不會再次進行。 值得有意識地做出的兩個決定是掃描器遺產是否理解 ECI,並且下游是否有標準要求每個符號聲明。

若要了解哪些條碼格式首先支持 Unicode 內容,請參見撰寫 UTF-8 和 Unicode 條碼操作指南,其中涵蓋了格式層面的 Unicode 支持,並提供了這裡的 ECI 詳細信息。 要生成 2D 格式本身,創建 2D 條碼指南涵蓋了 DataMatrix、QR、Aztec 和 PDF417 的生成。 完整的類文檔位於IronBarcode API 參考。

Ahmad 是一位全端開發人員,精通 C#、Python 和 Web 技術。他對建立可擴展的軟體解決方案有著濃厚的興趣,並樂於探索如何在實際應用中實現設計與功能的完美結合。

閱讀更多

準備好開始了嗎?

NuGet 下載次數 2,564,559版本:2026.11剛剛發布