VK Fix

VKFix — userscript для улучшения интерфейса ВКонтакте. Современная альтернатива VK Opt с гибкой настройкой каждого модуля.

📋 Оглавление

• Возможности
• Установка
• Разработка
• Тестирование
• Архитектура
• Вклад в проект
• Лицензия

---

🚀 Возможности

📷 Просмотрщик фотографий

Функция	Описание
Расширение фото	Кнопка «Расширить/Сузить» для просмотра фото в полном размере внутри просмотрщика. Поддержка авторасширения на основном или дополнительном мониторе
Переключение колёсиком	Навигация между фотографиями прокруткой колёсика мыши в просмотрщике
Фикс зумирования	Корректное отображение изображений при нестандартном масштабировании Windows (DPI > 100%)
Исправление навигации в ленте	Устраняет проблему с пролистыванием фото в ленте, вызванную некорректным хешем в URL
Открыть в Хранителе Групп	Дополнительный пункт в меню просмотрщика для открытия фото в приложении «Хранитель Групп»
Открыть в альбоме	Быстрый переход к фотографии в родном альбоме из просмотрщика

💬 Мессенджер

Функция	Описание
Фото-стикеры (умные подсказки)	Всплывающие подсказки с фотографиями при вводе текста в мессенджере. Поиск по описанию к фото с поддержкой семантического анализа, нечёткого поиска (fuzzy matching) и синонимов
Кэширование фотографий	Использование IndexedDB для локального кэширования альбомов, что ускоряет загрузку подсказок
Настраиваемые альбомы	Возможность указать ID конкретных альбомов для использования в подсказках (поддержка системных альбомов, например, сохранённых фотографий)

👥 Сообщества

Функция	Описание
Телепортация информации о группе	Автоматическая подгрузка содержимого модального окна «Подробная информация» прямо на страницу сообщества, без необходимости открытия модального окна

⌨️ Прочее

Функция	Описание
Переключение раскладки (Ctrl+Q)	Автоматическое переключение раскладки клавиатуры для введённого или выделенного текста в любом редактируемом поле. Поддержка русско-английской раскладки
Экспорт бэкапа сообществ	Кнопка «Создать бэкап из всех сообществ» в приложении «Хранитель Групп» для экспорта списка всех ваших сообществ в JSON
Логирование	Подробное логирование работы скрипта в консоль браузера для отладки

---

📦 Установка

Требования

• Браузер на базе Chromium (Chrome, Яндекс.Браузер, Edge и т.д.) или Firefox
• Менеджер userscript-ов: Tampermonkey или * Violentmonkey*

Установка из релиза

1. Установите Tampermonkey/Violentmonkey в ваш браузер
2. Скачайте файл vkfix.user.js из последнего релиза
3. Откройте файл — менеджер userscript предложит установить его
4. Нажмите «Установить»

---

💻 Разработка

Стек технологий

• TypeScript 5.6 — типизированный JavaScript
• Vue 3.5 — реактивные компоненты интерфейса (настройки, стикеры)
• VueUse — коллекция Vue-композиционных функций
• Naive UI — UI-компоненты для окна настроек
• Vite 7 — сборка проекта
• Vitest — фреймворк для тестирования
• es-toolkit — утилиты для работы с данными (debounce и др.)
• vue-vkontakte-icons — иконки VK UI

Быстрый старт

# Установка зависимостей
npm install

# Сборка в режиме разработки (с автопересборкой при изменениях)
npm start

# Production-сборка
npm build

Собранный файл vkfix.user.js появится в папке dist/.

Настройка Tampermonkey для разработки

1. Создайте новый скрипт в Tampermonkey
2. Вставьте следующий заготовку:

// ==UserScript==
// @name VK Fix
// @description Скрипт для улучшения интерфейса ВКонтакте
// @author Ivan Petrov (LazyTechwork)
// @license MIT
// @version 2.0
// @include https://vk.com/*
// @include https://vk.ru/*
// @require file://<ПУТЬ_ДО_ПРОЕКТА>/dist/vkfix.user.js
// @grant GM_getValue
// @grant GM_setValue
// @grant GM_addStyle
// @grant unsafeWindow
// ==/UserScript==

