Xuất bản thư viện khối

Các trình bổ trợ cung cấp thư viện định nghĩa khối là một cách hiệu quả để chia sẻ các khối có thể tái sử dụng với cộng đồng Blockly. Để đặt thư viện khối của bạn làm 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 của bạn và tạo điều kiện có thể nếu người dùng chỉ cài đặt một số khối hoặc đoạ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 tất cả các khối do trình bổ trợ cung cấp cùng một lúc.
  • Giúp bạn có thể chọn các phần cụ thể: Bạn nên xuất tất cả các phần định nghĩa khối một cách riêng biệt, để có thể người dùng chỉ nhập các phần họ cần để tạo các phần khối tuỳ chỉnh tương tự.
• Tránh sử dụng 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 dưới dạng một tác dụng phụ của việc 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 những phần họ cần mà không phải lo lắng rằng những phần không thuộc về mình .

• 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 được đề xuất – Tạo trực tiếp một 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.
  • Blockly sẽ sớm cung cấp các công cụ cho phép bạn đăng ký mặt hàng đã được đăng ký mà không có 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 nêu rõ mọi điều kiện tiên quyết hoặc phần phụ thuộc bắt buộc theo định nghĩa trình bổ trợ hoặc khối của bạn.

• Cân nhắc việc cung cấp hàm 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 tự viết trình tạo chức năng, điều này có thể khiến mỗi người dùng thực hiện thừa một lượng công việc.
  • JavaScript là ngôn ngữ được sử dụng phổ biến nhất trong Blockly, vì vậy, nếu bạn chỉ chọn một ngôn ngữ để cung cấp, bạn nên chọn JavaScript, trừ khi 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 chức năng cài đặt cho khối của mình, bạn có thể chấp nhận một tham số generators không bắt buộc. Nếu người dùng truyền một thực thể của trình tạo mà bạn hỗ trợ, bạn có thể tự động cài đặt trình tạo mã khối và thực hiện công việc liên quan như thêm từ dành riêng:

      // Your plugin's install function
      export const installMyCustomBlock(generators = {}) {
        Blockly.common.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 muốn xem các thư viện khối của bạn và cung cấp ý kiến phản hồi về các tính năng đó.

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