Block Factory'ye eklenti alanı ekleyin

Blockly Geliştirici Araçları, blokları kullanarak özel bloklar oluşturmanıza olanak tanır. Temel Blockly ile birlikte gelen alanların yanı sıra eklenti olarak yayınlanan alanları da destekler. Özel bir alan oluşturduysanız bu kılavuzu takip ederek Block Factory'ye bu alan için destek ekleyebilirsiniz. Özel alana destek ekleyebilmeniz için önce npm'de yayınlanması gerekir. Ayrıca, Blockly'deki değişikliklere ayak uydurmak için alanınızı güncellemeyi taahhüt etmeniz gerekir. Aksi takdirde, gelecekte alanınızı Block Factory'den kaldırmamız gerekebilir.

Blok Fabrikası'nda Geliştirme

Block Factory'nin kaynak kodu, examples/developer-tools dizinindeki bloklu örnekler deposunda bulunur.

Blok içeren örneklerde Geliştirici Araçları ile ilgili bir değişiklik göndermek için bloklu örneklerde geliştirmeyle ilgili tipik adımları uygulamanız gerekir. Ancak eklentilerle çalışmanın aksine npm install öğesini bloklu örneklerin kök düzeyi yerine doğrudan examples/developer-tools dizininden çalıştırmanız gerekir.

Eklentiyi yükleme

Block Factory'nin, özel alanınızı önizlemede göstermesi için özel alanı yüklemeniz gerekir. Alanınızı, geliştirici araçlarının npm bağımlılığı olarak ekleyin. Ardından, uygulamayı kaydedin veya developer-tools/src/blocks/index.ts'te gerekli diğer kurulum işlemlerini yapın.

Alan için bir blok oluştur

Block Factory özel bloklar oluşturmak için blokları kullandığından özel alanınızı temsil eden bir bloka ihtiyacınız vardır.

Blok tanımı oluşturma

Alanınız için blok tasarlamanız gerekir. Meta almak istiyorsanız Blok Fabrikası'nı kullanarak bile blok tasarlayabilirsiniz! Blok, kullanıcının alanınızın gerektirdiği ayarları (ör. varsayılan değerler ve ad) yapılandırmasına izin vermelidir. Bu engelleme tanımını developer-tools/src/blocks/fields.ts öğesine ekleyin ve developer-tools/src/blocks/index.ts içine aktarın.

Araç kutusuna blok ekle

Daha sonra, bu bloğu kullanıcıların erişebilmesi için araç kutusu tanımına eklemeniz gerekir. Araç kutusu tanımı developer-tools/src/toolbox.ts içindedir. Blokunuz "Fields" kategorisine eklenmelidir.

Kod Oluşturucular

Block Factory, Blockly'den aşina olduğunuz Code Generator sistemini kullanarak çalışır. Her blokta, Block Factory tarafından oluşturulan her çıkış türü için bir blok kodu oluşturucu bulunur ve üst bloklar, alt blokların kodunu doğru çıkışta bir araya getirir. Özel bir alan için destek eklemek isterseniz Kod Oluşturucu sınıflarının her biri için blok kodu oluşturucu işlevleri eklemeniz gerekir.

output-generators/fields dizininde alan blokunuz için bir dosya oluşturun. Bu dosyaya aşağıdaki Oluşturucuların her biri için blok kodu oluşturucuları ekleyeceksiniz. Blok kodu oluşturucu işlevlerinin uygulamaya yüklenmesi için bu dosyayı blocks/index.ts dosyasına aktarın.

JavaScript tanımı

javascriptDefinitionGenerator, özel alanınızı içeren bir blok için JavaScript tanımına dahil edilecek kodu oluşturur. Genellikle bu, blok kodu oluşturma aracının .appendField(new YourFieldConstructor(arg1, arg2), 'userSpecifiedName') gibi bir kod satırı döndürmesi gerektiği anlamına gelir. Bu kod satırı noktalı virgül içermez çünkü birden fazla alan içeren bir giriş birlikte zincirlenmiş birden fazla appendField çağrısına sahip olur. Yapıcıdaki bağımsız değişkenler, kullanıcının alan bloğunda ayarladığı değerlerden alınır. FieldAngle için bu blok kodu oluşturucunun bir örneğini aşağıda bulabilirsiniz:

javascriptDefinitionGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: JavascriptDefinitionGenerator,
): string {
  const name = generator.quote_(block.getFieldValue('FIELDNAME'));
  const angle = block.getFieldValue('ANGLE');
  return `.appendField(new FieldAngle(${angle}), ${name})`;
};

Kullanıcının Blok Fabrikası araç kutusunun "Alanlar" kategorisinden sürüklediği açı bloğunda iki alan bulunur:

FIELDNAME: Kullanıcı, özel bloğundaki alanın adını ayarlayabilir
ANGLE: kullanıcı varsayılan açı değerini ayarlayabilir

Bu blok kodu oluşturma aracında, varsayılan açı değerini alıp FieldAngle oluşturucuya tek bağımsız değişken olarak iletiriz. Alan adı her zaman appendField işlevine ikinci bağımsız değişken olarak iletilir.

