Thư viện khối xuất bản

Các trình bổ trợ cung cấp thư viện định nghĩa khối là một cách tuyệt vời để chia sẻ các khối có thể sử dụng lại với cộng đồng Blockly. Để thư viện khối của bạn trở nên linh hoạt và hữu ích nhất có thể, chúng tôi đã phát triển các nguyên tắc này.

Nguyên tắc

  • Giúp người dùng dễ dàng cài đặt tất cả các khối và cho phép người dùng chỉ cài đặt một số khối hoặc phần khối nhất định mà họ chọn.
    • Giúp dễ dàng cài đặt mọi thứ: Bạn có thể thực hiện việc này bằng cách cung cấp một hàm cài đặt mọi phần mà một định nghĩa khối yêu cầu (chẳng hạn như biến đổi, tiện ích, kết hợp, trường, v.v.). Bạn cũng có thể cung cấp một hàm sẽ cài đặt đồng thời tất cả các khối mà trình bổ trợ cung cấp.
    • Giúp có thể chọn các phần cụ thể: Bạn nên xuất riêng biệt tất cả các phần của định nghĩa khối để người dùng có thể chỉ nhập các phần họ cần để tạo khối tuỳ chỉnh tương tự của riêng họ.
  • Tránh sử dụng các hiệu ứng phụ trong trình bổ trợ của bạn.
    • Bạn không nên cài đặt các khối, trường, tiện ích và các thành phần khác như là một tác dụng phụ của việc tải trình bổ trợ. Người dùng nên duy trì quyền kiểm soát những nội dung nào được cài đặt và thời điểm cài đặt. Điều này cho phép người dùng nhập các mảnh họ cần mà không phải lo rằng các mảnh họ không sẽ được cài đặt.

  • Hãy sử dụng sổ đăng ký trường JSON thay vì tạo thực thể của các trường mới một cách trực tiếp.

    • Không nên dùng – Tạo bản sao của trường mới trực tiếp:

        const myCustomBlock = {
    init: function() {
      this.appendDummyInput()
          .appendField(new Blockly.FieldNumber(123), 'NAME');
    }
  }

    • Đề xuất – Sổ đăng ký trường JSON:

        export const myCustomBlock = {
    init: function() {
      this.appendDummyInput()
          .appendField(Blockly.fieldRegistry.fromJson({
              name: 'field_number',
              value: 123,
            }), 'NAME');
    }
  }

    • Việc sử dụng sổ đăng ký trường giúp người dùng dễ dàng thay thế phương thức triển khai trường được dùng trong khối của bạn mà không cần thay đổi định nghĩa khối.

  • Không giả định về những gì người dùng đã cài đặt.

    • Nếu trình bổ trợ của bạn yêu cầu một trường tuỳ chỉnh hoặc một trình bổ trợ khác, hãy tự đăng ký các trường đó trong hàm install mà bạn cung cấp.
    • Sắp tới, Blockly sẽ cung cấp các công cụ giúp bạn đăng ký các mục đã đăng ký mà không gặp lỗi. Cho đến lúc đó, bạn nên kiểm tra nội dung nào đã được đăng ký trước khi tự đăng ký tiện ích, trình biến đổi, kết hợp hoặc trường.
    • Hãy rõ ràng về mọi điều kiện tiên quyết hoặc phần phụ thuộc mà trình bổ trợ của bạn yêu cầu hoặc định nghĩa khối.

  • Hãy cân nhắc việc cung cấp các hàm tạo cho mỗi khối mà bạn cung cấp.

    • Việc cung cấp các hàm trình tạo hoạt động ngay từ đầu giúp người dùng sử dụng các khối của bạn dễ dàng hơn mà không cần phải hiểu về cấu trúc và thiết kế của các khối đó. Nếu họ phải viết hàm trình tạo riêng, điều này có thể dẫn đến việc từng người dùng thực hiện thừa công việc.
    • JavaScript là ngôn ngữ được dùng phổ biến nhất trong Blockly. Vì vậy, nếu chỉ chọn một ngôn ngữ để cung cấp, bạn nên sử dụng JavaScript, trừ phi các khối của bạn được tạo cho một ngôn ngữ cụ thể, chẳng hạn như triển khai thư viện Python.
    • Hãy cân nhắc việc đăng vấn đề "muốn được trợ giúp" cho các ngôn ngữ mà bạn không thể triển khai các hàm tạo và chấp nhận yêu cầu kéo (pull request) cho các ngôn ngữ này nếu người dùng đóng góp.

    • Nếu cung cấp hàm cài đặt cho khối của mình, bạn có thể chấp nhận tham số generators (không bắt buộc). Nếu người dùng truyền một thực thể trình tạo mà bạn hỗ trợ, bạn có thể tự động cài đặt hàm tạo mã khối và thực hiện các thao tác liên quan như thêm các từ dành riêng:

        // Your plugin's install function
  export const installMyCustomBlock(generators = {}) {
    Blockly.defineBlocks({my_custom_block: myCustomBlock});
    if (generators.javascript) {
      generators.javascript.forBlock['my_custom_block'] = myCustomGeneratorFunction;
      generators.javascript.addReservedWords('specialReservedWord');
    }
  }

  // How a user may install your block
  import {javascriptGenerator} from 'blockly/javascript';
  import {installMyCustomBlock} from 'blockly-cool-blocks-plugin';
  // installs the block definition and the javascript block-code generator
  installMyCustomBlock({javascript: javascriptGenerator});

Ý kiến phản hồi

Nếu bạn có thắc mắc về cách tuân thủ các nguyên tắc này trong trình bổ trợ của mình một cách hiệu quả nhất, hãy cho chúng tôi biết trong diễn đàn! Chúng tôi muốn xem thư viện khối của bạn và đưa ra ý kiến phản hồi về các thư viện đó.

Xin lưu ý rằng hiện tại, không phải mọi trình bổ trợ bên thứ nhất cung cấp định nghĩa về khối đều tuân theo các nguyên tắc này. Tuy nhiên, các trình bổ trợ mới sẽ và chúng tôi dự định di chuyển các trình bổ trợ hiện có.