跨平台集成嵌入式字体兜底与诊断优化

集成 NotoSansSC-Regular.otf 作为嵌入式资源，统一各平台字体回退逻辑，提升中文等 CJK 字符显示的健壮性。优化托管字体初始化流程，自动在系统字体不可用时回退到嵌入式字体。增强字体诊断与字形分析能力，诊断信息中明确标识字体来源。重构 Linux 字体解析流程，移除重复代码，保证 Mac/Windows/Linux 行为一致。

Author: maikebing

src/LVGLSharp.Core/LVGLSharp.Core.csproj

@@ -24,6 +24,11 @@
 	  <ProjectReference Include="..\LVGLSharp.Interop\LVGLSharp.Interop.csproj" />
 	</ItemGroup>
 
+	<ItemGroup>
+		<EmbeddedResource Include="..\LVGLSharp.Runtime.Linux\Assets\Fonts\NotoSansSC-Regular.otf" Link="Assets\Fonts\NotoSansSC-Regular.otf" LogicalName="LVGLSharp.Core.Assets.Fonts.NotoSansSC-Regular.otf" />
+		<None Include="..\LVGLSharp.Runtime.Linux\Assets\Fonts\NOTICE.txt" Pack="true" PackagePath="THIRD-PARTY-NOTICES\LVGLSharp.Core\" Visible="false" />
+	</ItemGroup>
+
  <ItemGroup>
    <Folder Include="Drawing\" />
  </ItemGroup>

src/LVGLSharp.Core/LvglFontDiagnostics.cs

@@ -26,18 +26,18 @@ public static LvglFontDiagnostics FromFontFamily(FontFamily? fontFamily, IEnumer
 
         if (!enabled)
         {
-            return new LvglFontDiagnostics(null, "ManagedFontDisabled", null);
+            return new LvglFontDiagnostics(null, "Source=LvglNativeFont; ManagedFontDisabled", null);
         }
 
         var candidateList = string.Join(", ", candidates.Where(static candidate => !string.IsNullOrWhiteSpace(candidate)));
         if (fontFamily is null)
         {
-            return new LvglFontDiagnostics(null, $"ManagedFontEnabled; Family=<none>; Candidates={candidateList}", null);
+            return new LvglFontDiagnostics(null, $"Source=PlatformSystemFont; ManagedFontEnabled; Family=<none>; Candidates={candidateList}", null);
         }
 
         return new LvglFontDiagnostics(
             fontFamily.Value.Name,
-            $"ManagedFontEnabled; Family={fontFamily.Value.Name}; Candidates={candidateList}",
+            $"Source=PlatformSystemFont; ManagedFontEnabled; Family={fontFamily.Value.Name}; Candidates={candidateList}",
             null);
     }
 }

src/LVGLSharp.Core/LvglManagedFontHelper.cs

@@ -1,12 +1,18 @@
 using LVGLSharp.Interop;
 using SixLabors.Fonts;
