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

Công cụ cho nhà phát triển của 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! Ngoài các trường đi kèm với Blockly chính, API này còn hỗ trợ các trường được xuất bản dưới dạng trình bổ trợ. 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 vào npm thì mới có thể thêm tính năng hỗ trợ cho trường đó. Bạn cũng cần cam kết cập nhật trường của mình để bắt kịp các thay đổi trong Blockly, nếu không, chúng tôi có thể cần phải xoá trường đó khỏi Block Factory trong tương lai.

Phát triển nhà máy khối

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

Để gửi thay đổi cho Công cụ dành cho nhà phát triển trong mẫu theo khối, bạn cần làm theo các bước thông thường để phát triển trong các mẫu theo khối. Tuy nhiên, không giống như 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 khối mẫu.

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 dưới dạng phần phụ thuộc npm của công cụ dành cho nhà phát triển. Sau đó, hãy đăng ký hoặc thực hiện mọi công việc thiết lập khác cần thiết trong developer-tools/src/blocks/index.ts.

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

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

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

Bạn cần phải thiết kế khối cho trường của mình; nếu muốn sử dụng meta, bạn thậm chí có thể thiết kế khối này bằng cách sử dụng Block Factory! Khối sẽ 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ư các 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 khối này 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 khối này. Định nghĩa hộp công cụ nằm trong developer-tools/src/toolbox.ts. Bạn nên thêm khối của mình 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 với 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 và các khối mẹ sẽ lắp ráp mã cho các khối con thành kết quả chính xác. Để hỗ trợ thêm một trường tuỳ chỉnh, bạn cần thêm các hàm 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 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 trong tệp blocks/index.ts để các hàm 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 đối với một khối có chứa trường tuỳ chỉnh. Thông thường, điều này có nghĩa là trình tạo mã khối sẽ trả về một dòng mã có dạng .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. Dưới đâ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ó 2 trường trên đó:

• FIELDNAME: người dùng có thể đặt tên 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 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 làm đối số thứ hai cho appendField.

Lưu ý: Đối với bất kỳ vị trí nào bạn cần dấu ngoặc kép xung quanh giá trị trường, chẳng hạn như khi chuyển tên của trường vào appendField, bạn nên sử dụng generator.quote_ thay vì gói trong dấu ngoặc kép theo cách thủ công.

Định nghĩa JSON

jsonDefinitionGenerator cũng tương tự, nhưng sẽ xuất ra một phần của đị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 của Blockly
• name: người dùng có thể đặt tên trường trên khối tuỳ chỉnh của họ
• bất kỳ thuộc tính tuỳ chỉnh nào khác mà phương thức khởi chạy json của trường cần thiết.

Sau đây là một ví dụ từ 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ề chuỗi, vì vậy, hãy tạo chuỗi cho đối tượng trước khi trả về.

Tiêu đề mã

Trình tạo tiêu đề mã tạo đầu ra Tiêu đề mã như trong Block Factory. Bạn có thể chuyển đổi đầu ra này giữa tính năng 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 thực thể trình tạo khác nhau: một thực thể 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 khối. Dưới đây là 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 sử dụng trong mã. Thông thường, các thao tác này bao gồm các tác vụ 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.

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

Đố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ỉ hiển thị một lần, ngay cả khi khối trường tuỳ chỉnh của bạn được sử 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.

Sơ đồ máy phát

Cuối cùng, chúng ta có một trình tạo để tạo mã giả lập cho trường này. Trong trình tạo mã khối này, bạn sẽ viết mã tạo ra mã giúp người dùng viết mã tạo ra mã. Bạn còn bối rối? Việc này nghe hay đấy!

Mã giả lập 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 đó, sẽ có một TODO mà người dùng phải hoàn tất để tập hợp tất cả các biến này vào 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 vào canvas của họ. Các khối này thêm một trường góc vào khối và đặt tên cho khối đó là "SUN_DIRECTION". Mã giả lập 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`;
};

Để có tên chuẩn cho biến, bạn có thể gọi generator.createVariableName và chuyể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 tên cho trường của họ.

Kiểm tra

Sau khi đã viết tất cả các phần này, bạn có thể khởi động 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 dữ liệu đầu vào trên khối và theo dõi sự thay đổi đầu ra. Kiểm tra để đảm bảo bản xem trước của khối hiển thị chính xác và mã cho từng phần đầu ra là chính xác.