Thêm trường trình bổ trợ vào Block Factory

Công cụ dành cho nhà phát triển Blockly cho phép bạn tạo các khối tuỳ chỉnh bằng cách sử dụng các khối! Blockly có hỗ trợ các trường được xuất bản dưới dạng trình bổ trợ, ngoài các trường đi kèm với Blockly cốt lõi. Nếu đã tạo một trường tuỳ chỉnh, bạn có thể thêm tính năng hỗ trợ cho trường đó vào Block Factory bằng cách làm theo hướng dẫn này. Bạn phải xuất bản trường tuỳ chỉnh trên npm trước khi có thể thêm chế độ hỗ trợ cho trường đó. Bạn cũng cần cam kết cập nhật trường của mình để theo kịp những thay đổi trong Blockly. Nếu không, có thể chúng tôi sẽ phải xoá trường đó khỏi Block Factory trong tương lai.

Phát triển trên Block Factory

Mã nguồn cho Block Factory nằm trong kho lưu trữ blockly-samples trong thư mục examples/developer-tools.

Để gửi nội dung thay đổi cho Công cụ dành cho nhà phát triển trong blockly-samples, bạn cần làm theo các bước thông thường để phát triển trong blockly-samples. Tuy nhiên, không giống như khi làm việc với các trình bổ trợ, bạn sẽ cần chạy npm install trực tiếp từ thư mục examples/developer-tools, thay vì ở cấp gốc của blockly-samples.

Cài đặt trình bổ trợ

Để Block Factory hiển thị trường tuỳ chỉnh của bạn trong bản xem trước, bạn cần cài đặt trường tuỳ chỉnh. Thêm trường của bạn làm phần phụ thuộc npm của developer-tools. Sau đó, hãy đăng ký hoặc thực hiện mọi công việc thiết lập cần thiết khác trong developer-tools/src/blocks/index.ts.

Tạo một khối cho trường

Vì Block Factory dùng các khối để tạo khối tuỳ chỉnh, nên bạn sẽ cần một khối đại diện cho trường tuỳ chỉnh.

Tạo định nghĩa khối

Bạn cần thiết kế khối cho trường của mình; nếu muốn lấy meta, bạn thậm chí có thể thiết kế khối đó bằng Block Factory! Khối này phải cho phép người dùng định cấu hình chế độ thiết lập mà trường của bạn yêu cầu, chẳng hạn như giá trị mặc định và tên. Thêm định nghĩa khối này vào developer-tools/src/blocks/fields.ts và nhập định nghĩa đó vào developer-tools/src/blocks/index.ts.

Thêm khối vào hộp công cụ

Tiếp theo, bạn cần thêm khối này vào định nghĩa hộp công cụ để người dùng có thể truy cập vào khối này. Định nghĩa về hộp công cụ nằm trong developer-tools/src/toolbox.ts. Khối của bạn sẽ được thêm vào danh mục "Trường".

Trình tạo mã

Block Factory hoạt động bằng cách sử dụng hệ thống Trình tạo mã mà bạn đã quen thuộc trong Blockly. Mỗi khối có một trình tạo mã khối cho từng loại đầu ra do Block Factory tạo ra, đồng thời các khối mẹ sẽ lắp ráp mã cho các khối con thành đầu ra chính xác. Để thêm hỗ trợ cho một trường tuỳ chỉnh, bạn cần thêm các hàm trình tạo mã khối cho từng lớp Trình tạo mã.

Tạo một tệp cho khối trường của bạn trong thư mục output-generators/fields. Bạn sẽ thêm trình tạo mã khối cho từng Trình tạo sau đây vào tệp này. Nhập tệp này vào tệp blocks/index.ts để các hàm trình tạo mã khối được tải vào ứng dụng.

Định nghĩa JavaScript