JSON tanımı

jsonDefinitionGenerator benzerdir, ancak bu, JSON blok tanımının alanınıza karşılık gelen bölümünü oluşturur. Genellikle bu kod aşağıdakileri içeren bir JSON nesnesidir:

type: Blockly alan kaydındaki alanınızın adına karşılık gelir.
name: Kullanıcı, özel bloğundaki alanın adını ayarlayabilir
alanınızın json başlatma yönteminin gerektirdiği diğer özel özellikleri de değiştirebilirsiniz.

FieldAngle alanından bir örnek daha:

jsonDefinitionGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: JsonDefinitionGenerator,
): string {
  const code = {
    type: 'field_angle',
    name: block.getFieldValue('FIELDNAME'),
    angle: block.getFieldValue('ANGLE'),
  };
  return JSON.stringify(code);
};

Kod başlıkları

Kod Üstbilgisi Oluşturucu, Blok Fabrikası'nda gösterilen Kod Üstbilgileri çıkışını oluşturur. Bu çıkış, kullanıcının kodu nasıl yüklemek istediğine bağlı olarak esmodule içe aktarma işlemleri ve komut dosyası etiketleri arasında değiştirilebilir. Böylece, aslında her biri için bir tane olmak üzere iki farklı oluşturucu örneği vardır. Her biri için bir blok kodu oluşturma aracı eklemeniz gerekir. FieldAngle için bir örnek:

importHeaderGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: CodeHeaderGenerator,
): string {
  generator.addHeaderLine(
    `import {registerFieldAngle, FieldAngle} from '@blockly/field-angle';`,
  );
  generator.addHeaderLine(`registerFieldAngle();`);
  return '';
};

scriptHeaderGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: CodeHeaderGenerator,
): string {
  generator.addHeaderLine(
    `<script src="https://unpkg.com/@blockly/field-angle"></script>`,
  );
  generator.addHeaderLine(`registerFieldAngle();`);
  return '';
};

Bu oluşturucular, alanınız kodda kullanılmadan önce çağrılması gereken bir kod satırı belirtmenizi sağlayan addHeaderLine adlı bir yönteme sahiptir. Genellikle bu, alanı içe aktarma veya bir komut dosyası etiketi aracılığıyla yükleme gibi işleri ve belki alanı Blockly'nin alan kaydına kaydedecek bir işlevin çağrılmasını içerir.

Bu iki blok kodu oluşturucu için tüm kodun, addHeaderLine öğesine yapılan çağrılar aracılığıyla eklenmesi gerekir. Bu işlev, özel alan blokunuz bir özel blokta birden çok kez kullanılsa bile her başlık satırının yalnızca bir kez gösterilmesini sağlar. Blok kodu oluşturma aracı boş dize döndürmelidir.

Jeneratör sapı

Son olarak, alan için jeneratör sapını oluşturan jeneratörümüz var. Bu blok kodu oluşturma aracında, kullanıcının kod üreten kodu yazmasına yardımcı olan kod yazacaksınız. Kafanız mı karıştı? Göründüğünden daha kolay.

Özel bir blok için oluşturucu sapı, bloktaki her alanı temsil eden önceden hazırlanmış bir değişken içerir. Kullanıcının tüm bu değişkenleri özel blokunun döndüreceği son kod dizesinde birleştirmek için tamamlaması gereken bir TODO vardır. Bu, genellikle blok kodu oluşturma aracınızın yapması gereken tek şeyin, bu özel değişkeni oluşturan satırı döndürmek olduğu anlamına gelir. Kullanıcının tuvaline güneş ışınları ekleyecek özel bir blok yaptığını varsayalım. Bloğuya bir açı alanı ekler ve bloka "SUN_DIRECTION" adını verir. Bu blok için oluşturucu sapı const angle_sun_direction = block.getFieldValue("SUN_DIRECTION"); satırını içerir. Bu, açı alanı için blok kodu oluşturucumuzun döndürmesi gereken kod satırıdır:

generatorStubGenerator.forBlock['field_angle'] = function (
  block: Blockly.Block,
  generator: GeneratorStubGenerator,
): string {
  const name = block.getFieldValue('FIELDNAME');
  const fieldVar = generator.createVariableName('angle', name);
  return `const ${fieldVar} = block.getFieldValue(${generator.quote_(
    name,
  )});\n`;
};

Değişken için standartlaştırılmış bir ad elde etmek üzere generator.createVariableName yöntemini çağırabilir ve alanınızın türünü (angle, number vb.) ve kullanıcının alanına adlandırdığı bilgiyi iletebilirsiniz.

Test et

Tüm bu parçaları yazdıktan sonra blockly-samples/examples/developer-tools dizininde npm start komutunu çalıştırarak Blok Fabrikası'nı başlatabilmeniz gerekir. Blokunuzu alan kategorisinden sürükleyebilir, bloktaki bir girişe ekleyebilir ve çıkıştaki değişimi izleyebilirsiniz. Blok önizlemesinin düzgün göründüğünden ve çıkış bölümlerinin her biri için kodun doğru olduğundan emin olun.