Teknik Makale

Delphi'de CJK ve Emoji İçin Otomatik Font Fallback

Arial ile dizilmiş bir fatura şablonu, "Invoice for" yazıp sonra susuyor. Metin çağrısı 1 döndü, dosya doğrulandı ve metin çıkarma on karakter eksik geldi: 北京示例科技有限公司 içindeki her Han karakteri kaybolmuştu, çünkü Arial'in hiçbiri yoktu. PDF Library for Delphi'de otomatik font fallback varsayılan olarak açıktır ve bu tür karakterleri kurulu yüzlerden çeker; AddFontFallback kendi arama sıranızı ayarlar, JSON raporlu bir eksik glif politikası da hiçbir yüzün çizemediği her şeyle ilgilenir

Bu işi pahalıya çıkaran şey sessizliğidir. Bir taraf adının olması gereken yerde boşluk taşıyan bir PDF, her yapısal kontrolden geçer, her görüntüleyicide açılır ve genellikle test paketiniz tarafından değil, müşteri tarafından fark edilir

Desteklenmeyen metin neden hata vermek yerine kayboluyor?

Çünkü PDF'in, bir yazı tipinin bir karakteri reddetmesi diye bir kavramı yoktur; dolayısıyla eksik bir glif dosya düzeyinde hata değildir. Basit bir yazı tipi, tek baytlık kodları bir kodlama üzerinden glif adlarına eşler; bileşik bir yazı tipi kodları bir CMap üzerinden CID'lere, sonra glif indekslerine eşler. Bir yüzden içermediği bir şey isterseniz glif indeks sıfırına, .notdef'e düşersiniz; ISO 32000-1 §9.7.6.3 bunu tanımsız karakterler için standart sonuç sayar. Çoğu yüz .notdef'i hiçbir şey çizmemek olarak yorumlar. Bazıları boş bir kutu çizer

Her iki durumda da içerik akışı iyi biçimlidir ve sayfa işlenir. Spesifikasyonun hiçbir yerinde, üreticiden bir metin operatörü yazmadan önce kapsam kontrolü istenmez; bu yüzden kontrolü atlayan bir üretici, sessizce içerik kaybetmiş, uyumlu bir dosya üretir. Fallback ile raporlamanın bu yüzden birlikte anılması gerekir. Çözülebilecekleri çözmek işin yarısıdır; gerisini size söylemek öteki yarısıdır ve bize göre ad ya da tutar taşıyan her şey için daha önemlidir

PDF Library for Delphi'de fallback zincirini açmak

Fallback, yalnızca seçilen yazı tipi dizedeki bir karakteri gerçekten içermiyorsa devreye girer; bu yüzden yalnızca Latin metin normal yolunu izler ve fazladan hiçbir şey ödemez. Yeni bir TPDFlib örneğinde otomatik fallback zaten açıktır; çizim kodunun fazladan bir çağrıya ihtiyacı yoktur:

var
  Lib: TPDFlib;
begin
  Lib := TPDFlib.Create;
  try
    // Otomatik fallback varsayılan olarak açıktır: emoji, kana, Hangul,
    // Han ve semboller yerleşik bir aday tablosunda aranır
    Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_REPORT);

    Lib.AddTrueTypeFont('Arial', 2);   // 2 = alt küme olarak gömülür
    Lib.SetTextSize(11);
    Lib.DrawText(72, 720, 'Invoice for 北京示例科技有限公司');
    Lib.DrawText(72, 700, 'Delivery status: on time ✅');

    Lib.SaveToFile('invoice.pdf');
  finally
    Lib.Free;
  end;
end;

Otomatik fallback açıkken kütüphane, her çözülemeyen karakterin yazı sistemine göre aday seçer. Tablo sabittir ve Windows'a yöneliktir: emoji ve piktograflar önce Segoe UI Emoji, sonra Segoe UI Symbol, ardından Arial Unicode MS dener; kana önce Yu Gothic dener; Hangul önce Malgun Gothic dener; birleşik Han bloğu Microsoft YaHei, sonra Microsoft JhengHei, Yu Gothic, Malgun Gothic ve SimSun dener; matematik ve teknik semboller Segoe UI Symbol ile Cambria Math'a gider. Geri kalan her şey, Nirmala UI ve Segoe UI ile başlayan geniş bir listeye düşer

