Sử dụng API Blockly

Giới thiệu

Trang này mô tả các phương pháp hay nhất để gọi hàm và truy cập vào các thuộc tính trong tính năng Blockly cốt lõi. Các nguyên tắc này áp dụng cho việc tạo trình bổ trợ choBlockly hoặc để tích hợp Blockly vào một ứng dụng độc lập.

Phân lớp con và mở rộng

Blockly có nhiều mô hình để thêm chức năng, bao gồm:

  • Lớp con (ví dụ: tạo trình kết xuất đồ hoạ mới)
  • Mixin (ví dụ: thêm tiện ích khối hoặc biến đổi)
  • Định nghĩa về quy tắc chặn (ví dụ: định nghĩa khối quy trình)

Trong tài liệu này, cả 3 trường hợp trên đều tương đương với việc phân lớp con.

Chèn lớp con

Chúng tôi hỗ trợ thay thế một số lớp thông qua phương thức Blockly.inject. Các lớp con này phải mở rộng lớp cơ sở hoặc triển khai giao diện tương ứng của chúng.

Bạn có thể truyền lớp con vào phương thức chèn.

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': CustomMetricsManagerClass
  }
}

Bạn cũng có thể đăng ký lớp bằng cách sử dụng Blockly.registry và sử dụng tên tổ chức đăng ký để chèn lớp đó. Việc này sẽ hữu ích nếu bạn lưu trữ các tuỳ chọn chèn dưới dạng JSON thuần.

Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);

