Blockly API'lerini kullanma

Giriş

Bu sayfada, işlevleri çağırma ve temel Blockly'deki özelliklere erişmeyle ilgili en iyi uygulamalar açıklanmaktadır. Bu ilkeler, Blockly için eklenti oluşturma veya Blockly'yi bağımsız bir uygulamaya entegre etmede geçerlidir.

Alt sınıflandırma ve genişletme

Blockly, işlev eklemek için aşağıdakiler de dahil olmak üzere birden fazla paradigmaya sahiptir:

  • Alt sınıflar (ör. yeni bir oluşturucu oluşturma)
  • Mix'ler (ör. bir blok uzantısı veya mutatör ekleme)
  • Engelleme tanımları (ör. prosedür bloğu tanımları)

Bu belgenin amaçları doğrultusunda, üç durum da alt sınıflandırmaya eşdeğerdir.

Alt sınıf ekleme

Blockly.inject yöntemiyle belirli sınıfların değiştirilmesi desteklenmektedir. Bu alt sınıflar, temel sınıfı genişletmeli veya karşılık gelen arayüzlerini uygulamalıdır.

Alt sınıfınızı ekleme yöntemine geçirebilirsiniz.

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': CustomMetricsManagerClass
  }
}

İsterseniz sınıfınızı Blockly.registry kullanarak kaydedebilir ve sınıfı eklemek için kayıt defteri adını kullanabilirsiniz. Ekleme seçeneklerinizi sadece JSON olarak depoluyorsanız bu yöntem faydalıdır.

Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': 'YOUR_NAME'
  }
}

Aşağıdaki sınıflar değiştirilebilir:

Kayıt Adı Arayüz/Temel Sınıf
blockDragger Blockly.IBlockDragger
connectionChecker Blockly.IConnectionChecker
connectionPreviewer Blockly.IConnectionPreviewer
flyoutsVerticalToolbox Blockly.IFlyout
flyoutsHorizontalToolbox Blockly.IFlyout
metricsManager Blockly.IMetricsManager
renderer Blockly.blockRendering.Renderer
toolbox Blockly.IToolbox

Arayüzleri kullanma hakkında daha fazla bilgi için belgelerin arayüzler bölümüne göz atın.

Görüş mesafesi

Çekirdek kitaplıktaki görünürlüğü public, private veya protected olarak işaretlemek için TypeScript erişim değiştiricilerini kullanırız. Bazı mülklere TsDoc yorumlarında @internal ek açıklaması eklenebilir.

Tüm public ve protected özellikleri, Blockly web sitesinin Referanslar bölümünde açıklanmıştır. Görünürlüğü kodu okuyarak da kontrol edebilirsiniz.

herkese açık

public olarak işaretlenen her şey, herkese açık API'mizin bir parçasıdır. Bir modülde yer alan ve görünürlük değiştiricisi olmayan tüm mülkler herkese açık olarak kabul edilir.

Genel API'mizi sık sık veya geçerli bir neden ve uyarı olmadan değiştirmemeye çalışıyoruz. Buna istisna olarak, yeni bir API'yi bir sürümde herkese açık hale getirebilir ve erken geri bildirimlere yanıt olarak bir sonraki sürümde değiştirebiliriz. Daha sonra, kamuya açık bir işlev veya kararlı mülk kullanmayı düşünebilirsiniz.

Herkese açık işlevler herhangi bir yerden çağrılabilir ve imza değişmediği sürece alt sınıflarda geçersiz kılınabilir.

korumalı

Korunan işlevlere ve özelliklere yalnızca tanımlayıcı sınıf veya bir alt sınıf erişebilir.

Alt sınıfların, tür imzaları değiştirilmeden korunan işlevleri ve özellikleri geçersiz kılmasına izin verilir.

Örneğin, temel oluşturucu sınıfını genişleten bir özel oluşturucu, korunan özelliklerine erişebilir.

Her durumda, işlevin veya özelliğin kodun geri kalanında nasıl kullanıldığını anladığınızdan emin olmalısınız.

private

Bunlara yalnızca tanımla aynı dosyadaki kod tarafından erişilebilir. Bu özelliklere doğrudan erişmek, tanımsız davranışa neden olabilir.

Alt sınıfların gizli işlevleri ve özellikleri geçersiz kılmasına izin verilmez.

