Fandom Developers Wiki
Advertisement

ShowCustomModal — це бібліотека JavaScript, яка дублює функціональні можливості існуючого $.showCustomModal.

Він більше не відображається через глобальний об'єкт jQuery, а натомість експонується через гачок mw. Цей хук запускається за допомогою функції, яка відповідає $.showCustomModal, а також містить інші відповідні методи модальних маніпуляцій, такі як closeModal.

Його існування випливає з двох факторів: існують застарілі скрипти, які потребують модальної підтримки, альтернативи — Modal-js та QDmodal. Перенесення до них нетривіальне. Це існує, щоб полегшити цей перехід. Іншою причиною його існування є архівні причини, а також надання альтернативи як недолікам Modal-js (переважно з корінням OOUI), так і QDmodal, а також більш простий виклик модальної функції без стану.

Імпорт[]

Ви знаєте, як це відбувається.

importArticle({
    type: 'script',
    article: 'u:dev:MediaWiki:ShowCustomModal.js'
});

mw.hook('dev.showCustomModal').add(function(showCustomModal) {
    // Ваш код тут
    // `showCustomModal` є прив’язкою до `window.dev.showCustomModal`
});

<documentation>[]

Гачок експортує одну функцію, функціюshowCustomModal. Це не конструктор, ви не називаєте його new; Ви викликаєте його, щоб показати модальний, і він повертає побудований модальний об'єкт jQuery.

Якщо ви раніше використовували $.showCustomModal, він повністю сумісний із назад. Це означає, що будь-який виклик $.showCustomModal, який ви можете знайти, можна замінити на dev.showCustomModal, і він буде «Просто працювати», якщо ви переконаєтесь, що перед використанням гачок використовується.

Функції в JavaScript також є об'єктами, що означає, що функція може мати властивості. Експортована функція showCustomModal також містить деякі з них, наприклад, closeModal. Якщо б ви хотіли його використати, ви б захопили посилання на повернений об’єкт jQuery showCustomModal і назвали його: showCustomModal.closeModal ($ modal)

showCustomModal(title, content?, options?)
Основна функція. Перший параметр — це рядок, і це назва модалю. Він інтерпретується як HTML, тому його потрібно дезінфікувати. Це повторюється: як заголовок, так і вміст інтерпретуються як HTML, якщо ви не використовуєте такі заходи, як mw.html.escape, ваш скрипт буде вразливим.
Не звертаючи уваги на це, другий параметр — це вміст, а третій — об’єкт параметрів із багатьма властивостями, які можна використовувати. Одним з них також є content, тому ви можете уникнути передачі другого атрибута та замінити його на об’єкт options. Це використання також дійсне: showCustomModal(title, { content: string, ...otherOptions })
Об'єкт options має багато корисних властивостей, які будуть належним чином задокументовані пізніше.
showCustomModal.closeModal($modal)
Друга експортована функція, і, швидше за все, найкорисніша з досить нішевих додаткових функцій.
З огляду на екземпляр jQuery, що посилається на елементи (елементи) .modalWrapper, він закриє їх і позбудеться фонів.
Існує помилка, коли, якщо у вас є кілька модальних екземплярів і закрити один з них, клас тіла .modalShown буде видалений, навіть якщо ще є один модальний. Якщо у вас дійсно є варіант використання цього класу, залиште повідомлення на сторінці обговорення. Наразі рекомендується просто не користуватися класом.
showCustomModal.hideModal($modal) & showCustomModal.showModal($modal)
Ці функції просто приховують і показують модалі, вони використовуються внутрішньо, коли ви вказуєте властивість параметрів persistent. Наскільки мені відомо, вони ніколи не використовувалися в будь-якому скрипту розробника, тому вам, мабуть, ці або вищевказана властивість не потрібні. Тим не менш, функціональність тут, якщо вам потрібен модал, який ви хочете зберегти у своєму стані після його закриття, на випадок, якщо ви хочете дозволити користувачеві підглянути до тла перед повторним відкриттям модалу.
showCustomModal.makeModal($dialog, options) & showCustomModal.getModalTopOffset($modal)
Це функції деталізації реалізації. Не використовуйте їх. Або я знайду тебе, а ти не хочеш бачити мене в поганому настрої. Мадмін заручена.

Об'єкт налаштування[]

Третій (або другий, якщо content опущено) параметр showCustomModal. Це простий об’єкт з багатьма корисними властивостями, які ви можете застосувати до свого модального. Ось де багато складності і звідки походить «звичай» від «showCustomModal».

Ось усі доступні властивості, впорядковані приблизно в найменш корисному порядку, а також дають поштовх простим, але ефективним властивостям, таким як id та width, про які ви повинні знати. Нижня половина, ймовірно, зламана, марна та схильна до видалення, якщо не з міркувань сумісності.

