Buyurgan Bileşen API'si Oluşturma

Önce sözleşmeyi belirleyerek başlayın: FocusableInput; odaklama, odağı kaldırma ve getValue işlemlerini sunabilir. Bunu forwardRef ile sarın, gerçek girdiye ait dahili bir referans tutun ve useImperativeHandle içinden bu üç yöntemi döndürün.

Her yöntem temel girdiye yetki verir; böylece üst bileşen, ham öğeye dokunmadan tam olarak ihtiyaç duyduğu işlemleri elde eder.

Bir medya bileşeni, imperatif bir API'den büyük ölçüde yararlanır. Bir VideoPlayer; oynatma, duraklatma ve seekTo işlemlerini sunabilir; bunların her biri dahili bir video referansındaki yerel HTMLVideoElement yöntemlerine yetki verir.

seekTo saniye cinsinden bir zaman kabul eder ve currentTime değerini ayarlar. Böylece üst bileşenler, yalnızca özellikler üzerinden yönetilmesi zahmetli olacak oynatma üzerinde hassas denetim elde eder.

Bir Karusel, harici denetimlerin veya klavye işleyicilerinin onu yönetebilmesi için ileri, geri ve goToSlide işlemlerini sunabilir. Dahili olarak bu yöntemler etkin dizin durumunu günceller ve bileşen yeni slaydı yeniden oluşturur.

Bu yaklaşım, imperatif tetikleyicileri deklaratif oluşturmayla birleştirir: üst bileşen bir geçiş komutu verir, karusel ise sonucu normal durum akışı üzerinden oluşturur.

İmperatif bir tutamak herkese açık bir sözleşmedir; bu nedenle her yöntemi, parametrelerini ve dönüş değerini belgeleyin. Açık belgeler, kullanıcılara nelerin desteklendiğini bildirir ve belgelenmemiş dahili ayrıntılara güvenmelerini engeller.

Tutamağı diğer tüm API yüzeyleri gibi ele alın: oynat(), duraklat() ve seekTo(saniye) gibi yöntemleri listeleyen kısa bir başvuru, yanlış kullanımı ve kafa karışıklığını önler.

Kullanıcılar bir tutamağa bağımlı hâle geldikten sonra bir yöntemi kaldırmak veya yeniden adlandırmak geriye dönük uyumluluğu bozan bir değişikliktir. Mevcut imzaları değiştirmek yerine yeni yöntemler ekleyin ve herhangi bir şeyi kaldırmadan önce kullanımdan kademeli olarak kaldırın.

Tutamağı sürümlendirilmiş bir API olarak düşünmek, bileşeni zaman içinde büyüttüğünüzde alt düzey kodun bozulmasını önler.

Gerçek bileşenlerin çoğu her iki yaklaşımı da birleştirir. Bir VideoPlayer, src özelliğini ve autoPlay özelliğini deklaratif olarak kabul ederken, özelliklerin iyi ifade edemediği anlar için imperatif oynat ve seekTo işlemlerini de sunabilir.

Yönerge şudur: durum ve yapılandırma için özellikleri kullanın; imperatif tutamağı ise belirli zamanlarda tetiklenen tek seferlik işlemlerle sınırlayın.

Bir imperatif API'yi sınamak için bileşeni bir referansla oluşturun, etkileşimleri act() içinde sarın ve sunulan yöntemleri ref.current üzerinden çağırın. Ardından videonun duraklatılmış olması veya slayt dizininin değişmesi gibi gözlemlenebilir sonucu doğrulayın.

Bir referans geri çağırımı, oluşturma sırasında tutamağı yakalayabilir; böylece sınamanız yöntemleri çağırabileceği kararlı bir başvuruya sahip olur.

Storybook, imperatif tutamakları sergilemek için iyi bir yerdir. Bir hikâye, bileşene ait bir referans tutabilir ve yöntemlerini çağıran düğmeler oluşturabilir; böylece inceleyenler oynatma, duraklatma veya goToSlide işlemlerini etkileşimli olarak deneyebilir.

Bu hikâyeler aynı zamanda yaşayan belgeler işlevi görür ve imperatif API'nin yalıtılmış durumda tam olarak nasıl davrandığını gösterir.

Imperatif tutamaklar, React dışı kütüphaneler sarılırken yaygın olarak kullanılır. Grafik kütüphaneleri yeniden çizme veya güncelleme yöntemleri, harita SDK'ları panTo ve setZoom işlemleri, zengin metin düzenleyicileri ise insertText veya getContents işlemleri sunar.

Böyle bir kütüphaneyi bir React bileşenine sarmak ve temiz bir tutamak sunmak, uygulamanızın geri kalanına onu yönetmek için düzenli ve deyimsel bir yol sağlar.

Bir tutamaktaki yöntemler çoğu zaman mevcut durumu kapatır; bu nedenle gerektiğinde onları yenilemek için useImperativeHandle'ın bağımlılık dizisini kullanın ve güncel olmayan kapanımları önlemek üzere dahili yardımcılar için useCallback kullanın.

İyi yönetilen bir tutamak her zaman güncel değerlerle çalışır; bu nedenle getValue veya seekTo çağrısı yapan bir üst bileşen, en son oluşturmayla tutarlı bir davranış elde eder.

İmperatif bileşen API'leri için tasarım yönergesini uygulayın.

FocusableInput, VideoPlayer ve Karusel için her biri küçük bir işlem yöntemi kümesi sunan tutamaklar tasarladınız. Kullanıcılar bu yöntemlere herkese açık bir API olarak bağımlı olduğundan onları belgeleyin ve sürümlendirin.

İmperatif işlemleri deklaratif özelliklerle birleştirin, act() içinde ref.current üzerinden sınayın ve davranışı Storybook'ta sergileyin. Aynı yaklaşım grafik, harita ve düzenleyici kütüphanelerini de temiz biçimde sarar.