Skip to content

technical-reference.md

Latest commit

 

History

History
325 lines (245 loc) · 16.7 KB

technical-reference.md

File metadata and controls

325 lines (245 loc) · 16.7 KB
Raw

AiteBar Technical Reference

Этот документ хранит технические детали, которые не должны перегружать пользовательское руководство. Пользовательская инструкция находится в USER_MANUAL.md.

Назначение

AiteBar - Windows desktop-утилита на .NET 10 и WPF. Приложение показывает скрываемую edge-панель, работает в фоне, использует tray-значок, глобальные hotkey, Win32 interop и локальное хранилище настроек в профиле пользователя.

Платформа

  • Runtime: .NET 10
  • Target: net10.0-windows
  • UI: WPF
  • Tray: Windows Forms NotifyIcon
  • Системная интеграция: Win32 API для hotkey, mouse hook, позиционирования окон и отправки клавиатурного ввода
  • Тесты: xUnit, Microsoft.NET.Test.Sdk, coverlet.collector

Установка и автозапуск

Стандартный установщик ставит программу в Program Files, создаёт группу в меню Пуск и может добавить автозапуск текущего пользователя.

Автозапуск хранится в:

HKCU\Software\Microsoft\Windows\CurrentVersion\Run

Один экземпляр приложения

AiteBar запускается как один экземпляр. Если пользователь запускает приложение повторно, второй экземпляр не стартует, а Windows показывает информационное сообщение о том, что AiteBar уже работает.

Локальные данные

Папка данных:

%AppData%\Codebdbd\Aite Bar
Файл или папка Назначение
settings.json Основные настройки приложения, панелей и пользовательских кнопок
custom_buttons.json Старый формат кнопок; используется для миграции, если settings.json отсутствует
QuickNote.md Файл быстрой заметки
clipboard_history.json История Clipboard Manager, если включено сохранение истории
Icons Пользовательские и импортированные иконки
error.log Текущий журнал ошибок
error.log.bak Резервная копия журнала после ротации

error.log ротируется при достижении примерно 1 МБ.

Модель настроек

Основные поля настроек:

Параметр Значение по умолчанию Описание
UiCulture auto Язык интерфейса
Edge Top Сторона панели
MonitorIndex 0 Индекс монитора
ActivationZoneSizePercent 30 Размер зоны активации
PanelSizePercent 80 Размер панели
ActivationDelayMs 150 Задержка появления
GlobalHotkeyCtrl false Модификатор Ctrl для показа панели
GlobalHotkeyAlt true Модификатор Alt для показа панели
GlobalHotkeyShift false Модификатор Shift для показа панели
GlobalHotkeyWin false Модификатор Win для показа панели
GlobalHotkeyKey D4 Клавиша показа панели
NextContextHotkey не назначено Следующая панель
PreviousContextHotkey не назначено Предыдущая панель
AddButtonHotkey не назначено Добавить кнопку
ShowPresetSearch true Показывать поиск
ShowPresetScreenshot true Показывать скриншот
ShowPresetVideo true Показывать запись видео
ShowPresetCalc true Показывать калькулятор
ShowPresetExplorer true Показывать проводник
ShowPresetDownloads true Показывать загрузки
ShowPresetTimerStopwatch true Показывать таймер и секундомер
ShowPresetColorPicker false Показывать выбор цвета
ShowPresetQuickNote false Показывать Quick Note
ShowPresetFileSorter true Показывать File Sorter
ShowPresetIconConverter true Показывать Icon Converter
ShowPresetQRCodeGenerator false Показывать QR Code Generator
ShowPresetClipboardManager false Показывать Clipboard Manager
ShowPresetShowDesktop true Показывать Show Desktop
ShowPresetAppsFolder true Показывать Apps Folder
ShowPresetCopilot true Показывать Copilot
ClipboardManagerPersistHistory true Сохранять историю Clipboard Manager между сессиями
QRCodeGeneratorHotkey не назначено Запустить QR Code Generator
TimerSoundEnabled true Звук окончания таймера
TimerIsStopwatchMode false Последний выбранный режим: таймер или секундомер
TimerDuration 00:05:00 Последняя длительность таймера
QuickNoteThemeId dark Тема Quick Note
QuickNotePinned false Закрепить окно Quick Note (не закрывать при потере фокуса)
QuickNoteLeft — Координата X окна Quick Note
QuickNoteTop — Координата Y окна Quick Note
QuickNoteWidth — Ширина окна Quick Note
QuickNoteHeight — Высота окна Quick Note
Contexts 8 панелей Список панелей-контекстов
ActiveContextId context-1 Активная панель
Elements пустой список Пользовательские кнопки
UtilityButtonOrder пустой список Порядок кнопок встроенных утилит