content
Ви повинні використовувати це лише, якщо ви використовуєте підпис для showCustomModal (назва, параметри). Це передбачено як стилістичний вибір для спрощення виклику функції, навіть якщо старий підпис доступний для зворотної сумісності.
buttons
Найпоширеніша та найкорисніша властивість об’єкта options. Він дозволяє визначити масив клавіш, які відображатимуться внизу модального. Його підпис [{ defaultButton: boolean, message: string, id: string, handler: function(event) }].
defaultButton
Логічне значення, яке вказує, чи слід позначити клавішу як основну чи ні. Первинні клавіші будуть темнішими, тоді як вторинні зазвичай виділяються менше.
message
Вміст клавіші. Це HTML, тому всі попередні попередження про санітарну обробку все ще діють. Використовуйте такі функції, як .escape() або mw.html.escape() I18n-js, щоб не мати ЗПСШ.
id
Атрибут id, який буде призначений клавіші. Як правило, ви не повинні турбуватися або турбуватися про цю нерухомість. Це може стати в нагоді, якщо ви хочете програмно відключити деякі клавіші, і була виправлена помилка, коли клавіші не мають id="undefined", якщо ви їх не надаєте.
handler
Функція, яка буде виконана при натисканні на модальний. Наприклад, клавіша закриття може викликати закриття, яке викликає showCustomModal.closeModal. Це, мабуть, другий за корисністю параметр, після message.
width
Кількість пікселів, що визначає, наскільки широким буде модальний, або рядок з одиницею розміру CSS. За замовчуванням: 400, examples: 420, '50%', '100vw'
height
Наскільки високим буде модал, як і width. Ймовірно, вам слід залишити це значення за замовчуванням. За замовчуванням: auto
id
Ідентифікатор, який надає модальний елемент обгортки. Якщо його пропустити, він буде призначений випадковим чином.
className
Клас для додавання до модальної обгортки поверх modalWrapper
callbackBefore, callback
Функції, які будуть викликані до і після створення модалу відповідно. callback не дуже корисний, оскільки ви можете просто розмістити вміст після виклику showCustomModal та посилатися на об’єкт $modal, який він повертає. Проте callbackBefore теж не дуже корисний, тому моя порада — просто уникайте цих параметрів, коли це можливо.
onClose
Дуже корисна функція, яка вам може знадобитися. Він обробляє модальне закриття, і якщо функція повертає false, модальний не буде закритий. Якщо ваша програма наразі запущена, і ви хочете запобігти випадковому закриттю користувача модального режиму, вам доведеться скористатися цим. Використовуйте це з розумом.
onCreate
Порівняно дуже марна функція. Він викликається з посиланням на діалогове вікно обгортання (яке відкидається) та на модальну обгортку. Це як callback, але має один додатковий параметр, який не служить жодній меті. Не використовуйте жодного з них.
escapeToClose
Закривати чи не модальний режим при натисканні клавіші «escape». Булеве. Не змінюйте, якщо у вас немає вагомих причин, наприклад, запобігати випадковому закриттю модального режиму. Однак, навіть якщо це так, ви використовуєте обробник onClose, який повертає false, і зупинить закриття модального режиму, якщо ви не зробите це за допомогою closeModal. Значення за замовчуванням true
showCloseButton
Логічне значення, яке вирішує, чи відображатиметься клавіша «X» у верхньому правому куті.
blackoutOpacity
Непрозорість на тлі модального. Це число від 0 до 1. За замовчуванням: 0.65
tabsOutsideContent
Старі налаштування для компонента modal-tabs, ви не повинні знайти для цього жодної користі. Бібліотека не надає жодних функцій для створення цих компонентів вкладки.
topOffset
Верхнє зміщення в пікселях, яке буде модальним від верхньої частини екрана. Має бути числом. Ймовірно, вам слід залишити це значення за замовчуванням. За замовчуванням: 50
zIndex
Щоб змінити стандартний z-index. Ви не повинні відміняти це без поважних причин.
noHeadline
Логічне значення, яке переміщує елемент модального заголовка над клавішею закриття, якщо він існує. Це може бути видалено в майбутньому, це потворно і безглуздо.
suppressDefaultStyles
Це в назві, видаляє більшість властивостей css за замовчуванням, наданих модальному. Вам доведеться розмістити його вручну.
persistent
Логічне значення того, чи слід використовувати hideModal замість closeModal внутрішньо, зберігаючи модальний вміст для показу пізніше за допомогою showModal. Не очікуйте, що користувачі зрозуміють цю поведінку без пояснень, вони, швидше за все, очікуватимуть втрати прогресу, якщо модал закрити.
resizeModal
Чи потрібно автоматично обробляти модальне змінення розміру. Ймовірно, це не має ефекту. Не використовуйте його.