+using SixLabors.Fonts.Unicode;
+using System.Numerics;
+using System.Reflection;
+using System.Text;
 
 namespace LVGLSharp;
 
 public static unsafe class LvglManagedFontHelper
 {
     private const string EnableManagedFontEnvironmentVariable = "LVGLSHARP_ENABLE_MANAGED_FONT";
     private const string DisableManagedFontEnvironmentVariable = "LVGLSHARP_DISABLE_CUSTOM_FONT";
+    private const string EmbeddedFallbackFontResourceName = "LVGLSharp.Core.Assets.Fonts.NotoSansSC-Regular.otf";
+    private const string EmbeddedFallbackFontFileName = "NotoSansSC-Regular.otf";
 
     /// <summary>
     /// Determines whether managed font rendering should be enabled for the current process.
@@ -62,8 +68,38 @@ public static LvglManagedFontState InitializeManagedFont(
         bool enabled)
     {
         var fallbackFont = LvglFontHelper.GetEffectiveTextFont(root, lv_part_t.LV_PART_MAIN);
-        var fontManager = TryApplyManagedFont(root, fontPath, size, dpi, fallbackFont, out var font, out var style, enabled);
-        return new LvglManagedFontState(fallbackFont, font, fontManager, diagnostics, style);
+        if (!enabled)
+        {
+            return new LvglManagedFontState(
+                fallbackFont,
+                null,
+                null,
+                LvglFontDiagnostics.FromPath(null, "Source=LvglNativeFont; ManagedFontDisabled", null),
+                null);
+        }
+
+        var fontManager = TryApplyManagedFont(root, fontPath, size, dpi, fallbackFont, out var font, out var style, enabled: true);
+        if (fontManager is not null)
+        {
+            return new LvglManagedFontState(fallbackFont, font, fontManager, diagnostics, style);
+        }
+
+        if (TryResolveEmbeddedFallbackFontPath(out var embeddedFallbackFontPath))
+        {
+            var embeddedFallbackDiagnostics = CreateEmbeddedFallbackDiagnostics(embeddedFallbackFontPath, diagnostics.DiagnosticSummary);
+            var embeddedFallbackFontManager = TryApplyManagedFont(root, embeddedFallbackFontPath, size, dpi, fallbackFont, out font, out style, enabled: true);
+            if (embeddedFallbackFontManager is not null)
+            {
+                return new LvglManagedFontState(fallbackFont, font, embeddedFallbackFontManager, embeddedFallbackDiagnostics, style);
+            }
+        }
+
+        return new LvglManagedFontState(
+            fallbackFont,
+            null,
+            null,
+            LvglFontDiagnostics.FromPath(null, $"{diagnostics.DisplaySummary}; Source=LvglNativeFont; EmbeddedFallback=<none>", diagnostics.GlyphDiagnosticSummary),
+            null);
     }
 
     /// <summary>
@@ -79,8 +115,33 @@ public static LvglManagedFontState InitializeManagedFont(
     {
         var diagnostics = CreateFontDiagnostics(fontFamily, fontFamilyNames, enabled);
         var fallbackFont = LvglFontHelper.GetEffectiveTextFont(root, lv_part_t.LV_PART_MAIN);
-        var fontManager = TryApplyManagedFont(root, fontFamily, size, dpi, fallbackFont, out var font, out var style, enabled);
-        return new LvglManagedFontState(fallbackFont, font, fontManager, diagnostics, style);
+        if (!enabled)
+        {
+            return new LvglManagedFontState(fallbackFont, null, null, diagnostics, null);
+        }
+
+        var fontManager = TryApplyManagedFont(root, fontFamily, size, dpi, fallbackFont, out var font, out var style, enabled: true);
+        if (fontManager is not null)
+        {
+            return new LvglManagedFontState(fallbackFont, font, fontManager, diagnostics, style);
+        }
+
+        if (TryResolveEmbeddedFallbackFontPath(out var embeddedFallbackFontPath))
+        {
+            var embeddedFallbackDiagnostics = CreateEmbeddedFallbackDiagnostics(embeddedFallbackFontPath, diagnostics.DiagnosticSummary);
+            var embeddedFallbackFontManager = TryApplyManagedFont(root, embeddedFallbackFontPath, size, dpi, fallbackFont, out font, out style, enabled: true);
+            if (embeddedFallbackFontManager is not null)
+            {
+                return new LvglManagedFontState(fallbackFont, font, embeddedFallbackFontManager, embeddedFallbackDiagnostics, style);
+            }
+        }
+
+        return new LvglManagedFontState(
+            fallbackFont,
+            null,
+            null,
+            LvglFontDiagnostics.FromPath(null, $"{diagnostics.DisplaySummary}; Source=LvglNativeFont; EmbeddedFallback=<none>", diagnostics.GlyphDiagnosticSummary),
+            null);
     }
 
     /// <summary>
@@ -91,6 +152,92 @@ public static LvglFontDiagnostics CreateFontDiagnostics(FontFamily? fontFamily,
         return LvglFontDiagnostics.FromFontFamily(fontFamily, fontFamilyNames, enabled);
     }
 
+    /// <summary>
+    /// Resolves the shared embedded fallback font path extracted from the Core assembly resources.
+    /// </summary>
+    public static bool TryResolveEmbeddedFallbackFontPath(out string resolvedFontPath)
+    {
+        Assembly assembly = typeof(LvglManagedFontHelper).Assembly;
+        using Stream? resourceStream = assembly.GetManifestResourceStream(EmbeddedFallbackFontResourceName);
+        if (resourceStream is null)
+        {
+            resolvedFontPath = string.Empty;
+            return false;
+        }
+
+        string targetDirectory = Path.Combine(Path.GetTempPath(), "LVGLSharp", "fonts");
+        Directory.CreateDirectory(targetDirectory);
+
+        resolvedFontPath = Path.Combine(targetDirectory, EmbeddedFallbackFontFileName);
+        if (File.Exists(resolvedFontPath) && new FileInfo(resolvedFontPath).Length == resourceStream.Length)
+        {
+            return true;
+        }
+
+        using FileStream outputStream = File.Create(resolvedFontPath);
+        resourceStream.CopyTo(outputStream);
+        return true;
+    }
+
+    /// <summary>
+    /// Creates diagnostics for the shared embedded fallback font.
+    /// </summary>
+    public static LvglFontDiagnostics CreateEmbeddedFallbackDiagnostics(string fontPath, string? previousSummary = null)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(fontPath);
+
+        string summary = string.IsNullOrWhiteSpace(previousSummary)
+            ? $"Source=EmbeddedFallbackFont; Path={fontPath}"
+            : $"{previousSummary}; Source=EmbeddedFallbackFont; Path={fontPath}";
+
+        return LvglFontDiagnostics.FromPath(fontPath, summary, CreateGlyphDiagnosticSummary(fontPath));
+    }
+
+    /// <summary>
+    /// Creates a glyph diagnostics summary for a font file path.
+    /// </summary>
+    public static string CreateGlyphDiagnosticSummary(string fontPath)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(fontPath);
+
+        try
+        {
+            FontCollection collection = new();
+            FontFamily family = collection.Add(fontPath);
+            Font font = family.CreateFont(12);
+            Rune[] sampleRunes = [new Rune('图'), new Rune('像'), new Rune('路'), new Rune('径')];
+            Dictionary<string, int> signatureCounts = new(StringComparer.Ordinal);
+            List<string> parts = new(sampleRunes.Length);
+
+            foreach (var rune in sampleRunes)
+            {
+                if (!TryGetGlyphSignature(font, rune, out var signature))
+                {
+                    parts.Add($"{rune}:Missing");
+                    continue;
+                }
+
+                parts.Add($"{rune}:{signature}");
+                signatureCounts[signature] = signatureCounts.TryGetValue(signature, out var count) ? count + 1 : 1;
+            }
+
+            bool uniformSignature = signatureCounts.Count == 1 && signatureCounts.Values.First() == sampleRunes.Length;
+            return $"Uniform={uniformSignature}; Distinct={signatureCounts.Count}; Samples={string.Join(", ", parts)}";
+        }
+        catch (IOException ex)
+        {
+            return $"GlyphDiagError={ex.GetType().Name}:{ex.Message}";
+        }
+        catch (UnauthorizedAccessException ex)
+        {
+            return $"GlyphDiagError={ex.GetType().Name}:{ex.Message}";
+        }
+        catch (InvalidOperationException ex)
+        {
+            return $"GlyphDiagError={ex.GetType().Name}:{ex.Message}";
+        }
+    }
+
     /// <summary>
     /// Applies a managed font from the specified font file path when managed fonts are enabled.
     /// </summary>
@@ -195,4 +342,18 @@ public static void ReleaseManagedFont(
         lv_font_t* font = null;
         ReleaseManagedFont(ref fallbackFont, ref font, ref fontManager, ref diagnostics, ref defaultFontStyle);
     }
+
+    private static bool TryGetGlyphSignature(Font font, Rune rune, out string signature)
+    {
+        signature = string.Empty;
+
+        if (!font.TryGetGlyphs(new CodePoint(rune.Value), out var glyphs) || glyphs.Count == 0)
+        {
+            return false;
+        }
+
+        FontRectangle bbox = glyphs[0].BoundingBox(GlyphLayoutMode.Horizontal, Vector2.Zero, 72f);
+        signature = $"Count={glyphs.Count};Adv={Math.Round((double)glyphs[0].GlyphMetrics.AdvanceWidth, 2)};BBox={Math.Round((double)bbox.Width, 2)}x{Math.Round((double)bbox.Height, 2)}@{Math.Round((double)bbox.Left, 2)},{Math.Round((double)bbox.Top, 2)}";
+        return true;
+    }
 }