مقدمه
این صفحه بهترین روش‌ها را برای فراخوانی توابع و دسترسی به ویژگی‌ها در هسته Blockly توضیح می‌دهد. این اصول برای ایجاد پلاگین برای Blockly یا ادغام Blockly در یک برنامه مستقل اعمال می شود.
زیر طبقه بندی و گسترش
Blockly دارای پارادایم های متعددی برای افزودن عملکرد است، از جمله:
- زیر کلاس ها (مثلا ایجاد یک رندر جدید)
- ترکیبات (به عنوان مثال افزودن یک پسوند بلوک یا جهش دهنده)
- تعاریف بلوک (مثلاً تعاریف بلوک رویه)
برای اهداف این سند، هر سه مورد معادل طبقه بندی فرعی هستند.
زیر کلاس های تزریقی
ما از جایگزینی کلاس های خاص از طریق متد Blockly.inject پشتیبانی می کنیم. این زیر کلاس ها یا باید کلاس پایه را گسترش دهند یا رابط مربوطه خود را پیاده سازی کنند.
شما می توانید زیر کلاس خود را به روش تزریق منتقل کنید.
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': CustomMetricsManagerClass
}
}
یا می توانید کلاس خود را با استفاده از Blockly.registry ثبت کنید و از نام رجیستری برای تزریق کلاس استفاده کنید. اگر گزینه های تزریق خود را به صورت JSON خالص ذخیره کنید، این کار مفید است.
Blockly.registry.register(Blockly.registry.Type.METRICS_MANAGER, 'YOUR_NAME', SubClass);
Blockly.inject('blocklyDiv', {
plugins: {
'metricsManager': 'YOUR_NAME'
}
}
کلاس های زیر را می توان جایگزین کرد:
| نام ثبت نام | کلاس رابط/پایه |
|---|---|
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 |
برای کسب اطلاعات بیشتر در مورد استفاده از رابط ها، بخش واسط اسناد را بررسی کنید.
دید
ما از اصلاح کننده های دسترسی TypeScript برای علامت گذاری دید در کتابخانه هسته به عنوان public , private یا protected استفاده می کنیم . برخی از ویژگی ها ممکن است با @internal در نظرات TsDoc آنها حاشیه نویسی شود.
همه دارایی های public و protected در بخش مراجع وب سایت Blockly مستند شده اند. همچنین می توانید با خواندن کد قابلیت مشاهده را بررسی کنید.
عمومی
هر چیزی که public علامت گذاری شده باشد بخشی از API عمومی ما است. هر خاصیت در یک ماژول که اصلاح کننده دید ندارد عمومی در نظر گرفته می شود.
ما سعی می کنیم API عمومی خود را به طور مکرر یا بدون دلیل موجه و هشدار تغییر ندهیم. استثنا: ممکن است یک API جدید را در یک نسخه عمومی کنیم و در نسخه بعدی در پاسخ به بازخورد اولیه آن را اصلاح کنیم. پس از آن می توانید یک عملکرد عمومی یا دارایی پایدار را در نظر بگیرید.
توابع عمومی ممکن است از هر جایی فراخوانی شوند و تا زمانی که امضا تغییر نکند، در زیر کلاس‌ها لغو شوند.
محافظت شده است
توابع و خصوصیات محافظت شده فقط توسط کلاس تعریف کننده یا یک زیر کلاس قابل دسترسی هستند.
زیر کلاس‌ها مجاز هستند که توابع و ویژگی‌های محافظت‌شده را بدون تغییر نوع امضا لغو کنند.
به عنوان مثال، یک رندر سفارشی که کلاس رندر پایه را گسترش می دهد، ممکن است به ویژگی های محافظت شده آن دسترسی داشته باشد.
در هر مورد باید مطمئن شوید که نحوه استفاده از تابع یا ویژگی را در بقیه کدها درک کرده اید.
خصوصی
اینها فقط با کد موجود در همان فایل تعریف قابل دسترسی هستند. دسترسی مستقیم به این ویژگی ها ممکن است منجر به رفتار نامشخص شود.
زیر کلاس ها مجاز به لغو توابع و ویژگی های خصوصی نیستند.
دارایی های خصوصی بدون اخطار در معرض تغییر هستند، زیرا بخشی از API عمومی Blockly محسوب نمی شوند.
برخی از توابع در Blockly دارای حاشیه نویسی قابل مشاهده نیستند زیرا از ماژول خود صادر نمی شوند. این توابع اساساً متغیرهای محلی هستند و نمی توانند خارج از ماژول تعریف کننده آنها استفاده شوند. آنها باید معادل املاک خصوصی در نظر گرفته شوند.
داخلی
توابع و خصوصیات داخلی برای استفاده در کتابخانه هسته در نظر گرفته شده است، اما نه به صورت خارجی. آنها با حاشیه نویسی داخلی TsDoc @internal مشخص شده اند.
ویژگی‌های داخلی بدون اخطار ممکن است تغییر کنند، زیرا بخشی از API عمومی Blockly محسوب نمی‌شوند.
خصوصیات داخلی ممکن است از هر جایی در هسته قابل دسترسی باشد، و تا زمانی که امضا تغییر نکند، در زیر کلاس‌های هسته لغو شود. آنها نباید از خارج از کتابخانه اصلی قابل دسترسی باشند.
منسوخ شده است
هر چیزی که علامت گذاری شده @deprecated نباید استفاده شود. اکثر موارد منسوخ شده شامل دستورالعمل هایی در کد ترجیحی هستند، چه در یک هشدار کنسول یا TSDoc.
در صورت امکان، عملکردهای منسوخ شده هشداری را ثبت می کنند که شامل تاریخ حذف مورد نظر و توصیه ای برای فراخوانی یک تابع جایگزین است.
سوالات متداول
اگر تابعی که می خواهم استفاده کنم عمومی نباشد چه؟
درخواست ویژگی را در core Blockly ثبت کنید. شرحی از مورد استفاده خود و بیانیه ای در مورد آنچه که می خواهید عمومی کنیم را شامل کنید.
ما از این ویژگی برای درخواست بحث در مورد عمومی کردن آن یا راه‌های دیگری برای دریافت اطلاعات مشابه استفاده خواهیم کرد.
اگر تصمیم بگیریم آن را عمومی کنیم، یا شما یا تیم Blockly تغییر مناسبی را ایجاد می‌کنید و در نسخه بعدی Blockly پخش می‌شود.
اگر می‌خواهید از یک عضو غیرعمومی در افزونه استفاده کنید، افزونه خود را به‌عنوان بتا علامت‌گذاری کنید و اطلاعات را در README خود وارد کنید.
در مورد میمون وصله چی؟
در مورد monkeypatching بخوانید.
وصله میمون ناامن است، زیرا وصله‌ها می‌توانند بدون اطلاع قبلی به دلیل استفاده از قطعات غیرعمومی Blockly API کار نکنند. وصله کردن یک افزونه به ویژه خطرناک است، زیرا کد شما ممکن است با هر افزونه دیگری که میمون کد را وصله می کند، تعامل ضعیفی داشته باشد. به همین دلیل ما اکیداً از وصله میمون در برنامه‌ها و افزونه‌های شخص ثالث جلوگیری می‌کنیم و آن را در افزونه‌های شخص اول نمی‌پذیریم.
آیا می توانم توابع عمومی را نادیده بگیرم؟
هنگام طبقه بندی فرعی: بله. در غیر این صورت: نه، این میمون وصله است.
آیا می توانم توابع محافظت شده را لغو کنم؟
هنگام طبقه بندی فرعی: بله. در غیر این صورت: نه، این میمون وصله است.
آیا می توانم عملکردهای داخلی یا خصوصی را لغو کنم؟
نه، این میمون وصله است.
چه زمانی می توانم مستقیماً به املاک دسترسی داشته باشم؟ چه زمانی باید از گیر یا ستر استفاده کنم؟
اگر یک گیرنده یا تنظیم کننده منتشر می کنیم، لطفاً به جای دسترسی مستقیم به ملک از آن استفاده کنید. اگر ملک عمومی نیست حتما از گیر و ستر استفاده کنید.
اگر ملکی حاشیه نویسی نداشته باشد چه؟
به‌طور پیش‌فرض عمومی است، اما در صورتی که می‌خواهیم یک جفت گیرنده/ستر برای شما قرار دهیم، لطفاً یک خط برای ما بگذارید.
اگر یک تابع حاشیه نویسی نداشته باشد چه؟
به طور پیش فرض عمومی است.
اگر هنوز مطمئن نیستم چه؟
یک سوال در انجمن بپرسید و ما معمولاً ظرف یک روز کاری با شما تماس خواهیم گرفت.