ShowCustomModal/tr — dev

ShowCustomModal artık kullanılmayan $.showCustomModal nesnenin işlevlerini kopyalayan bir JavaScript kitaplığıdır.

Artık küresel jQuery nesnesi aracılığıyla gösterilmez, bunun yerine bir mw kancası aracılığıyla gösterilir. Bu kanca, $.showCustomModal nesneye karşılık gelen bir işlevle tetiklenir ve ayrıca closeModal gibi modal manipülasyonla ilgili diğer yöntemleri içerir.

Varlığının kökleri iki faktöre dayanmaktadır: Modal destek gerektiren eski betikler mevcuttur, alternatifler Modal-js ve QDmodal betiktir. Onlara taşımak önemsiz değildir. Bu, bu geçişi kolaylaştırmak için var. Var olmasının bir başka nedeni de, hem Modal-js'nin (çoğunlukla OOUI köklü) hem de QDmodal'ın eksikliklerine bir alternatif ve daha basit bir durum bilgisi olmayan modal işlev çağrısı sağlamanın yanı sıra arşivsel nedenlerdir.

İçe aktarma

Bunun nasıl olduğunu biliyorsunuz.

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

mw.hook('dev.showCustomModal').add(function(showCustomModal) {
    // Kodunuz buraya
    // `showCustomModal`, `window.dev.showCustomModal` için bir bağlayıcıdır
});

<documentation>

Kanca, tek bir işlevi, showCustomModal işlevini dışa aktarır. Bu bir oluşturucu değil, onu new ile çağırmazsınız; bir modal göstermek için onu çağırırsınız ve o, oluşturulmuş modal jQuery nesnesini döndürür.

Daha önce $.showCustomModal kullandıysanız, tamamen geriye dönük uyumludur. Bunun anlamı, bulabileceğiniz herhangi bir $.showCustomModal çağrısının dev.showCustomModal ile değiştirilebileceği ve kullanmadan önce kancanın ateşlendiğinden emin olduğunuz sürece "Şimdi Çalışacaktır".

JavaScript'teki işlevler de nesnelerdir; bu, bir işlevin özelliklere sahip olabileceği anlamına gelir. Dışa aktarılan showCustomModal işlevi bunlardan bazılarına sahiptir, örneğin closeModal. Kullanmak isteseydiniz showCustomModal tarafından döndürülen jQuery nesnesine olan referansınızı alır ve onu şöyle çağırırdınız: showCustomModal.closeModal($modal)

showCustomModal(title, content?, options?): Ana işlev. İlk parametre bir dizedir ve modalın başlığıdır. HTML olarak yorumlanır, bu yüzden onu temizlemeniz gerekir. Tekrar etmekte fayda var: hem başlık hem de içerik HTML olarak yorumlanır, mw.html.escape gibi önlemler kullanmazsanız komut dosyanız savunmasız olacaktır.; Bunun dışında, ikinci parametre içeriktir ve üçüncüsü, kullanabileceğiniz birçok özelliğe sahip bir seçenekler nesnesidir. Bunlardan biri de content değeridir, yani ikinci niteliği geçmekten kaçınabilir ve onu bir options nesnesiyle değiştirebilirsiniz. Bu kullanım da geçerlidir: showCustomModal(title, { content: string, ...otherOptions }); options nesnesi, daha sonra düzgün bir şekilde belgelenecek olan birçok faydalı özelliğe sahiptir.
showCustomModal.closeModal($modal): İkinci dışa aktarılan işlev ve büyük olasılıkla sağlanan oldukça niş ekstra işlevlerin en kullanışlısı.; .modalWrapper ögelerine başvuran bir jQuery örneği verildiğinde, bunları kapatacak ve arka planlarından kurtulacaktır.; Birden çok modal örneğiniz varsa ve bunlardan birini kapatırsanız, hâlâ gösterilen bir kip olsa bile gövde sınıfı .modalShown sınıfının kaldırılacağı bir hata var. Bu sınıf için gerçekten bir kullanım durumunuz varsa, tartışma sayfasına bir mesaj bırakın. Şimdilik sınıfı kullanmamanız tavsiye ediliyor.
showCustomModal.hideModal($modal) & showCustomModal.showModal($modal): Bu işlevler modalları gizler ve gösterir, seçenekler persistent özelliğini belirttiğinizde dahili olarak kullanılırlar. Bunlar bildiğim kadarıyla herhangi bir geliştirici betiğinde hiç kullanılmadı, bu yüzden muhtemelen bunlara veya yukarıdaki özelliklere ihtiyacınız yok. Bununla birlikte, bir modalı kapattıktan sonra durumunu korumak istediğiniz bir kipe ihtiyacınız varsa, kullanıcının bir modalı yeniden açmadan önce arka plana bir göz atmasına izin vermek istemeniz durumunda işlevsellik buradadır.
showCustomModal.makeModal($dialog, options) & showCustomModal.getModalTopOffset($modal): Bunlar uygulama ayrıntısı işlevleridir. Onları kullanmayın. Ya da seni bulurum ve beni kötü bir ruh halinde görmek istemezsin. Madmin nişanlandı.