javascriptDefinitionGenerator tạo mã sẽ được đưa vào định nghĩa JavaScript cho một khối có chứa trường tuỳ chỉnh của bạn. Thông thường, điều này có nghĩa là trình tạo khối mã sẽ trả về một dòng mã có dạng như .appendField(new YourFieldConstructor(arg1, arg2), 'userSpecifiedName'). Xin lưu ý rằng dòng mã này không bao gồm dấu chấm phẩy, vì một đầu vào chứa nhiều trường sẽ có một số lệnh gọi đến appendField được xâu chuỗi với nhau. Các đối số trong hàm khởi tạo được lấy từ các giá trị mà người dùng đặt trên khối trường. Sau đây là ví dụ về trình tạo mã khối này cho FieldAngle:

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})`;
};

Khối góc mà người dùng kéo từ danh mục "Trường" của hộp công cụ Block Factory có hai trường trên đó:

• FIELDNAME: người dùng có thể đặt tên cho trường trên khối tuỳ chỉnh của họ
• ANGLE: người dùng có thể đặt giá trị góc mặc định

Trong trình tạo mã khối này, chúng ta sẽ nhận được giá trị góc mặc định và truyền giá trị đó làm đối số duy nhất cho hàm khởi tạo FieldAngle. Tên trường luôn được truyền dưới dạng đối số thứ hai đến appendField.

Lưu ý: Đối với bất kỳ vị trí nào mà bạn cần đặt dấu ngoặc kép xung quanh giá trị trường, chẳng hạn như khi truyền tên của trường đến appendField, bạn nên sử dụng generator.quote_ thay vì tự động bao bọc trong dấu ngoặc kép.

Định nghĩa JSON

jsonDefinitionGenerator cũng tương tự, nhưng lệnh này sẽ xuất ra phần định nghĩa khối JSON tương ứng với trường của bạn. Thông thường, mã này là một đối tượng JSON bao gồm:

• type: tương ứng với tên trường của bạn trong sổ đăng ký trường Blockly
• name: người dùng có thể đặt tên cho trường trên khối tuỳ chỉnh của họ
• mọi thuộc tính tuỳ chỉnh khác mà phương thức khởi tạo json của trường cần.

Sau đây là một ví dụ khác về FieldAngle:

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);
};

Lưu ý: Trình tạo mã khối luôn trả về các chuỗi, vì vậy, hãy chuyển đổi đối tượng thành chuỗi trước khi trả về.

Tiêu đề mã

Trình tạo tiêu đề mã sẽ tạo ra đầu ra Tiêu đề mã xuất hiện trong BlockFactory. Đầu ra này có thể được chuyển đổi giữa các câu lệnh nhập esmodule và thẻ tập lệnh, tuỳ thuộc vào cách người dùng muốn tải mã. Vì vậy, thực tế có 2 phiên bản trình tạo khác nhau: một cho mỗi trường hợp. Bạn cần thêm một trình tạo mã khối cho từng mã. Sau đây là một ví dụ về FieldAngle:

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 '';
};

Các trình tạo này có một phương thức tên là addHeaderLine cho phép bạn chỉ định một dòng mã cần được gọi trước khi trường của bạn được dùng trong mã. Thông thường, việc này bao gồm các thao tác như nhập trường hoặc tải trường thông qua thẻ tập lệnh và có thể gọi một hàm sẽ đăng ký trường với sổ đăng ký trường của Blockly.

Lưu ý: Nếu gói của bạn được xuất bản trên npm, thì gói đó sẽ tự động có sẵn trên unpkg. Đây là một nơi thuận tiện để các thẻ tập lệnh có thể tải từ đó.

Đối với 2 trình tạo mã khối này, bạn phải thêm tất cả mã thông qua các lệnh gọi đến addHeaderLine. Hàm này sẽ đảm bảo mỗi dòng tiêu đề chỉ xuất hiện một lần, ngay cả khi khối trường tuỳ chỉnh của bạn được dùng nhiều lần trong một khối tuỳ chỉnh. Trình tạo mã khối sẽ trả về chuỗi trống.

Stub trình tạo

Cuối cùng, chúng ta có trình tạo tạo ra phần giữ chỗ trình tạo cho trường. Trong trình tạo mã dạng khối này, bạn sẽ viết mã tạo mã giúp người dùng viết mã tạo mã. Bạn đã thấy bối rối chưa? Dễ hơn bạn tưởng!

Phần giữ chỗ trình tạo cho một khối tuỳ chỉnh bao gồm một biến được tạo sẵn, đại diện cho mọi trường trên khối. Sau đó, người dùng phải hoàn tất TODO để tập hợp tất cả các biến này thành chuỗi mã cuối cùng mà khối tuỳ chỉnh của họ sẽ trả về. Điều đó có nghĩa là thông thường, tất cả những gì trình tạo mã khối của bạn cần làm là trả về dòng tạo biến tuỳ chỉnh này. Giả sử người dùng đang tạo một khối tuỳ chỉnh sẽ thêm các tia nắng mặt trời vào canvas của họ. Chúng sẽ thêm một trường góc vào khối và đặt tên là "SUN_DIRECTION". Phần giữ chỗ của trình tạo cho khối này sẽ bao gồm dòng const angle_sun_direction = block.getFieldValue("SUN_DIRECTION");. Đó là dòng mã mà trình tạo mã khối cho trường góc cần trả về:

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`;
};

Để lấy tên chuẩn hoá cho biến, bạn có thể gọi generator.createVariableName và truyền vào loại trường của bạn (chẳng hạn như angle, number, v.v.) cùng với tên mà người dùng đặt cho trường của họ.

Kiểm thử

Sau khi viết tất cả các phần này, bạn có thể bắt đầu Block Factory bằng cách chạy npm start trong thư mục blockly-samples/examples/developer-tools. Bạn có thể kéo khối từ danh mục trường, thêm khối đó vào một đầu vào trên khối và xem thay đổi đầu ra. Kiểm tra để đảm bảo bản xem trước của khối trông phù hợp và mã cho từng phần đầu ra đều chính xác.