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 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ợ cho Blockly hoặc tích hợp Blockly vào một ứng dụng độc lập.
Chế độ hiển thị
Chúng ta sử dụng các đố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.
Một số thuộc tính có thể được chú thích bằng @internal trong các 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 trên 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 nội dung được đánh dấu là public đều thuộc API công khai của chúng tôi. Bất kỳ thuộc tính nào trong mô-đun không có đối tượng sửa đổi chế độ hiển thị đều được coi là thuộc tính công khai.
Chúng tôi cố gắng không thay đổi API công khai thường xuyên hoặc khi không có lý do chính đáng và cảnh báo. Trường hợp ngoại lệ: chúng tôi có thể công khai một 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 để phản hồi ý kiến phản hồi ban đầu. Sau đó, bạn có thể coi một hàm hoặc thuộc tính công khai là ổn định.
Bạn có thể gọi các hàm công khai từ bất kỳ đâu và 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 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ụ: 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 lớp đó.
Trong mỗi trường hợp, bạn phải đảm bảo rằng bạn hiểu cách 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 thuộc tính này bằng mã trong cùng một 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 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ần cảnh báo, vì chúng 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ú thích chế độ hiển thị vì các hàm này không được xuất từ mô-đun. 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 chúng. Bạn nên xem các thuộc tính 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 dùng trong thư viện cốt lõi, chứ không phải bên ngoài. Các lớp này được chỉ định bằng chú thích @internal của TsDoc.
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 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ừ bất kỳ đâu trong lõi và ghi đè trong các lớp con trong lõi miễn là chữ ký không thay đổi. Bạn không được truy cập vào các lớp này từ bên ngoài thư viện cốt lõi.
không dùng nữa
Không được sử dụng bất kỳ nội dung nào được đánh dấu là @deprecated. Hầu hết các trường hợp ngừng sử dụng đều bao gồm hướng dẫn về mã ưu tiên, trong cảnh báo của bảng điều khiển hoặc TSDoc.
Nếu có thể, các hàm không dùng nữa sẽ ghi lại một cảnh báo bao gồm ngày xoá dự kiến và đề xuất về hàm thay thế cần gọi.
Câu hỏi thường gặp
Sau đây là một số câu hỏi thường gặp mà nhóm Blockly gặp phải.
Nếu hàm tôi muốn sử dụng không phải là hàm công khai thì sao?
Gửi yêu cầu về tính năng trên Blockly cốt lõi. Hãy thêm nội dung mô tả trường hợp sử dụng của bạn và tuyên bố về những nội dung 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 về việc có nên công khai thông tin đó hay không, hoặc có cách nào khác để bạn có được thông tin tương tự hay không.
Nếu chúng tôi quyết định công khai, bạn hoặc nhóm Blockly sẽ thực hiện thay đổi thích hợp và thay đổi đó sẽ có hiệu lực trong bản phát hành Blockly tiếp theo.
Nếu bạn chọn sử dụng thành phần không công khai trong trình bổ trợ, hãy cân nhắc đánh dấu trình bổ trợ là phiên bản beta và đưa thông tin đó vào README.
Còn việc vá mã nguồn thì sao?
Đọc về cách vá mã.
Việc vá lỗi Monkey 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 do sử dụng các phần không công khai của API Blockly. Việc vá trong trình bổ trợ đặ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ỳ trình bổ trợ nào khác cũng vá cùng một mã. Vì lý do này, chúng tôi khuyên bạn không nên sử dụng tính năng vá lỗi trong ứng dụng và trình bổ trợ của bên thứ ba, đồng thời sẽ không chấp nhận tính năng này trong 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: không, đó là monkeypatching.
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: không, đó là monkeypatching.
Tôi có thể ghi đè các hàm nội bộ hoặc riêng tư không?
Không, đó là monkeypatching.
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 setter?
Nếu chúng tôi phát hành phương thức getter hoặ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 phải là thuộc tính công khai, hãy nhớ sử dụng phương thức getter và setter.
Nếu một thuộc tính không có chú thích thì sao?
Theo mặc định, thuộc tính này là công khai, nhưng vui lòng gửi thư cho chúng tôi trong trường hợp chúng tôi muốn đặt một cặp phương thức getter/setter cho bạn.
Nếu một hàm không có chú thích thì sao?
Chế độ này là công khai theo mặc định.
Nếu tôi vẫn không chắc 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 trong vòng vài ngày.