SVG в .NET MAUI: храните SVG, ссылайтесь на PNG

Для SVG в процессе включенных изображений .NET MAUI храните SVG в проекте и ссылайтесь на сгенерированное имя PNG из XAML или C#. MAUI обрабатывает векторный исходник при сборке. Поэтому Image с compass.png может быть правильным, даже если вы добавили compass.svg. Руководство Microsoft по изображениям проекта описывает конвертацию.

Это объясняет имя файла, но оставляет вопрос дизайна: какой размер должен генерировать MAUI и что проверять после? Проследите маленькую эмблему компаса через исходник, метаданные проекта и объявление отображения.

Проследите исходник через сборку

Редактируемый SVG и упакованное изображение выполняют разные задачи. Сохраните исходник для последующего изменения фигур, пустого пространства или цветов. Используйте сгенерированное имя в представлении, которое его показывает.

Документация элемента Image описывает включение изображений целевой плотности в пакет приложения и выбор подходящего разрешения операционной системой. Хранение оригинала SVG не означает, что этот конкретный процесс передает живой документ SVG представлению.

Добавьте небольшой SVG с четкими границами

Сохраните оригинальный пример как Resources/Images/compass.svg:

<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96" viewBox="0 0 96 96">
  <circle cx="48" cy="48" r="34" fill="none" stroke="#173e52" stroke-width="8"/>
  <path d="M58 28L52 52L28 58Z" fill="#ed765e"/>
</svg>

Кольцо оставляет прозрачный центр, а коралловая стрелка — отдельная фигура. Эти детали дают конкретные объекты проверки после импорта. Объявленные размеры и квадратный viewBox также ясно задают рамку. См. руководство по SVG-файлам о различии векторной геометрии и растра внутри оболочки SVG.

В проекте подтвердите действие сборки MauiImage у файла. Microsoft указывает Resources/Images как обычную папку. Перед добавлением XML проверьте существующие элементы проекта: папка уже может включаться шаблоном. Настройка изображений проекта объясняет размещение и действие сборки.

Обновите существующий элемент один раз

Если существующий шаблон MauiImage уже включает файл компаса, поместите это обновление метаданных после включения:

<ItemGroup>
  <MauiImage Update="Resources\Images\compass.svg" BaseSize="48,48" />
</ItemGroup>

Update меняет метаданные существующего элемента, а не добавляет отсутствующий файл в список. Если соответствующего включения нет, добавьте файл один раз с действием MauiImage или явным Include. Справочник Microsoft по Item MSBuild различает операции.

Это предотвращает соблазнительное исправление: повторное добавление Include при диагностике отсутствующего изображения. Сначала установите наличие файла в списке, затем меняйте метаданные.

Сошлитесь на PNG и задайте область отображения

Поместите объявление в существующую страницу или макет MAUI:

<Image Source="compass.png"
       WidthRequest="48"
       HeightRequest="48"
       Aspect="AspectFit"
       SemanticProperties.Description="Compass" />

Расширение .png намеренное. Ширина и высота запрашивают квадратную область отображения; AspectFit сохраняет все изображение внутри. Для прямоугольной иллюстрации используйте подходящую область вместо растягивания до квадрата. Справочник масштабирования Image Microsoft различает вписывание, обрезку и растягивание.

Код компаса — оригинальный пример настройки, а не зафиксированный тест рендеринга устройства. Соберите его в своем целевом проекте и проверьте полученное представление. Одно правильное имя не доказывает нужного отображения конкретной графики.

BaseSize и размер макета решают разные задачи

BaseSize="48,48" задает базовые размеры, по которым MAUI создаёт изображения для разной плотности пикселей. Без явного базового размера MAUI использует собственные размеры SVG. Microsoft описывает оба правила в Resize an image.

В примере исходный рисунок использует пространство 96 на 96, а запрошенные база и представление — 48 на 48. Это намеренные авторские решения, а не измеренные выходные размеры сборки. Кольцо должно сохранять пропорции при масштабировании.

Если позднее та же эмблема используется в гораздо большем представлении, пересмотрите размер сборки и проверьте это использование. Изменение WidthRequest не редактирует исходную графику или метаданные сборки. И наоборот, изменение BaseSize не удаляет пустые поля SVG. Подгоните границы рисунка в исходнике, если сама эмблема выглядит маленькой внутри представления с правильно заданными размерами.