1. Замените <ПУТЬ_ДО_ПРОЕКТА> на абсолютный путь к папке проекта (например, C://projects/vkfix)
2. Дайте Tampermonkey разрешение на доступ к локальным файлам в настройках расширения браузера
3. Запустите npm start для автоматической пересборки

Доступные команды

Команда	Описание
npm run build	Production-сборка
npm start	Разработка с автопересборкой (watch-режим)
npm run dev	Запуск Vite dev server
npm run type-check	Проверка типов TypeScript
npm run test	Запуск тестов
npm run test:watch	Тесты в режиме watch
npm run test:ui	Тесты с UI
npm run test:coverage	Тесты с отчётом покрытия

---

🧪 Тестирование

Проект использует Vitest для модульного тестирования. Тесты покрывают:

• Переключение раскладки (switchKeyboardLayout.test.ts) — проверка корректности преобразования символов между русско-английской раскладками
• Фильтрация стикеров (AdvancedStickerFilter.test.ts) — тестирование позитивных и негативных фильтров, обработка эмодзи
• Семантический поиск (SemanticSearch.test.ts, SemanticMap.test.ts) — проверка работы с синонимами и смысловыми группами
• Нечёткий поиск (FuzzyMatcher.test.ts) — тестирование fuzzy matching алгоритма
• Поиск по эмодзи (EmojiSearch.test.ts) — проверка поиска по эмодзи-символам

---

🏗️ Архитектура

Структура проекта

src/
├── classes/               # Базовые классы и утилиты
│   ├── sticker-search/    # Движок семантического поиска стикеров
│   ├── AdvancedStickerFilter.ts   # Фильтрация стикеров по ключевым словам
│   ├── ApiInteractor.ts           # Взаимодействие с VK API
│   ├── LocationState.ts           # Отслеживание состояния URL
│   ├── Logger.ts                  # Логирование
│   ├── PhotoCache.ts              # Кэширование фото в IndexedDB
│   ├── PriorityArray.ts           # Приоритетный массив
│   ├── SemanticSearch.test.ts     # Тесты семантического поиска
│   └── VKLocation.ts              # Утилиты для работы с URL VK
│
├── common/                # Общие утилиты
│   ├── helpers/           # Хелпер-функции
│   │   ├── convertTextLayout.ts   # Переключение раскладки
│   │   ├── extractPath.ts
│   │   ├── extractQuotedTexts.ts
│   │   ├── querySelectorWithTimeout.ts
│   │   ├── saveTemplateAsFile.ts
│   │   ├── sleep.ts
│   │   ├── switchKeyboardLayout.ts
│   │   └── uiHelpers.ts
│   └── consts.ts          # Константы
│
├── data/                  # Данные
│   └── semantic-map.json  # Карта синонимов для семантического поиска
│
├── libs/                  # Сторонние библиотеки
│   └── GM_config.js       # Обёртка для GM_config
│
├── modules/               # Основные модули
│   ├── config/            # Модуль настроек (Vue-компоненты)
│   │   ├── configData.ts        # Конфигурация и метаданные полей
│   │   ├── VConfigButton.vue    # Кнопка открытия настроек
│   │   ├── VConfigField.vue     # Поле конфигурации
│   │   └── VConfigPopup.vue     # Модальное окно настроек
│   │
│   ├── messenger/         # Модуль мессенджера
│   │   ├── messenger.ts         # Основная логика фото-стикеров
│   │   ├── VPhotoStickersPopup.vue
│   │   └── types.ts             # TypeScript-типы
│   │
│   ├── mutations/         # Модуль отслеживания мутаций DOM
│   │   ├── mutationHandler.ts
│   │   └── locationMutations.ts
│   │
│   ├── appActions.ts      # Дополнения к приложениям (бэкап сообществ)
│   ├── fixImagesZooming.ts   # Исправление зумирования изображений
│   ├── groupInfoTeleport.ts  # Телепортация информации о группе
│   ├── pageScanner.ts     # Сканер страницы
│   ├── pvAddons.ts        # Дополнения к просмотрщику фото
│   └── styles.ts          # Инъекция CSS-стилей
│
├── GlobalConfig.ts        # Глобальная конфигурация (хранение в GM)
├── index.ts               # Точка входа userscript
└── styles.css             # Глобальные стили

Ключевые архитектурные решения

• Userscript-подход — скрипт работает через Tampermonkey/Violentmonkey, не требует установки отдельных приложений
• Vue 3 Composition API — для построения интерактивных UI-компонентов (настройки, стикеры)
• Глобальная конфигурация — все настройки хранятся через GM_getValue/GM_setValue, каждый модуль можно включить/выключить индивидуально
• Асинхронная загрузка — модули инициализируются после полной загрузки страницы
• MutationObserver — отслеживание изменений DOM для работы с динамическим контентом VK
• VK API — взаимодействие через встроенный MECommonContext (если доступен) или через прямой вызов с токеном из localStorage
• IndexedDB кэширование — фотографии для стикеров кэшируются локально, ускоряя последующие загрузки

---

🤝 Вклад в проект

Мы приветствуем любой вклад! Перед началом работы ознакомьтесь с инструкциями на Wiki.

Как внести вклад

1. Форкните репозиторий
2. Создайте ветку для новой функциональности (git checkout -b feature/amazing-feature)
3. Внесите изменения и убедитесь, что тесты проходят (npm run test)
4. Закоммитьте изменения (git commit -m 'Добавлена потрясающая функциональность')
5. Отправьте в ветку (git push origin feature/amazing-feature)
6. Создайте Pull Request

Рекомендации

• Используйте npm run type-check перед коммитом
• Добавляйте тесты для новой функциональности
• Следуйте стилю кода проекта

---

📝 Лицензия

Этот проект распространяется под лицензией MIT. Подробности — в файле LICENSE.md.

---

👥 Авторы и контрибьюторы

• Ivan Petrov (LazyTechwork) — автор проекта
• Ivan Mel (ivanmem) — контрибьютор
• VK Fix Team — команда разработки

---

🙏 Благодарности

• Проект пришёл на замену VK Opt
• Использует Vue.js, Naive UI, VueUse
• Тестирование через Vitest
• Иконки от vue-vkontakte-icons