Skip to content

RU Windows 11 WinUI Guide

Jump to bottom
SlimRG edited this page Aug 23, 2026 · 1 revision

Windows 11 / WinUI 3

Этот документ задаёт актуальные правила UI. Это не история миграции.

Shell

  • Shadowsocks.WinUI — единственный основной desktop UI.
  • Используется NavigationView и штатная Settings entry.
  • Mica Base применяется там, где поддерживается.
  • Закрытие окна скрывает его; tray работает до Quit.
  • Persistent preferences находятся на соответствующих страницах приложения, а tray содержит быстрые runtime actions.
  • Shadowsocks.Windows.WinUI содержит tray/QR/power shell integration; Shadowsocks.Windows остаётся WinUI-free.

Layout

  • Базовый gutter страницы: 24 epx; compact navigation: 12 epx.
  • Размеры желательно кратны 4.
  • Используются WinUI typography resources (TitleTextBlockStyle, BodyTextBlockStyle, CaptionTextBlockStyle).
  • UI copy — sentence case.
  • Состояние нельзя кодировать только цветом: добавляйте текст, glyph или selection state.

Предпочтительные controls

  • NavigationView — навигация;
  • ContentDialog — модальные действия;
  • InfoBar — неблокирующие ошибки/состояния;
  • TeachingTip — contextual education;
  • NumberBox — порты/таймауты;
  • ToggleSwitch — boolean settings;
  • ComboBox — выбор из фиксированных вариантов.

Не добавлять WinForms/WPF для отсутствующего контрола.

Traffic

В UI доступны только:

  • User Mode;
  • Administrator Mode.

Game Mode — автоматическое состояние, а не третий traffic mode. Admin Mode показывает shield/UAC affordance и статус NetworkService/WinDivert/TCP/UDP capture.

Servers и Plugins

В редакторе Server Name располагается выше Server IP.

Plugin — ComboBox: None + плагины, установленные через PluginManager. Per-server остаются Plugin Options и Plugin Arguments.

Plugins page отвечает за install/remove; built-in Install скачивает latest Windows x64 release. При импорте ss:// с известным built-in plugin, которого ещё нет, UI сначала предлагает установить его, явно позволяя также импорт без plugin или отмену. Catalog-installed plugins имеют Automatic updates, автоматически проверяются раз в сутки, когда не используются, и поддерживают ручную Check updates. In-use пакет откладывается, manual ZIP/TAR.GZ import никогда не выполняет фоновое сетевое обновление. Произвольное repository field остаётся намеренно недоступным до отдельной модели доверия/asset selection. Arbitrary PATH/absolute executable fallback в UI не показывается.

Пароль можно показать для вручную созданного сервера; imported URL/subscription credentials остаются reveal-protected.

Logs

Toolbar всегда видим. Viewer — selectable RichTextBlock, а не старый ListView. Long lines не должны ломать layout; severity formatting сохраняется для WARN/ERROR/FATAL и multiline continuation.

Top Most реализуется через WinUI/AppWindow, не WinForms/WPF.

PAC / GeoSite

Local routing всегда managed C#. В Local PAC страница показывает effective mode, generation/source snapshot, counts правил, DIRECT/PROXY counters, Admin managed-routing state и кнопку Open user-rule.txt для пользовательских ABP/EasyList-style правил.

Online PAC — отдельный explicit mode. При его выборе карточки Local managed routing, Local user rules и локальных GeoSite sources скрываются.

При первой установке/проверке/активации DNSCrypt UI постоянно показывает активные ProgressRing/ProgressBar и текст операции; временно недоступные DNS settings скрываются, чтобы disabled-страница не выглядела зависшей.

Localization

  • UI работает через ILocalizationService.
  • Один service instance используется shell/pages/tray.
  • Persisted enum/config values не должны зависеть от переведённых labels.
  • CSV locale order: en,ru-RU,zh-CN,zh-TW,ja,ko,fr.
  • Единственный runtime source локализации — embedded i18n.csv.

Startup lifecycle

Program.Main выполняет AppInstance redirection и ProcessSingleInstanceGuard, затем запускает WinUI через публичный Application.Start. App остаётся parameterless для generated XAML compatibility.

Контекстная видимость и состояние действий

  • Сценарно-зависимые controls скрываются, когда не имеют смысла, вместо больших disabled-блоков: например Plugin=None, отсутствие forward proxy, Online PAC против Local PAC и Admin diagnostics вне Admin runtime.
  • Действия, зависящие от selection, отключены до выбора корректного элемента. Save/Discard отражают реальное наличие несохранённых изменений; Add отключён для дубликатов.
  • Долгие network/package операции показывают видимый progress и блокируют конфликтующие изменения до завершения. Это относится к DNSCrypt, GeoSite refresh, online configurations, plugins и application update.
  • Проверка Online PAC URL одинакова на странице и в tray: принимаются только абсолютные HTTP/HTTPS URL; невалидный сохранённый URL необходимо исправить до включения Online PAC.
  • Скрытие контекстного поля не должно уничтожать несохранённое значение только из-за временного переключения option; нормализация/очистка выполняется при фактическом Save.
  • Если смысл действия меняется по контексту, label и tooltip должны обновляться вместе (например Install ↔ Reinstall на Plugins).
  • Если действие намеренно заблокировано из-за несохранённого prerequisite-state, причина должна быть явно показана локализованным текстом, а не подразумеваться (например GeoSite sources нужно сохранить до refresh).

Accessibility

У неочевидных controls должны быть локализованные ToolTip и AutomationProperties.HelpText. Keyboard navigation и selection должны сохраняться без зависимости от цвета/мыши.

Проверка после обновления Windows App SDK

После обновления пакетов выполнить clean restore/build и smoke-test:

  • NavigationView;
  • ContentDialog;
  • InfoBar;
  • TeachingTip;
  • NumberBox;
  • ToggleSwitch;
  • tray integration;
  • QR import;
  • main window lifecycle.

Bootstrap resolver-каталога DNSCrypt

Shadowsocks Reborn самостоятельно обновляет подписанный каталог DNSCrypt, не позволяя dnscrypt-proxy разрешать hostnames удалённых sources через bootstrap DNS. Основной resolver — Cloudflare DoH (1.1.1.1, TLS/SNI cloudflare-dns.com), резервный — Google DoH (8.8.8.8, TLS/SNI dns.google); оба HTTPS-соединения DoH открываются через активный локальный SOCKS5 Shadowsocks. После разрешения имени источника загрузка public-resolvers.md и .minisig также идёт через Shadowsocks.

Размер загрузок ограничен, а пара проверяется закреплённым публичным Minisign-ключом DNSCrypt до публикации. Затем dnscrypt-proxy получает только локальный аутентифицированный кэш с urls = [], bootstrap_resolvers = [] и ignore_system_dns = true. Если обновление временно недоступно, может использоваться уже существующий валидный подписанный кэш; при отсутствии валидного кэша операция завершается fail-closed, а предыдущий DNS mode сохраняется.

Clone this wiki locally