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 trong các sản phẩm cốt lõi của Blockly. Những nguyên tắc này áp dụng khi tạo trình bổ trợ cho Blockly hoặc tích hợp Blockly vào một ứng dụng độc lập.

Phân loại 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 một trình kết xuất mới)
  • Mixin (ví dụ: thêm tiện ích khối hoặc trình biến đổi)
  • Định nghĩa khối (ví dụ: định nghĩa khối quy trình)

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

Chèn lớp con

Chúng tôi hỗ trợ thay thế một số lớp nhất định thông qua phương thức Blockly.inject. Các các lớp con phải mở rộng lớp cơ sở hoặc triển khai lớp tương ứng .

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

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

Hoặc bạn có thể đăng ký lớp học của mình bằng Blockly.registry và sử dụng tên đăng ký để chèn lớp. Điều này rất hữu ích nếu bạn lưu trữ nội dung tiêm dưới dạng JSON thuần túy.

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 của tài liệu.

Chế độ hiển thị

Chúng tôi 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 chính là public, private hoặc protected. Bạn có thể chú thích một số thuộc tính bằng @internal trong Nhận xét trên TsDoc.

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

công khai

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

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

Các hàm công khai có thể được gọi từ bất cứ đâu và bị ghi đè trong các lớp con dưới dạng miễn là chữ ký không thay đổi.

được bảo vệ

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

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ý kiểu.

Ví dụ: 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 các thuộc tính được bảo vệ.

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

riêng tư

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

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

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

Một số hàm trong Blockly không có chú thích chế độ hiển thị vì chúng không được xuất từ mô-đun của họ. Về cơ bản, các hàm này là biến cục bộ và không thể sử dụng bên ngoài mô-đun xác định của các thuật toán đó. Bạn cần cân nhắc đến những chính sách này tương đương với thuộc tính riêng tư.

nội bộ

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

Các thuộc tính nội bộ có thể thay đổi mà không cần cảnh báo, vì chúng không được coi là một phần trong 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ừ bất cứ đâu trong lõi và bị ghi đè trong các lớp con trong lõi, miễn là chữ ký không thay đổi. Không được truy cập từ bên ngoài thư viện chính.

không dùng nữa

Không được sử dụng bất cứ mục nào được đánh dấu là @deprecated. Hầu hết các trường hợp ngừng sử dụng bao gồm hướng dẫn về mã ưu tiên, trong cảnh báo trên bảng điều khiển hoặc TSDoc.

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

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 yêu cầu về tính năng về Blockly. Bao gồm nội dung mô tả trường hợp sử dụng của bạn và lời tuyên bố về những gì mà 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ó nên công khai thông tin hay không, hoặc liệu có cách nào khác giúp bạn có được thông tin tương tự không.

Nếu chúng tôi quyết định đặt thông tin này ở chế độ công khai, bạn hoặc nhóm Blockly sẽ đặt thay đổi phù hợp và 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 viên không công khai trong một trình bổ trợ, hãy cân nhắc việc đánh dấu trình bổ trợ dưới dạng bản beta và đưa thông tin vào README của bạn.

Thế còn Kẻ vá lỗi thì sao?

Đọc thêm về các bản vá của khỉ.

Monkeypatch không an toàn vì các bản vá có thể ngừng hoạt động mà không cần thông báo sang việc sử dụng các phần không công khai của Blockly API. Việc vá lỗi trong trình bổ trợ là đặc biệt nguy hiểm vì mã của bạn có thể tương tác kém với bất kỳ một trình bổ trợ khắc phục cùng một mã. Vì lý do này, chúng tôi mạnh mẽ không nên sử dụng bản vá lỗi trong các ứng dụng và trình bổ trợ của bên thứ ba, và sẽ không chấp nhận mã 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, đó là lỗi của bản vá.

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

Khi phân lớp con: có. Nếu không, đó là lỗi của bản vá.

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

Không, đó là việc vấp ngã.

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 xuất bản 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ì trực tiếp truy cập vào tài sản. Nếu cơ sở lưu trú không công khai, hãy chắc chắn sử dụng các phương thức getter và phương thức setter.

Nếu cơ sở lưu trú không có chú thích thì sao?

Theo mặc định, hồ sơ ở 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 phương thức getter/setter phù hợp với bạn.

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

Theo mặc định, video sẽ ở chế độ công khai.

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

Đặ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).