Горячие клавиши

В UI доступны глобальные hotkey:

  • показать или скрыть панель;
  • следующая панель;
  • предыдущая панель;
  • добавить кнопку;
  • запустить File Sorter;
  • запустить Quick Note;
  • запустить Color Picker;
  • запустить Timer/Stopwatch;
  • запустить QR Code Generator.

Внутри окна настроек нельзя сохранить две одинаковые назначенные комбинации. Если Windows не даёт зарегистрировать hotkey, настройки сохраняются, но приложение показывает предупреждение, а комбинация не работает до изменения.

Поддерживаемые модификаторы:

  • Ctrl;
  • Alt;
  • Shift;
  • Win;
  • распространённые комбинации этих модификаторов.

Поддерживаемые клавиши:

  • Space;
  • [;
  • ];
  • A-Z;
  • 0-9;
  • NumPad0-NumPad9 и операторы numpad;
  • F1-F12.

Константы анимаций

Длительности анимаций централизованы в AiteBar/Constants.cs, чтобы MainWindow, drag-and-drop и утилиты не расходились по значениям:

Константа Значение Назначение
AnimationFadeMs 140 Fade-in/fade-out кнопок при drag-and-drop
AnimationSlideMs 150 Slide-анимация перестановки кнопок
PanelShowAnimationMs 175 Показ панели
PanelHideAnimationMs 140 Скрытие панели
QuickNoteSlideMs 200 Анимация окна Quick Note

Типы пользовательских действий

Тип Техническое поведение
Web Запускает URL в выбранном браузере, профиле и режиме
Программа Запускает .exe, .lnk или .appref-ms
Файл Открывает файл через системную ассоциацию
Папка Открывает папку в Проводнике
Скрипт Запускает .bat, .cmd, .ps1 или .py после подтверждения
Команда Запускает команду через командную оболочку после подтверждения
Hotkey Отправляет выбранное сочетание клавиш в активное окно

Для .py при сохранении проверяется наличие python.exe в PATH.

Команды и скрипты

Команды выполняются через командную оболочку. PowerShell-скрипты запускаются через доступный PowerShell. Скрипты и команды требуют подтверждения перед запуском.

Для команд действует дополнительное предупреждение, если строка содержит shell chaining или redirection (&, |, >, <) либо потенциально разрушительные команды (del, erase, rd, rmdir, rm, remove-item, format, shutdown, restart-computer, stop-computer, bcdedit, diskpart, cipher). Это предупреждение не блокирует запуск само по себе: пользователь всё равно принимает финальное решение в confirmation dialog.

Технические строки запуска, такие как cmd.exe /c, powershell.exe -NoProfile, pwsh.exe и детали политики выполнения PowerShell, должны оставаться в технической документации, а не в user manual.

Браузеры и профили

Редактор web-кнопки показывает Chrome, Edge, Brave, Yandex и Firefox. Внутренняя модель и сервисы также могут учитывать Opera, Opera GX и Vivaldi, но эти варианты не являются основными пользовательскими пунктами текущего редактора.

