Курсоры, обновление документации

2023-03-29 00:36:23 +04:00
parent 0ca319ae0f
commit 1ec33d6a80
20 changed files with 1118 additions and 106 deletions
@@ -2,6 +2,7 @@

 Базовое использование:
 ```html
+<!-- Первоапрельские шутки -->
 <script src="https://static.kozhilya.ru/script/april-fools.min.js"></script>
 <script>
    // Установка настроек системы
@@ -9,8 +10,114 @@
        // ...
    };
 </script>
+<!-- Конец первоапрельских шуток -->
 ```

+---
+## Полный список шуток
+
+* `shake` — **Форумо-трясение**. Страница форума начинает трястись.
+* `mirror` — **Зеркало**. Элементы форума отражаются... По крайней мере, пытаются.
+* `carnival` — **Карнавал**. Аватарки приобретают интересные цвета.
+* `humanitarian_hell` — **Ад гуманитария**. Все "тся" заменяются на "ться", а все "ться" на "тся".
+* `crazy_letters` — **Мама, Я сОшЛа С уМа!** иМеНа ЗаБоРчИкОм
+* `letter_chaos` — **Буквенный хаос**. Все буквы в словах, кроме первой и последней, перемешены.
+* `cursor` — **Красивые курсоры**. Эффекты, следующие за курсором.
+
+---
+## Настройка шуток
+
+Настройка шуток происходит при присвоении объекта `window.AprilJokes.settings`.
+Это присвоедние должно произойти **после** загрузки скрипта.
+
+Для всех шуток определны 2 общих поля:
+```js
+window.AprilJokes.settings = {
+    // ...
+    example: {
+        /**
+         * Активность шутки.
+         * Установите это значение `false`, что бы отключить шутку.
+         * Если `true`, то шутка будет обработана как обычно.
+         */
+        enabled: true,
+
+        /**
+         * Вероятность срабатывания в процентах.
+         * Если установлено значение `100`, шутка будет срабатывать всегда.
+         * Если установлено значение `0`, шутка никогда не сработает.
+         * Лучше отключать шутку, используя enabled = false!
+         */
+        chance: 20,
+    },
+    // ...
+};
+```
+
+Полный список настроек с объяснениями вы можете посмотреть в файле [`settings.example.js`](./settings.example.js). Также представлен файл [`settings.compact.js`](./settings.compact.js), который также содержит все настройки, но без коментариев. 
+
+При этом, объективно, вставлять весь этот код в HTML-начало может быть "немного" неудобно, поэтому вы можете скачать код (кнопка "Raw" над файлом), изменить его, и загрузить в файлы форума, подключив скрипт таким образом:
+
+```html
+<!-- Первоапрельские шутки -->
+<script src="https://static.kozhilya.ru/script/april-fools.min.js"></script>
+<script src="https://forumstatic.ru/files/$$$$/$$/$$/$$$$$.js"></script>
+<!-- Конец первоапрельских шуток -->
+```
+
+Заметьте, что во всех примерах приведены значения настроек по умолчанию. Вы *можете* удалять строки, значения по умолчанию которых вас устраивают.
+
+Если вас интерсует только несколько шуток, вы можете использовать метод `disableAll()`, что бы выключить выполнение всех шуток, а потом включать отдельные шутки через установку настройки `enabled`:
+
+```js
+window.AprilJokes.disableAll();
+
+window.AprilJokes.settings = {
+    // ...
+    example: {
+        enabled: true,
+        // ...
+    },
+    // ...
+};
+```
+
+Обратите внимание, что метод `disableAll()` должен быть вызван *до* установки настроек `settings`, иначе заданные значения `enabled` будут сброшены.
+
+---
+### Настройка `shake` (Форумо-трясение)
+
+Тряска элементов происходит путём изменения перечисленных направлений `margin` на значение ±`force` от стандартного значения.
+
+> **Важно**: эта шутка может вызвать дискомфорт у пользователей. Настоятельно рекомендуется оставить вероятность срабатывания шутки (`chance`) очень низкой, что бы у пользователей была возможность избавиться от шутки простым обновлением страницы! Вариант отключить шутку (`enabled: false`) тоже вариант.
+
+---
+### Настройка `mirror` (Зеркало)
+Элементы форума отражаются по весьма специфичному алгоритму... И из-за этого, шутка может работать *очень* плохо на некоторых дизайнах, поэтому данная шутка по умолчанию **отключена**
+
+Для того, что бы попробовать, сработает ли шутка для вашего дизайна, используйте в консоли разработчика:
+```js
+window.AprilJokes.start("mirror", true);
+```
+
+Так же можете [посмотреть](./src/jokes/mirror.ts#L16) на метод `MirrorJoke.start`, что бы узнать как именно проиходит отражение. 
+
+---
+### Настройка `cursor` (Красивые курсоры)
+Эффекты, следующие за курсором.
+
+Используются курсоры, предложенные в библотеке `tholman/cursor-effects` от Tim Holman ([Github](https://github.com/tholman/cursor-effects), [сайт](https://tholman.com/cursor-effects/)).
+
+Код предусматривает, что одновременно активировано не более 1 курсора из этой библиотеки. Так же для каждого курсора установлен свой шанс срабатывания, однако из-за необходимости активации строго одного эффекта, предусмотрено использование весового коэффициента `weight`: если говорить просто, то чем больше это значение, то тем больше шанс срабатывания эффекта относительно других эффектов.
+
+Так же для каждого эффекта определена настройка `enabled`, позволяющая отключить эффекты, и метод `disableAll` для отключения эффектов:
+```js
+window.AprilJokes.jokes.cursor.disableAll();
+```
+
+---
+## Разработка дополнений
+
 Использование для тестирования:
 ```html
 <script src="https://static.kozhilya.ru/script/april-fools.js"></script>
@@ -26,10 +133,13 @@
        'alert', 

        // Вызываемая функция шутки
-        settings => alert(settings.text), 
+        settings => {
+            alert(settings.text)
+        }, 

        // Стандартные настройки
        {
+            enabled: true,
            chance: 30,
            text: 'Fooled!',
        }
@@ -40,11 +150,3 @@
    window.AprilJokes.start('alert', true);
 </script>
 ```
-
-В планах:
-* Отключение отдельных шуток для пользователей.
-
-О том, какие шутки определены по умолчанию, смотрите [на странице со списком их настроек](JOKES.md).
-
-Если же вам интересна их реализация, то ищите её в папке [с их исходным кодом](src/jokes).
-