Приклади[]

Основне використання[]

Ви імпортуєте скрипт і зареєструєте хук, який після завантаження скрипту негайно покаже модальний.

importArticle({
    type: 'script',
    article: 'u:dev:MediaWiki:ShowCustomModal.js'
});

mw.hook('dev.showCustomModal').add(function() {
    dev.showCustomModal('Hello, world!');
});

У наведеному вище прикладі параметр функції зворотного виклику mw.hook ігнорується. Ви можете використовувати його для виклику власної модальної функції, але використання dev.showCustomModal у більшості випадків простіше.

Використання клавіш та вмісту[]

Відтепер усі приклади передбачають, що ви запускаєте код всередині або після запуску гачка.

Щоб мати клавіші, потрібно використати другий аргумент для функції showCustomModal та надати масив buttons:

dev.showCustomModal('Clickity', {
    content: 'Натисніть клавішу, щоб показати другий модаль!',
    buttons: [
        {
            message: 'Modalception',
            defaultButton: true,
            handler: function() {
                dev.showCustomModal('Ти зробив це!', 'Хороша робота.');
            }
        }
    ]
});

Як ви можете бачити з прикладу вище, ви можете показувати модалі поверх модалів. Modal не може цього зробити, OOUI цього не дозволяє.

Ви також можете побачити, що другий виклик showCustomModal використовує рядок як другий параметр. Це пояснюється тим, що ви можете надати вміст як другий аргумент функції, а потім як необов’язковий об’єкт параметрів як третій.

Однак це не рекомендується, і в ідеалі ви повинні завжди використовувати об’єкт для другого аргументу, коли це можливо. Він пропонується з міркувань зворотної сумісності та як зручність для дуже простих випадків.

Ручне керування закриттям модалів[]

У цьому розділі буде пояснено кілька аспектів, що стосуються закриття модалів у ShowCustomModal

showCloseButton — це властивість параметрів, яка визначає, чи повинна відображатися клавіша «X» у верхньому лівому куті

escapeToClose аналогічна властивість, яка вирішує, чи слід закривати ключ, закриваючи модальний

Ви не можете змінити, чи натискання задника закриває модальний режим (це завжди відбувається), але ви можете визначити власну функцію onClose, яка повертає false

Наприклад, якщо ви хочете показати модал, який неможливо закрити (не робіть цього!), Захопивши користувача в пастку, ви можете зробити це:

dev.showCustomModal("Ви в пастці!", {
    content: 'Mwahaha',
    onClose: function() {
        // Втечі немає!
        return false;
    }
});

Зауважте, що в цьому прикладі все ще є клавіша «X», але натискання на неї запускає обробник onClose і робить його марним.

Це досить безглуздо, проте це може бути корисним, якщо ви хочете контролювати, коли модал може закритися!

Наприклад, якщо ви хочете відключити закриття модального режиму під час виконання певної умови:

dev.showCustomModal("Ви можете закрити лише тоді, коли хвилини парні", {
    onClose: function() {
        return new Date().getMinutes() % 2 === 0;
    }
});

Однак, якби ми не сказали користувачу, коли модал закривається, це було б досить погано.

Ви можете показати користувачеві другий модал, щоб підтвердити, що він дійсно хоче закрити модаль. Ось що робить MassCategorization, якщо користувач намагається закрити модал під час його роботи, щоб користувач не втратив прогрес!

var $modal = dev.showCustomModal('Закрити підказку', {
    onClose: function() {
        var $confirmation = dev.showCustomModal('Ви впевнені, що хочете закрити?', {
            buttons: [
                {
                    message: 'Ні!',
                    defaultButton: true,
                    handler: function() {
                        dev.showCustomModal.closeModal($confirmation);
                    }
                },
                {
                    message: 'Так!',
                    handler: function() {
                        dev.showCustomModal.closeModal($confirmation);
                        dev.showCustomModal.closeModal($modal);
                    }
                }
            ]
        });

        // Ми завжди повертаємо false, показуючи замість цього модальний; використання вручну showCustomModal.closeModal не викликає цю функцію!
        return false;
    }
});

У цьому прикладі набагато більше рухомих частин, тому давайте проаналізуємо його:

  1. Модаль має властивість onClose з функцією, яка завжди повертає false і показує модальну підказку
  2. Модаль підказки має дві клавіші: Так і ні
  3. Ні закриває модал підтвердження, залишаючи оригінальний модаль показаним
  4. Так закриває модальний режим підтвердження та оригінал