Поддерживаемые режимы:

  • обычный запуск;
  • app mode для Chromium-браузеров;
  • incognito/private;
  • fullscreen после запуска;
  • выбранный профиль;
  • ротация профилей.

Если список профилей ротации пуст, это трактуется как "использовать все доступные профили".

Встроенные инструменты

Инструмент Техническое поведение
Поиск Ищет текст из буфера обмена в Google
Скриншот Открывает ms-screenclip:
Видео Открывает ms-screenclip:?type=recording
Калькулятор Запускает calc.exe
Проводник Запускает explorer.exe
Загрузки Открывает shell:Downloads
Таймер и секундомер Открывает встроенное окно таймера/секундомера
Выбор цвета Запускает overlay-пипетку и копирует HEX
Quick Note Открывает локальную заметку с автосохранением
File Sorter Утилита для сортировки файлов по расширению и другим правилам
Icon Converter Утилита для конвертации изображений в формат ICO
QR Code Generator Утилита для создания QR-кодов с экспортом в PNG/SVG
Clipboard Manager Показывает runtime-историю текста и изображений из буфера обмена
Show Desktop Минимизирует окна и показывает рабочий стол
Apps Folder Открывает системную папку Applications
Copilot Запускает Windows Copilot

Таймер и секундомер

Окно таймера/секундомера открывается из встроенных быстрых инструментов. Поддерживаются:

  • режим таймера с пресетами от 1 до 120 минут;
  • ввод своего времени в формате hh:mm:ss, mm:ss или минуты одним числом;
  • старт, пауза и сброс;
  • режим секундомера с отображением сотых долей секунды;
  • компактный режим окна;
  • звук окончания таймера, который можно отключить;
  • сохранение последнего режима, длительности и настройки звука.

Quick Note

Quick Note сохраняет данные в QuickNote.md. Поддерживаются:

  • автосохранение;
  • базовое форматирование;
  • открытие файла во внешнем редакторе;
  • очистка заметки с подтверждением;
  • темы;
  • изменение размера и положения окна;
  • закрытие по Esc и по клику вне окна;
  • Ctrl+Shift+C для копирования всего текста;
  • Ctrl+клик для открытия URL.

Для больших заметок подсветка ссылок может отключаться из соображений производительности.

Импорт и экспорт .aitebarpanel

Экспорт сохраняет текущую панель в пакет .aitebarpanel.

В пакет входят:

  • manifest с описанием панели;
  • пользовательские кнопки активной панели;
  • связанные пользовательские и импортированные иконки, если они нужны кнопкам.

Импорт:

  • проверяет пакет;
  • проверяет manifest;
  • копирует импортированные иконки в локальное хранилище;
  • добавляет кнопки в текущую панель;
  • не меняет имя текущей панели.

Ограничения размера пакета и проверки manifest относятся к технической валидации и не должны подробно описываться в user manual.

Контекстные меню

Главная панель:

  • список включенных панелей;
  • Импорт в текущую панель...;
  • Экспорт текущей панели....

Пользовательская кнопка:

  • Редактировать;
  • Дублировать;
  • Переименовать;
  • Переместить;
  • Копировать URL;
  • Копировать путь;
  • Копировать команду;
  • Открыть расположение;
  • Удалить.

Встроенный инструмент:

  • Открепить.

Tray-меню:

  • Открыть;
  • Настройки программы;
  • Проверить обновления;
  • О программе;
  • Поддержать автора;
  • Закрыть и выйти.

Сборка и проверка

Сборка Release:

dotnet build .\AiteBar.sln -c Release

Тесты:

dotnet test .\AiteBar.Tests\AiteBar.Tests.csproj -c Release

Fallback для WPF/MSBuild temp-проблем:

dotnet vstest .\AiteBar.Tests\bin\Release\net10.0-windows\AiteBar.Tests.dll

Сборка инсталлятора:

.\installer\Build-Installer.ps1

Publish-артефакты:

artifacts\publish\win-x64

Installer-артефакты:

artifacts\installer