Options nesnesi

showCustomModal için üçüncü (veya content atlanırsa ikinci) parametre. Modalınıza uygulamak isteyebileceğiniz birçok faydalı özelliği olan sade bir nesnedir. Karmaşıklığın büyük bir kısmının yattığı ve "showCustomModal" nesneden gelen "custom" değerin geldiği yer burasıdır.

Burada, kabaca en az kullanışlı olacak şekilde sıralanmış mevcut tüm özellikler ve aynı zamanda hakkında bilmeniz gereken id ve width gibi basit ama etkili özellikler de destekleniyor. Alt yarısı muhtemelen kırılmış, işe yaramaz ve uyumluluk nedenleriyle değilse çıkarılmaya eğilimlidir.

content

Bunu yalnızca showCustomModal(title, options) için imza kullanıyorsanız kullanmalısınız. Eski imza geriye dönük uyumluluk için mevcut olsa bile işlev çağrısını daha basit tutmak için biçimsel bir seçim olarak sağlanır.

buttons

options nesnesindeki en yaygın ve kullanışlı özellik. Modalın altında gösterilecek bir dizi düğme tanımlamanıza izin verir. İmzası [{ defaultButton: boolean, message: string, id: string, handler: function(event) }] şeklindedir.

defaultButton

Düğmenin birincil olarak işaretlenip işaretlenmeyeceğini belirten bir boole. Birincil düğmeler daha koyu olurken, ikincil düğmeler genellikle daha az göze çarpar.

message

Düğmenin içeriği. Bu HTML'dir, yani sanitasyonla ilgili önceki tüm uyarılar hala geçerlidir. Cinsel yolla bulaşan hastalıklardan uzak kalmak için I18n-js .escape() veya mw.html.escape() gibi işlevleri kullanın.

id

Düğmeye atanacak id özniteliği. Genellikle, bu özellik hakkında endişelenmemeli veya umursamamalısınız. Yine de, bazı düğmeleri programlı olarak devre dışı bırakmak istiyorsanız kullanışlı olabilir ve siz sağlamazsanız düğmelerin id="undefined" içermemesine neden olan bir hata düzeltildi.

handler

Modalı tıkladığınızda yürütülecek bir işlev. Örneğin, bir kapatma düğmesi showCustomModal.closeModal nesneyi çağıran bir kapatma çağrısı yapabilir. Muhtemelen message değerden sonra en kullanışlı ikinci parametredir.