Не используйте Resize="false" как общее исправление четкости. Он отключает изменение размера векторного изображения в этом процессе. Выбирайте его только для намеренно нужного поведения по документированному параметру resize.

Проверяйте отсутствующее или неожиданное изображение по порядку

1. Подтвердите имя файла и элемент проекта. Используйте строчное имя вроде compass.svg и проверьте, нет ли другого изображения с тем же именем. Правила имен Microsoft требуют уникальных имен изображений и символов, совместимых с Android.
2. Проверьте источник представления. Для процесса включенного SVG используйте compass.png в XAML или C#.
3. Сравните нужную область отображения с базовым размером. Изменение размера представления и размера сборки делаются в разных местах.
4. Проверьте саму графику. Центр кольца все еще открыт? Коралловая стрелка различима? Эмблема по центру или невидимое пустое пространство исходника сдвигает ее?

Также проверьте метаданные, меняющие оформление. Руководство изображений проекта описывает TintColor и Color для тонирования и фона. Для двухцветного примера оставьте их незаданными, если не хотите менять внешний вид. Проверьте изображение на настоящем фоне страницы, где потерю прозрачного отверстия легче заметить.

Когда нужно поведение SVG во время выполнения

Скачанное содержимое SVG, интерактивные контуры или изменения во время выполнения требуют отдельного решения реализации. Приведённые выше инструкции для изображений, включённых в сборку, не подтверждают поддержку этих задач.

Например, проект примеров SVG Vapolia описывает собственные SvgImage и SvgImageSource и настройку встроенных ресурсов. Это другой контракт загрузки. Оцените поддерживаемые рендерером возможности и целевые платформы на реальном файле перед внедрением; смена расширения в обычном объявлении Image не устанавливает рендерер.

Та же графика требует другой настройки в процессе изображений SVG Flutter, каталоге ресурсов SwiftUI и импорте Android VectorDrawable. Используйте исходный оригинал повторно, затем следуйте правилам каждого назначения.

Подготовьте векторный оригинал, если остался только PNG

Если компас или логотип существует только в PNG, PerfectVector может помочь создать редактируемую графику SVG до добавления в проект MAUI. Конвертируйте PNG в SVG, затем проверьте отверстие кольца, маленькие отдельные части и интервалы в редакторе. Сохраните чистый оригинал для последующих изменений размера и цвета.

Векторизация не исправляет объявление MauiImage и не превращает процесс включенных изображений в парсер SVG во время выполнения. Если исходник уже редактируемый SVG, работайте с конфигурацией проекта или самим рисунком. Фото и текстурная графика могут быть полезнее в растре; трассировка только потому, что приложение принимает SVG-исходники, добавляет отдельное решение о графике.

Частые вопросы

Почему я ссылаюсь на PNG, если добавил SVG? .NET MAUI преобразует включенные исходники изображений SVG в PNG при сборке. Храните SVG в проекте и ссылайтесь на имя PNG из XAML или C#.

Задает ли BaseSize размер элемента Image? BaseSize задает базовые размеры для вычисления изображений разных плотностей при сборке. Макет и запросы размеров представления управляют областью отображения.

Нужно ли добавлять еще один MauiImage Include для изменения BaseSize? Проверьте, включен ли файл, в том числе через шаблон. Используйте Update для метаданных существующего элемента; Include нужен только для добавления элемента.

Загрузит ли это SVG, скачанный после сборки приложения? Процесс включенных изображений не охватывает скачивание и разбор SVG во время выполнения. Для этого требования выберите и проверьте отдельный подход рендеринга.

Источники

1. Microsoft — Add images to a .NET MAUI app project — Обработка SVG в PNG, элементы изображений, имена файлов, базовый размер и метаданные сборки.
2. Microsoft — Image — Ссылки на локальные изображения, выбор целевой плотности, размеры представления и масштабирование.
3. Microsoft — Item element (MSBuild) — Различие добавления элемента через Include и изменения метаданных через Update.
4. Vapolia — SVG samples — Отдельный элемент SVG во время выполнения и процесс загрузки ресурсов.

Работаете с растровой эмблемой приложения? Превратите PNG в редактируемый SVG, проверьте отверстия и интервалы, затем добавьте оригинал в MAUI и проверьте сгенерированное изображение в целевом приложении.