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 hay để 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 sau.

Nguyên tắc

  • Giúp người dùng dễ dàng cài đặt tất cả các khối của bạn và giúp người dùng có thể chỉ cài đặt một số khối hoặc phần khối nhất định mà họ chọn.
    • 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 đơn yêu cầu (chẳng hạn như phương thức sửa đổi, tiện ích, thành phần 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 cùng lúc tất cả các khối do trình bổ trợ cung cấp.
    • Cho phép chọn các phần cụ thể: Bạn nên xuất riêng tất cả các phần của định nghĩa khối để người dùng chỉ có thể nhập các phần họ cần nhằm tạo khối tuỳ chỉnh tương tự của riêng mình.
  • Tránh sử dụng các hiệu ứng phụ trong trình bổ trợ.
    • 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 làm tác dụng phụ khi tải trình bổ trợ. Người dùng phải duy trì quyền kiểm soát đối với những nội dung đượ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 phần họ cần mà không lo lắng rằng các phần họ không cần sẽ được cài đặt.

  • Sử dụng sổ đăng ký trường JSON thay vì tạo thực thể cho các trường mới trực tiếp.

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

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

    • Nên dùng – 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ế việc triển khai trường được sử 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ụ cho phé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 những gì đã được đăng ký trước khi tự đăng ký một tiện ích, phương thức sửa đổi, mixin 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ợ hoặc định nghĩa khối của bạn yêu cầu.

  • Cân nhắc cung cấp hàm trình tạo cho từng 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 dễ dàng sử dụng các khối của bạn mà không cần phải hiểu cấu trúc và thiết kế của các khối đó. Nếu họ phải viết các hàm trình tạo của riêng mình, thì điều này có thể dẫn đến việc mỗi người dùng phải làm công việc thừa.
    • JavaScript là ngôn ngữ thường dùng 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 đăng các vấn đề "cần trợ giúp" cho các ngôn ngữ mà bạn không thể triển khai hàm trình tạo và chấp nhận các yêu cầu kéo 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ợ, thì bạn có thể tự động cài đặt hàm tạo mã khối và thực hiện các công việc liên quan, chẳng hạn 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});

Phản hồi

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

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