width: Modalın ne kadar geniş olacağına karar veren bir dizi piksel veya CSS boyut birimine sahip bir dize. Varsayılan: 400, örnekler: 420, '50%', '100vw'
height: Modalın ne kadar uzun olacağı, tıpkı width gibi. Muhtemelen bunu varsayılan değerine bırakmalısınız. Varsayılan: auto
id: Modal sarmalayıcı ögesini vermek için bir kimlik. Atlanırsa, rastgele atanacaktır.
className: Modal sarmalayıcıya modalWrapper üzerine eklenecek bir sınıf.
callbackBefore, callback: Modaldan önce ve sonra çağrılacak işlevler sırasıyla oluşturulur. callback çok kullanışlı değildir, çünkü içeriği showCustomModal çağrısından sonra yerleştirebilir ve döndürdüğü $modal nesnesine yapabilirsiniz. Yine de, callbackBefore da çok kullanışlı değil, bu yüzden tavsiyem, mümkün olduğunca bu parametrelerden uzak durmak.
onClose: İhtiyacınız olabilecek çok kullanışlı bir işlev. Modal kapatmayı yönetir ve işlev false döndürürse, mod kapatılmaz. Programınız şu anda çalışıyorsa ve bu arada kullanıcının modu yanlışlıkla kapatmasını önlemek istiyorsanız, bunu kullanmalısınız. Akıllıca kullanın.
onCreate: Nispeten çok işe yaramaz bir işlev. Sarma iletişim kutusuna (atılır) ve modal sarmalayıcıya referansla çağrılır. callback gibidir, ancak hiçbir amaca hizmet etmeyen fazladan bir parametresi vardır. Bunların hiçbirini kullanmayın.
escapeToClose: Esc tuşuna basıldığında modalın kapatılıp kapatılmayacağı. Bir boole. Yanlışlıkla modal kapanışları önlemek gibi iyi bir nedeniniz olmadıkça geçersiz kılmayın. Ancak öyle olsa bile, false döndüren bir onClose işleyicisinden yararlanırsınız ve bunu closeModal ile yapmadığınız sürece modalın kapanmasını durdurursunuz. Varsayılan değer true şeklindedir.
showCloseButton: Sağ üst köşedeki "X" düğmesinin gösterilip gösterilmeyeceğine karar veren bir boole değeri.
blackoutOpacity: Modalın arka planını vermek için opaklık. 0 ile 1 arasında bir sayıdır. Varsayılan: 0.65
tabsOutsideContent: Bir modal-tabs bileşeni için eski ayar, bunun bir faydasını görmemelisiniz. Kitaplık, bu sekme bileşenlerini oluşturmak için hiçbir işlevsellik sağlamaz.
topOffset: Modalın ekranın üstünden olacağı piksel cinsinden üst ofset. Bir sayı olmalı. Muhtemelen bunu varsayılan değerine bırakmalısınız. Varsayılan: 50
zIndex: Varsayılan z-endeksini geçersiz kılmak için. İyi bir sebep olmadan bunu geçersiz kılmamalısınız.
noHeadline: Varsa, kalıcı başlık öğesini kapat düğmesinin üzerine taşıyan bir boole. Bu gelecekte kaldırılabilir, çirkin ve aptalca.
suppressDefaultStyles: Adında, modala verilen çoğu varsayılan CSS özelliğini kaldırır. Elle konumlandırmanız gerekecek.
persistent: Dahili olarak closeModal yerine hideModal kullanılıp kullanılmayacağına ilişkin bir boole, showModal ile daha sonra gösterilmek üzere modal içerikleri tutar. Kullanıcıların açıklama yapmadan bu davranışı anlamalarını beklemeyin, modal kapatılırsa muhtemelen ilerlemenin kaybedileceğini bekleyeceklerdir.
resizeModal: Modal yeniden boyutlandırmanın otomatik olarak işlenip işlenmeyeceği. Bunun muhtemelen bir etkisi yoktur. Onu kullanma.

Examples

Temel kullanım

Betiğini içe aktaracak ve betik yüklendikten sonra hemen bir modal gösterecek bir kanca kaydedeceksiniz.

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

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

Yukarıdaki örnekte, mw.hook geri çağrı işlevinin parametresi yok sayılır. Özel modal işlevi çağırmak için kullanabilirsiniz, ancak dev.showCustomModal nesneyi kullanmak çoğu durumda daha kolaydır.

Düğmeleri ve içeriği kullanma

Şu andan itibaren, tüm örnekler, kodu kancanın içinde veya tetiklendikten sonra çalıştırdığınızı varsayar.

Düğmelere sahip olmak için, showCustomModal işlevinin ikinci argümanını kullanmanız ve buttons dizisini sağlamanız gerekir:

dev.showCustomModal('Tıklama', {
    content: 'İkinci bir modalı göstermek için düğmeyi tıklayın!',
    buttons: [
        {
            message: 'Modalsepyon',
            defaultButton: true,
            handler: function() {
                dev.showCustomModal('Başardın!', 'İyi iş.');
            }
        }
    ]
});

Yukarıdaki örnekte de görebileceğiniz gibi, modalları modalların üzerinde gösterebilirsiniz. Modal bunu yapamaz, OOUI buna izin vermez.