AddFontFallback ile kaydettiğiniz yüzler, o yerleşik tablodan önce, eklediğiniz sırayla denenir. SetAutomaticFontFallback(0) yalnızca yerleşik tabloyu kapatır: açık zincir etkin kalır; çıktının yalnızca onayladığınız yüzleri kullanmasını istediğinizde seçeceğiniz ayar budur. AddFontFallback, zaten listede olan bir adı yok sayar ve 1 tabanlı konumunu döndürür; ClearFontFallbacks, RemoveFontFallback ve GetFontFallbackCount, zinciri belgeler arasında yeniden kurmanızı sağlar

Han birleştirme tuzağı: paylaşılan karakterleri kim kazanır?

Çince, Japonca ve Korece, Unicode'daki Han ideograflarının çoğunu paylaşır, ama her yerel ayar çoğu için farklı harf biçimleri bekler. 直 ya da 骨 kod noktası, Tokyo adresiyle Beijing adresinde aynıdır; yerli okuyucunun beklediği biçim değildir. Bir fallback zinciri yalnızca "bu kod noktası için hangi kurulu yüzde glif var" sorusunu yanıtlar ve her CJK yüzünde bir glif vardır; dolayısıyla sırada ilk gelen yüz, paylaşılan her karakteri kazanır

Otomatik tablo, Han için Microsoft YaHei'yi öne koyar. Bu, basitleştirilmiş Çince için iyidir, Japonca için yanlıştır. O faturadaki bir Japonca adres, kana'sı Yu Gothic ile çizilmiş (kana aramayı önce Japonca yüzeye gönderir) ama kanji'si Çince biçimli YaHei ile çizilmiş olarak tek bir satırda çıkar. Hiçbir şey eksik değildir, rapor boştur ve Japon okuyucu hemen bir şeylerin ters olduğunu görür

Tavsiyemiz, Han için otomatik sıraya güvenmeyi bırakıp açık zinciri belgenin yerel ayarından kurmanız. Onu genellikle zaten bilirsiniz; müşteri kaydından ya da şablon dilinden:

procedure ConfigureFallback(Lib: TPDFlib; const Locale: string);
begin
  Lib.ClearFontFallbacks;
  if Locale = 'ja' then
  begin
    Lib.AddFontFallback('Yu Gothic');
    Lib.AddFontFallback('Meiryo');
  end
  else if (Locale = 'zh-TW') or (Locale = 'zh-HK') then
    Lib.AddFontFallback('Microsoft JhengHei')
  else if Locale = 'ko' then
    Lib.AddFontFallback('Malgun Gothic')
  else
    Lib.AddFontFallback('Microsoft YaHei');
  // Emoji, semboller ve yukarıda kapsanmayan her yazı sistemi yine
  // yerleşik adaylardan geçer; bunu yasaklamak için burada 0 geçirin
  Lib.SetAutomaticFontFallback(1);
end;

Her belge için, ilk DrawText'ten önce bir kez çağırın. Açık liste içindeki sıra da aynı şekilde önemlidir: bir karakteri kapsayan ilk yüz kazanır, dolayısıyla Arial Unicode MS gibi pan-Unicode bir yüz varsa en sona konmalıdır. Başa koyarsanız neredeyse her şeyi o çizer ve özenle seçtiğiniz yazı sistemi özel yüzler hiç sorgulanmaz

Fallback bütün kümelerde çalışır

PDF Library for Delphi, fallback kararını grafem kümesi başına verir; böylece bir küme her zaman tek bir yüzle çizilir. Bir Devanagari hecesi, ten tonu değiştiricili bir emoji, birleştirici aksanlı bir temel harf: her biri ekranda tek bir birimdir ve içindeki şekillendirme kararları tek bir belirli yazı tipinin tablolarından gelir. Yarısı Arial'den yarısı bir fallback yüzünden gelen bir küme, teknik olarak var olan ama görünürde bozuk bir glif sayfaya bırakır; bu, boşluktan da kötü sayılır

Seçilen yazı tipi dizeyi önce kendisi şekillendirir. Yalnızca glif sıfır olarak dönen kümeler başka bir yüz arar ve aynı yüze çözülen komşu kümeler tek akış olarak birlikte çizilir; böylece on karakterli bir Çince ad, on ayrı yazı tipi geçişi yerine tek bir YaHei akışı olur. Sağdan sola sıra da korunur: Arapça ya da İbranice metin içindeki bir fallback akışı, çift yönlü algoritmanın ona verdiği yerde durur. Aynı şekillendirme mekanizması, Japonca ve Çince için dikey yazımı da sürer