Blockly.inject('blocklyDiv', {
  plugins: {
    'metricsManager': 'YOUR_NAME'
  }
}

Bạn có thể thay thế các lớp sau:

Tên đăng ký Giao diện/Lớp cơ sở
blockDragger Blockly.IBlockDragger
connectionChecker Blockly.IConnectionChecker
connectionPreviewer Blockly.IConnectionPreviewer
flyoutsVerticalToolbox Blockly.IFlyout
flyoutsHorizontalToolbox Blockly.IFlyout
metricsManager Blockly.IMetricsManager
renderer Blockly.blockRendering.Renderer
toolbox Blockly.IToolbox

Để biết thêm thông tin về cách sử dụng giao diện, hãy xem phần giao diện trong tài liệu.

Chế độ hiển thị

Chúng tôi sử dụng đối tượng sửa đổi quyền truy cập TypeScript để đánh dấu chế độ hiển thị trong thư viện cốt lõi là public, private hoặc protected. Bạn có thể chú thích một số thuộc tính bằng @internal trong phần nhận xét TsDoc.

Tất cả thuộc tính public và protected đều được ghi lại trong phần Tài liệu tham khảo của trang web Blockly. Bạn cũng có thể kiểm tra chế độ hiển thị bằng cách đọc mã.

công khai

Mọi mục được đánh dấu public đều là một phần của API công khai. Mọi thuộc tính trong một mô-đun không có đối tượng sửa đổi chế độ hiển thị đều được coi là công khai.

Chúng tôi cố gắng không thường xuyên thay đổi API công khai hoặc không có lý do chính đáng và không có cảnh báo. Ngoại lệ: chúng tôi có thể công khai API mới trong một bản phát hành và sửa đổi API đó trong bản phát hành tiếp theo để đáp ứng ý kiến phản hồi ban đầu. Sau đó, bạn có thể cân nhắc một hàm công khai hoặc thuộc tính ổn định.

Hàm công khai có thể được gọi từ mọi nơi và bị ghi đè trong các lớp con miễn là chữ ký không thay đổi.

được bảo vệ

Chỉ lớp xác định hoặc một lớp con mới có thể truy cập vào các hàm và thuộc tính được bảo vệ.

Các lớp con được phép ghi đè các hàm và thuộc tính được bảo vệ mà không cần thay đổi chữ ký loại.

Ví dụ: một trình kết xuất tuỳ chỉnh mở rộng lớp trình kết xuất cơ sở có thể truy cập vào các thuộc tính được bảo vệ của trình kết xuất đó.

Trong mỗi trường hợp, bạn nên đảm bảo bạn hiểu cách sử dụng hàm hoặc thuộc tính trong phần còn lại của mã.

private

Bạn chỉ có thể truy cập các định dạng này bằng mã trong cùng tệp với định nghĩa. Việc truy cập trực tiếp vào các thuộc tính này có thể dẫn đến hành vi không xác định.

Lớp con không được phép ghi đè các hàm và thuộc tính riêng tư.

Các thuộc tính riêng tư có thể thay đổi mà không có cảnh báo, vì các thuộc tính đó không được coi là một phần của API công khai của Blockly.

Một số hàm trong Blockly không có chú giải chế độ hiển thị vì các hàm này không được xuất từ mô-đun của chúng. Về cơ bản, các hàm này là biến cục bộ và không thể dùng bên ngoài mô-đun xác định của các hàm đó. Chúng phải được coi là tương đương với các thuộc tính riêng tư.

nội bộ

Các hàm và thuộc tính nội bộ chỉ để sử dụng trong thư viện lõi, chứ không phải bên ngoài. Các đối tượng này được chỉ định bằng chú giải @internal TsDoc.

Các thuộc tính nội bộ có thể thay đổi mà không có cảnh báo, vì các thuộc tính này không được coi là một phần của API công khai của Blockly.

Bạn có thể truy cập vào các thuộc tính nội bộ từ mọi nơi trong lõi và bị ghi đè trong các lớp con của lõi, miễn là chữ ký không thay đổi. Bạn không được truy cập vào các API này từ bên ngoài thư viện chính.

không dùng nữa

Bạn không nên sử dụng mọi giá trị được đánh dấu là @deprecated. Hầu hết việc ngừng sử dụng đều bao gồm chỉ dẫn trên mã ưu tiên, trong cảnh báo trên bảng điều khiển hoặc TSDoc.

Khi có thể, các hàm không dùng nữa sẽ ghi lại cảnh báo, bao gồm cả ngày dự kiến xoá và nội dung đề xuất gọi hàm thay thế.

Câu hỏi thường gặp

Nếu hàm tôi muốn sử dụng không công khai thì sao?

Gửi một yêu cầu về tính năng trên lõi Blockly. Bao gồm nội dung mô tả trường hợp sử dụng của bạn và tuyên bố những gì bạn muốn chúng tôi công khai.

Chúng tôi sẽ sử dụng tính năng này để yêu cầu thảo luận xem có công khai thông tin đó hay không hoặc có cách nào khác để bạn nhận được những thông tin đó hay không.

Nếu chúng tôi quyết định công khai nội dung này, thì bạn hoặc nhóm Blockly sẽ thực hiện thay đổi phù hợp và thay đổi sẽ được áp dụng trong bản phát hành Blockly tiếp theo.

Nếu bạn chọn sử dụng một thành phần không công khai trong một trình bổ trợ, hãy cân nhắc đánh dấu trình bổ trợ của mình là phiên bản beta và đưa thông tin đó vào README.

Còn việc đắp khỉ thì sao?

Đọc thêm về những điều vui vẻ về khỉ.

Monkeypatching không an toàn vì các bản vá có thể ngừng hoạt động mà không có thông báo do sử dụng các phần không công khai của API Blockly. Việc vá lỗi trong một trình bổ trợ đặc biệt nguy hiểm vì mã của bạn có thể tương tác không tốt với bất kỳ trình bổ trợ nào khác có khả năng vá lỗi cùng một mã. Vì lý do này, chúng tôi rất khuyên bạn không nên vá lỗi khỉ trong các ứng dụng và trình bổ trợ của bên thứ ba, đồng thời sẽ không chấp nhận lỗi này trong các trình bổ trợ của bên thứ nhất.

Tôi có thể ghi đè các hàm công khai không?

Khi phân lớp con: có. Nếu không, đó chỉ là yêu cầu sửa chữa.

Tôi có thể ghi đè hàm được bảo vệ không?

Khi phân lớp con: có. Nếu không, đó chỉ là yêu cầu sửa chữa.

Tôi có thể ghi đè hàm nội bộ hoặc hàm riêng tư không?

Không, đó là trò đùa vui.

Khi nào tôi có thể truy cập trực tiếp vào các tài sản? Khi nào tôi nên sử dụng phương thức getter hoặc phương thức setter?

Nếu chúng tôi phát hành một phương thức getter hoặc phương thức setter, vui lòng sử dụng phương thức đó thay vì truy cập trực tiếp vào thuộc tính đó. Nếu thuộc tính không công khai, chắc chắn sử dụng phương thức getter và phương thức setter.

Nếu một tài sản không có chú thích thì sao?

Theo mặc định, thông tin này ở chế độ công khai, nhưng vui lòng liên hệ với chúng tôi trong trường hợp chúng tôi muốn đặt một cặp getter/setter cho bạn.

Nếu một hàm không có chú giải thì sao?

Đây là chế độ công khai theo mặc định.

Nếu tôi vẫn không chắc chắn thì sao?

Hãy đặt câu hỏi trên diễn đàn và chúng tôi sẽ liên hệ lại với bạn, thường là trong vòng một ngày làm việc.