Ayrıca, ikinci showCustomModal çağrısının ikinci parametre olarak bir dize kullandığını da görebilirsiniz. Bunun nedeni, işlevin ikinci bağımsız değişkeni olarak içeriği ve üçüncü olarak isteğe bağlı bir seçenekler nesnesini sağlayabilmenizdir.

Yine de bu önerilmez ve ideal olarak mümkün olduğunda ikinci bağımsız değişken için her zaman bir nesne kullanmalısınız. Geriye dönük uyumluluk nedenleriyle ve çok basit durumlar için kolaylık sağlamak amacıyla sunulmaktadır.

Modal kapanışının elle işlenmesi

Bu bölüm, ShowCustomModal'da kapanan modallarla ilgili birkaç yönü açıklayacaktır.

showCloseButton, sol üstteki "X" düğmesinin gösterilip gösterilmeyeceğini kontrol eden bir options özelliğidir.

escapeToClose, modalı kapatarak escape anahtarının kullanılıp kullanılmayacağına karar veren benzer bir özelliktir.

Arka plana tıklamanın modalı kapatıp kapatmayacağını değiştiremezsiniz (her zaman kapatır), ancak false döndüren kendi onClose işlevinizi tanımlayabilirsiniz.

Örneğin, kapatılamayan bir kip göstermek istiyorsanız (bunu yapmayın!), kullanıcıyı hapsederek, bunu yapabilirsiniz:

dev.showCustomModal("Tuzağa düştün!", {
    content: 'Mwahaha',
    onClose: function() {
        // Kaçış yok!
        return false;
    }
});

Bu örnekte hâlâ bir "X" düğmesi olduğunu unutmayın, ancak buna tıklandığında onClose işleyicisi tetiklenecek ve onu işe yaramaz hâle getirecektir.

Bu oldukça anlamsız, ancak modalın ne zaman kapanabileceğini kontrol etmek istiyorsanız bu yararlı olabilir!

Örneğin, belirli bir koşul karşılanırken modu kapatmayı devre dışı bırakmak istiyorsanız:

dev.showCustomModal("Yalnızca dakikalar çift olduğunda kapatabilirsiniz", {
    onClose: function() {
        return new Date().getMinutes() % 2 === 0;
    }
});

Ancak, modalın ne zaman kapatılabileceğini kullanıcıya tam olarak söylemeseydik, bu oldukça kötü bir kullanıcı deneyimi olurdu.

Kullanıcının modalı gerçekten kapatmak istediğini onaylaması için ikinci bir modal gösterebilirsiniz. MassCategorization, kullanıcı modalı çalışırken kapatmaya çalışırsa bunu yapar, böylece kullanıcı ilerlemesini kaybetmez!

var $modal = dev.showCustomModal('İstemi kapat', {
    onClose: function() {
        var $confirmation = dev.showCustomModal('Kapatmak istediğinizden emin misiniz?', {
            buttons: [
                {
                    message: 'Hayır!',
                    defaultButton: true,
                    handler: function() {
                        dev.showCustomModal.closeModal($confirmation);
                    }
                },
                {
                    message: 'Evet!',
                    handler: function() {
                        dev.showCustomModal.closeModal($confirmation);
                        dev.showCustomModal.closeModal($modal);
                    }
                }
            ]
        });

        // Bunun yerine bir modal göstererek her zaman false döndürürüz; showCustomModal.closeModal kılavuzunu kullanmak bu işlevi çağırmaz!
        return false;
    }
});

Bu örnekte çok daha fazla hareketli parça var, o yüzden onu analiz edelim:

Modal, her zaman false döndüren ve bir bilgi istemi modalın gösteren bir işleve sahip bir onClose özelliğine sahiptir
Bilgi istemi modalında iki düğme vardır: Evet ve hayır
Hayır, onay modalı kapatır ve gösterilen orijinal modalı bırakır
Evet, hem onay modunu hem de orijinali kapatır

Fakat bekle! Orijinal modalımızın her zaman false döndüren bir onClose işlevi vardır! Başka bir modal göstermez miydi?

İyi yakalama! showCustomModal.closeModal, onClose işleyicisini tamamen atlar, dolayısıyla bu konuda endişelenmenize gerek yoktur.