Але зачекайте! Наш оригінальний модал має функцію onClose, яка завжди повертає false! Чи не показував би він інший модаль?

Хороший улов! showCustomModal.closeModal повністю обходить обробник onClose, тому вам не потрібно турбуватися про це.

Вищезазначене є досить корисною моделлю, яку ви, можливо, захочете прийняти, якщо ваші модалі містять потенційно конфіденційну інформацію, яку ви не хочете, щоб користувач випадково втратив.

Ви також можете заховати праву верхню клавішу «X», поки модал не повинен бути закритий. Для цього немає API, але деякі маніпуляції з CSS або DOM повинні завести вас далеко.

Використання з i18n-js[]

I18n-js-де-факто стандарт для вбудовування перекладів у ваші скрипти, він дозволяє використовувати багато можливостей для параметрів та форматів ваших повідомлень.

Зокрема, оскільки ShowCustomModal використовує HTML для більшості своїх рядкових вхідних даних, це корисно для його функцій екранування HTML:

dev.showCustomModal(i18n.msg('modal-title').escape(), {
    content: i18n.msg('modal-contents').escape(),
    buttons: [
        {
            message: i18n.msg('modal-button').escape()
        }
    ]
});

Майте на увазі, що у наведеному вище коді ви, напевно, вже отримали екземпляр i18n із перекладами вашого скрипту.

Це виходить за рамки цього прикладу, але ви можете переглянути I18n-js для прикладу використання або подивитися на більш складну програму зі складним управлінням залежностями.

Використання з Dorui[]

Якщо ви передбачаєте, що вміст вашого модалю буде складним, ви можете скористатися бібліотекою інтерфейсу користувача.

jQuery настільки вийшов з моди, тому давайте використовувати Dorui поряд з i18n-js, для реалістичного прикладу:

var $modal = dev.showCustomModal(i18n.msg('my-modal-title').escape(), {
    content: ui.div({
        id: 'my-modal-wrapper',
        children: [
            // Використання .plain () як Dorui замінює рядки HTML за замовчуванням
            i18n.msg('my-modal-description').plain(),
            ui.div({
                id: 'random-number-container',
                text: Math.random()
            })
        ]
    }),
    buttons: [
        {
            message: i18n.msg('my-modal-button-randomize').escape(),
            defaultButton: true,
            handler: function() {
                $modal.find('#random-number-container').text(Math.random());
            }
        },
        {
            message: i18n.msg('my-modal-button-close').escape(),
            handler: function() {
                dev.showCustomModal.closeModal($modal);
            }
        }
    ]
});

Вау! Це дуже багато коду, сподіваюся, прочитавши його раз або два, ви зможете розрізнити, що відбувається.

Все ще втрачено? Ось пояснення:

  1. Це створення модального з заголовком повідомлення i18n my-modal-title, деяким вмістом та деякими клавішами
  2. Він призначає модальний змінній $modal
  3. Вміст є елементом <div> з id="my-modal-wrapper"
  4. Його дочірні елементи — це два елементи: один текстовий вузол з описом того, що таке модальний (щось про показ випадкового числа та оновлення його однією з кнопок), і контейнер випадкових чисел
  5. Цей контейнер випадкових чисел створюється з деяким випадковим текстом спочатку з Math.random ()
  6. Існує клавіша рандомізації, яка знаходить контейнер випадкових чисел всередині модального і встановлює його текст знову на Math.random ()
  7. Існує клавіша закриття, яка закриває модал за допомогою посилання $modal, яке ми зробили раніше

Зрозумів? Так? Ні? Чудово.

Перенесення з $.showCustomModal[]

Якщо ви хочете перенести застарілий скрипт для використання ShowCustomModal, вам потрібно імпортувати цю бібліотеку, прослухати хук і замінити посилання на $.showCustomModal на експортовану функцію dev.showCustomModal. Ось кілька прикладів людей, які здійснюють міграцію:

  1. Discord: тут я
  2. I18nEdit: тут, також я
  3. Medals: тут від HumansCanWinElves
  4. FAQ: тут від Agent Zuri

Перенесення з Modal-js[]

Якщо ви приїжджаєте з OOUI modals, можливо, ви захочете прийняти ShowCustomModal незалежно від того, оскільки це не накладає обмеження по висоті, а переформатування відбувається автоматично.

Кожен виклик функції showCustomModal створює власний екземпляр, тому вам не потрібно оновлювати вміст, події та кнопки, якщо вони є динамічними у кожному показі модального

Ще немає портів від Modal-js до ShowCustomModal, але MassCategorization є потенційною мішенню через його дуже динамічний розмір вмісту за своєю природою.

Advertisement