PDF Library for Delphi: Fallback zinciri şeması: bir CJK küme akışı birincil Arial yüzünü ıskalar, ilk kapsayan yedek olarak Microsoft YaHei ile çizilir ve kapsanmayan kümeler rapor ya da iptal politikasını izler
Bu küme akışı birincil yüzden ilk kapsayan yedeğe düşer ve yalnızca gerçekten kullanılan yüzler gömülür. Hiçbir yüzün çizemediği kümeler eksik glif politikasını izler: raporla ve sürdür ya da 521 hatasıyla iptal et

Eksik bir glif belgeyi durdurmalı mı?

Cevap belgenin amacına bağlıdır ve PDF Library for Delphi bunu SetMissingGlyphPolicy ile size bırakır. PDF_MISSING_GLYPH_REPORT varsayılandır: metin işlemi yola çıkar, hiçbir yüzün çizemediği karakterler çıktıdan düşürülür ve her biri kaydedilir. PDF_MISSING_GLYPH_ABORT, sayfaya bir şey yazılmadan bütün metin işlemini reddeder; DrawText 0 döndürür ve hata kodu 521 olur (PDFLIB_ERROR_MISSING_GLYPH)

Dahili toplu raporlar için rapor politikasını seçin ve boşlukları günlüğe yazın; bugün hafif eksik bir rapor, hiç rapor olmamasından iyidir. Sözleşmeler, faturalar, sertifikalar ve bir kişi ya da şirket adı taşıyan her şey için iptali seçin. Parti adında düşmüş bir karakter, kendi hattınızda yakalamak isteyeceğiniz bir kusurdur ve iptal yazmadan önce gerçekleştiği için sayfada yarım çizilmiş bir satır kalmaz

var
  Lib: TPDFlib;
  Err: Integer;
  Report: WideString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetMissingGlyphPolicy(PDF_MISSING_GLYPH_ABORT);
    Lib.AddTrueTypeFont('Arial', 2);
    Lib.SetTextSize(11);

    if Lib.DrawText(72, 660, CustomerName) <> 1 then
    begin
      Err := Lib.LastErrorCode;   // okumak aynı zamanda onu 0'a sıfırlar
      if Err = PDFLIB_ERROR_MISSING_GLYPH then
      begin
        Report := Lib.GetMissingGlyphReportJSON;
        // {"valid":false,"policy":1,"eventCount":1,"events":[
        //   {"sequence":1,"documentIndex":0,"page":1,"utf16Index":3,
        //    "codePoint":983041,"unicode":"U+F0001",
        //    "fontName":...,"fontType":...,"operation":"DrawText"}]}
        EscalateToOperator(Report);
      end;
    end;
  finally
    Lib.Free;
  end;
end;

Yerel değişkene dikkat. LastErrorCode okunduğunda kendini sıfırlar; bu yüzden bir yerde Lib.LastErrorCode = 0 kontrolü yapıp başka bir yerde Lib.LastErrorCode'u günlüğe yazan kod 0 yazar. Bir kez okuyun, değeri saklayın

Her rapor olayı sayfayı, dize içindeki UTF-16 indeksini, kod noktasını ondalık ve U+XXXX biçiminde, seçilen yazı tipini, türünü ve sorunla karşılaşan API çağrısını taşır. Bununla bir destek talebi, belirti tarif etmek yerine tam karakteri adlandırır. valid bayrağı yalnızca hiç olay kaydedilmemişse true'dur; bu, onu toplu bir işte ucuz bir geçit yapar

Kütüphane en son 256 olayı tutar ve eskilerini düşürür; böylece çizilemeyen metinle dolu bir belge, tanılamayı bellek sorununa çeviremez. Olaylar aynı TPDFlib örneğinde belgeler arasında birikir; dosya başına bir rapor istiyorsanız her belgeden önce ClearMissingGlyphReport çağırın ya da documentIndex alanıyla ayırın

Harflerde iptal, süste hoşgörü

Bütün belge için tek bir politika bazen fazla kabadır. Bir kargo etiketi, alıcının adının yanında süslü bir emoji taşıyabilir ve etiketi reddetmekten emojiyi kaybetmeyi tercih edersiniz. OnMissingGlyph olayı, zincirdeki hiçbir yüzün çizemediği her karakter için tetiklenir, politikayı varsayılan eylem olarak alır ve kod noktası başına geçersiz kılabilir:

type
  TGlyphGate = class
    procedure MissingGlyph(Sender: TObject; CodePoint: Cardinal;
      UTF16Index, Page: Integer; const FontName, Operation: WideString;
      var Action: Integer);
  end;

procedure TGlyphGate.MissingGlyph(Sender: TObject; CodePoint: Cardinal;
  UTF16Index, Page: Integer; const FontName, Operation: WideString;
  var Action: Integer);
begin
  // Piktograflar ve dingbatlar süstür: düşür ve kaydet
  if ((CodePoint >= $1F000) and (CodePoint <= $1FAFF)) or
     ((CodePoint >= $2600) and (CodePoint <= $27BF)) then
    Action := PDF_MISSING_GLYPH_REPORT
  else
    Action := PDF_MISSING_GLYPH_ABORT;   // harfler ve rakamlar kaybolmamalı
end;

// Bağlama
Gate := TGlyphGate.Create;
Lib.OnMissingGlyph := Gate.MissingGlyph;

Olay, fallback şansını tükettikten sonra çalışır; dolayısıyla yalnızca bu makinede gerçekten çözülemeyen karakterleri görür. İşleyicinin seçtiği eylem ne olursa olsun, her biri JSON raporuna düşer

Ölçme, gömme ve dağıtma

GetTextWidth, DrawText ile aynı küme küme fallback kararlarından geçer. Bu açık gelir ama ev yapımı fallback katmanlarının tam olarak yanlış yaptığı yer burasıdır: çizim çağrısını yamalar, ölçümü birincil yazı tipinde bırakırlar ve sağa hizalı her toplam ile tablo sütunu, sayfaya düşenle uyuşmayan genişliklerden hesaplanır. Burada çizimden önce ölçülen bir dize, fallback akışları dahil, ölçüldüğü genişliği kaplar; bu, fallback'i yalnızca elle denetlediğiniz şablonlarda değil her yerde açık tutmayı makul kılan şeydir

İptal politikası altında bir sonuç: ölçüm çözülemeyen bir karaktere çarptığında GetTextWidth 0 döndürür ve 521 hatasını ayarlar. Genişliğe bölme yapan ya da hücre boyutlandırmak için onu kullanan yerleşim kodu, sayıyı kullanmadan önce bunu kontrol etmelidir

Fallback yüzleri yalnızca bir şey çizdiklerinde gömülür. Zincirde hiçbir kümeyi çözmemiş bir yüz dosyaya hiçbir şey katmaz; çizen bir yüz ise çizdiği gliflerin alt kümesi olarak gömülür. 5.000 Latin karakterin arasında tek bir Çince karakter taşıyan bir belge, birkaç megabaytlık bir CJK yazı tipi değil, tek bir Han glifi taşır; dosya boyutu optimizasyonu ve yazı tipi alt kümeleri o alt kümenin nasıl kurulduğunu anlatır. Bu yüzden hizmet verdiğiniz her yerel ayarı kapsayan uzun bir zinciri yapılandırmak ucuzdur ve her PDF yalnızca kullandığının bedelini öder. Başka bir yerde üretilmiş ve hiç gömmediği fontlara başvuran dosyalar ayrı bir onarım konusudur; mevcut bir PDF'e eksik fontları gömme yazısında anlatılır

Dağıtım uyarısı gözden kaçırılmamalıdır: fallback, kodunuzun çalıştığı makinede kurulu yazı tiplerine göre çözülür ve dolu bir Office kurulumuna sahip geliştirme istasyonu, kırpılmış bir sunucu imajından ya da kapsayıcıdan çok daha fazlasına sahiptir. Yu Gothic ya da Microsoft YaHei orada yoksa zincirin düşeceği bir yer yoktur. Hedef sunucuda bir Han adlı, bir Hangul adlı ve emojili tek bir belge çalıştırın ve JSON raporunu okuyun: oradaki boş bir events dizisi, kendi masaüstünüzdeki herhangi bir testten daha çok şey söyler. Bağlandığınız yazı tiplerini dağıtın ve lisanslarının gömmeye izin verdiğini kontrol edin

Aynı fallback zinciri, eksik glif politikası ve rapor, DLL ve ActiveX sürümleriyle de açılır; böylece C#, C++ ya da betik çağırıcıları aynı çağrılarla yapılandırır. Referans dokümantasyonu ve indirmeler PDF Library for Delphi ürün sayfasındadır