Yukarıdakiler, modallarınızda kullanıcının kazara kaybetmesini istemediğiniz potansiyel olarak hassas bilgiler varsa, benimsemek isteyebileceğiniz oldukça yararlı bir kalıptır.

Modal kapatılmamalıyken sağ üstteki "X" düğmesini de gizlemek isteyebilirsiniz. Bunun için bir API yok, ancak bazı CSS veya DOM manipülasyonları sizi oldukça uzağa götürebilir.

i18n-js ile kullanım

I18n-js, betiklerinize çeviriler eklemek için fiili standarttır, mesajlarınız için parametreler ve biçimler için birçok kolaylığa izin verir.

Özellikle, ShowCustomModal dize girişlerinin çoğu için HTML kullandığından, HTML'den kaçış işlevi için kullanışlıdır:

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

Yukarıdaki kodda, betiğinizin çevirileriyle zaten bir i18n örneği almış olmanız gerektiğini unutmayın.

Bu, bu örneğin kapsamı dışındadır, ancak örnek bir kullanım için I18n-js'ye veya gelişmiş bağımlılık yönetimine sahip daha bir karmaşık programına bakabilirsiniz.

Dorui ile kullanım

Modalınızın içeriğinin karmaşık olacağını tahmin ediyorsanız, bir kullanıcı arayüz kitaplığı kullanmak isteyebilirsiniz.

jQuery'nin çok modası geçti, bu yüzden gerçekçi bir örnek için i18n-js ile birlikte Dorui kullanalım:

var $modal = dev.showCustomModal(i18n.msg('my-modal-title').escape(), {
    content: ui.div({
        id: 'my-modal-wrapper',
        children: [
            // .plain() ögesinin Dorui olarak kullanılması varsayılan olarak HTML dizelerinden kaçar
            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);
            }
        }
    ]
});

Fiv! Bu çok fazla kod, umarım bir veya iki kez okuyarak neler olup bittiğini anlayabilirsiniz.

Hâlâ kayıp mısınız? İşte bir açıklama:

i18n mesajı my-modal-title başlığı, bazı içerikler ve bazı düğmelerle bir modal oluşturuyor
Modalı $modal değişkenine atar
İçerik, id="my-modal-wrapper" içeren bir <div> ögesidir
Atları iki ögedir: Modalın ne olduğunu açıklayan bir metin düğümü (rastgele bir sayı göstermek ve onu düğmelerden biriyle yenilemekle ilgili bir şey) ve bir rasgele sayı kapsayıcı
Bu rasgele sayı kapsayıcı, başlangıçta Math.random() ile bazı rasgele metinlerle oluşturulur.
Modal içindeki rasgele sayı kapsayıcısını bulan ve metnini yeniden Math.random() olarak ayarlayan bir rasgele düğme vardır
Daha önce $modal yaptığımız referansla modu kapatan bir kapatma düğmesi var

Anladınız mı? Evet? Hayır? Mükemmel.

$.showCustomModal nesneden içe aktarma

Eski bir betiği ShowCustomModal'ı kullanacak şekilde taşımak istiyorsanız, bu kitaplığı içe aktarmanız, kancayı dinlemeniz ve $.showCustomModal referanslarını dışa aktarılan dev.showCustomModal işleviyle değiştirmeniz gerekir. Taşıma işlemini gerçekleştiren insanlara bazı örnekler:

Discord: burada benim tarafından
I18nEdit: burada, ayrıca benim tarafından
Medals: burada HumansCanWinElves tarafından
FAQ: burada Agent Zuri tarafından

Modal-js betiğinden içe aktarma

OOUI modallarından geliyorsanız, yükseklik sınırlaması getirmediği ve yeniden akışlar otomatik olduğu için ShowCustomModal'ı ne olursa olsun benimsemek isteyebilirsiniz.

showCustomModal işlevine yapılan her çağrı kendi örneğini oluşturur, böylece kipin her gösterisinde dinamiklerse içeriği, olayları ve düğmeleri yenilemeniz gerekmez.

Henüz Modal-js'den ShowCustomModal'a herhangi bir bağlantı noktası olmadı, ancak MassCategorization, doğası gereği oldukça dinamik içerik boyutu nedeniyle potansiyel bir hedef.