Özel mülkler, Blockly'nin herkese açık API'sinin bir parçası olarak değerlendirilmediğinden uyarı yapılmaksızın değiştirilebilir.

Blockly uygulamasındaki bazı işlevler, modüllerinden dışa aktarılmadığı için görünürlük ek açıklamalarına sahip değildir. Bu işlevler temelde yerel değişkenlerdir ve tanımlama modüllerinin dışında kullanılamazlar. Özel mülklere eşdeğer kabul edilmelidir.

internal

Dahili işlevler ve özelliklerin, harici olarak değil, temel kitaplık içinde kullanılması amaçlanmıştır. Bunlar, TsDoc @internal notasyonuyla belirtilir.

Dahili mülkler Blockly'nin herkese açık API'sinin bir parçası olarak değerlendirilmediğinden, uyarı yapılmaksızın değiştirilebilir.

Dahili özelliklere çekirdek içindeki herhangi bir yerden erişilebilir ve imza değişmediği sürece çekirdekteki alt sınıflarda geçersiz kılınabilir. Bunlara çekirdek kitaplığın dışından erişilmemesi gerekir.

desteği sonlandırıldı

@deprecated işareti kullanılmamalıdır. Çoğu kullanımdan kaldırma işlemi, bir konsol uyarısında veya TSDoc'ta, tercih edilen kodla ilgili talimatları içerir.

Mümkün olduğunda kullanımdan kaldırılan işlevler, planlanan silme tarihini ve yeni bir işlev çağırması için öneriyi içeren bir uyarı kaydeder.

SSS

Kullanmak istediğim işlev herkese açık değilse ne olur?

Temel Blockly için bir özellik isteği gönderin. Kullanım alanınızın açıklamasını ve herkese açık hale getirmemizi istediğiniz şeyi belirtin.

Bu özelliği, herkese açık olup olmayacağını veya aynı bilgileri edinmenin başka yolları olup olmadığını tartışmak için talep etmek amacıyla kullanacağız.

Herkese açık hale getirmeye karar verirsek, siz veya Blockly ekibi uygun değişikliği yapacak ve bir sonraki Blockly sürümünde hayata geçirecektir.

Eklentide herkese açık olmayan bir üyeyi kullanmayı tercih ederseniz eklentinizi beta olarak işaretleyebilir ve bilgileri README öğenize ekleyebilirsiniz.

Peki ya maymun yamama?

Monkeypatching ile ilgili bilgi edinin.

Monkeypat uygulama, Blockly API'nin herkese açık olmayan parçalarının kullanılması nedeniyle bildirim yapılmadan çalışmayı durdurabileceği için güvenli değildir. Eklentiye yama uygulamak özellikle tehlikelidir çünkü kodunuz, aynı koda yama yapan diğer eklentilerle zayıf bir şekilde etkileşimde bulunabilir. Bu nedenle, uygulamalarda ve üçüncü taraf eklentilerinde monkeypat oluşturma özelliğinin kullanılmamasını önemle tavsiye ederiz ve birinci taraf eklentilerde bunu kabul etmeyeceğiz.

Genel işlevleri geçersiz kılabilir miyim?

Alt sınıflandırma yaparken: evet. Yoksa hayır, maymun yamaması demektir.

Korunan işlevleri geçersiz kılabilir miyim?

Alt sınıflandırma yaparken: evet. Yoksa hayır, maymun yamaması demektir.

Dahili veya gizli işlevleri geçersiz kılabilir miyim?

Hayır, maymun yamaması demektir.

Mülklere ne zaman doğrudan erişebilirim? Ne zaman alıcı mı yoksa setter mi kullanmalıyım?

Bir alıcı veya belirleyici yayınlarsak, lütfen mülke doğrudan erişmek yerine bunu kullanın. Mülk herkese açık değilse kesinlikle alıcı ve belirleyicileri kullanın.

Bir mülkün ek açıklaması yoksa ne olur?

Varsayılan olarak herkese açıktır, ancak sizin için bir toplayıcı/ayarlayıcı çifti eklemek isterseniz lütfen bize bir e-posta gönderin.

Bir fonksiyonun ek açıklaması yoksa ne olur?

Varsayılan olarak herkese açıktır.

Hâlâ emin değilsem ne olacak?

Forumda soru sorun. Genellikle bir iş günü içinde size dönüş yaparız.