تصف تعريفات الكتلة كيف تبدو الكتلة وسلوكها، بما في ذلك النص واللون والشكل والكتل الأخرى التي يمكن أن تتصل بها.
تنسيق JSON مقابل واجهة برمجة تطبيقات JavaScript
هناك طريقتان لتحديد الكتل في المحظورة: كائنات JSON ودوال JavaScript. تم تصميم تنسيق JSON لتبسيط عملية الترجمة عند تطوير اللغات ذات الترتيبات المختلفة للكلمات. تنسيق JSON هو الطريقة المفضلة لتعريف الكتل.
ومع ذلك، يتعذّر على تنسيق JSON تحديد الميزات المتقدّمة مباشرةً، مثل أدوات التبديل أو أدوات التحقّق. يجب كتابتها بلغة JavaScript، عادةً على شكل إضافات.
يمكن أيضًا للتطبيقات التي تستخدم عملية تنفيذ لغة JavaScript الأصلية بأسلوب Openly كتابة تعريفات الحظر مباشرةً على استدعاءات وظائف واجهة برمجة التطبيقات المحظورة على مستوى أدنى، كما هو موضَّح في أمثلة JavaScript المختلفة أدناه.
JSON
Blockly.defineBlocksWithJsonArray([{
"type": "string_length",
"message0": 'length of %1',
"args0": [
{
"type": "input_value",
"name": "VALUE",
"check": "String"
}
],
"output": "Number",
"colour": 160,
"tooltip": "Returns number of letters in the provided text.",
"helpUrl": "http://www.w3schools.com/jsref/jsref_length_string.asp"
}]);
JavaScript
Blockly.Blocks['string_length'] = {
init: function() {
this.appendValueInput('VALUE')
.setCheck('String')
.appendField('length of');
this.setOutput(true, 'Number');
this.setColour(160);
this.setTooltip('Returns number of letters in the provided text.');
this.setHelpUrl('http://www.w3schools.com/jsref/jsref_length_string.asp');
}
};
تنشئ الدالة init
شكل الكتلة. في سياق هذه
الوظيفة، تكون الكلمة الرئيسية this
هي الكتلة الفعلية التي يتم إنشاؤها.
يحمّل كلا المثالين مجموعة "string_length" نفسها.
على الويب، يتم تحميل تنسيق JSON باستخدام الدالة initJson
.
يتيح هذا أيضًا المزج بين التنسيقين في صفحات ويب المحظورة. ومن المفضّل تحديد الكتلة باستخدام JSON كلما أمكن ذلك، واستخدام JavaScript فقط مع أجزاء من تعريفات الكتل غير المتوافقة مع JSON.
في ما يلي مثال على مجموعة يتم تحديدها بشكل أساسي باستخدام JSON، ولكن تم توسيعها باستخدام واجهة برمجة تطبيقات JavaScript لعرض تلميح ديناميكي.
JavaScript
var mathChangeJson = {
"message0": "change %1 by %2",
"args0": [
{"type": "field_variable", "name": "VAR", "variable": "item", "variableTypes": [""]},
{"type": "input_value", "name": "DELTA", "check": "Number"}
],
"previousStatement": null,
"nextStatement": null,
"colour": 230
};
Blockly.Blocks['math_change'] = {
init: function() {
this.jsonInit(mathChangeJson);
// Assign 'this' to a variable for use in the tooltip closure below.
var thisBlock = this;
this.setTooltip(function() {
return 'Add a number to variable "%1".'.replace('%1',
thisBlock.getFieldValue('VAR'));
});
}
};
لون الكتلة
يتم تحديد اللون الأساسي للكتلة من خلال سمة JSON colour
، أو وظيفة
block.setColour(..)
،
أو من خلال استخدام المظاهر وتحديد نمط
الحظر.
JSON
{
// ...,
"colour": 160,
}
JavaScript
init: function() {
// ...
this.setColour(160);
}
ويمكنك الاطّلاع على دليل ألوان الكتلة للحصول على مزيد من التفاصيل.
اتصالات العبارات
يمكن للمستخدمين إنشاء تسلسلات من المجموعات باستخدام موصِّلَي nextStatement
وpreviousStatement
. في تخطيط Bluely، تكون هذه الاتصالات في
الجزء العلوي والسفلي، مع الكتل المكدسة عموديًا.
ولا يمكن أن تحتوي الوحدة التي تشتمل على موصل سابق على موصل إخراج، والعكس صحيح. يشير مصطلح مجموعة عبارات إلى مجموعة بدون ناتج قيمة. ستحتوي كتلة العبارة عادةً على اتصال سابق واتصال تالٍ.
ويمكن كتابة وصلات nextStatement
وpreviousStatement
، إلا أنّ هذه الميزة لا تُستخدم من خلال الوحدات الأساسية القياسية.
عملية الربط التالية
ينشئ نقطة أسفل القالب، بحيث يمكن تكديس العبارات الأخرى أسفلها. أما الجزء الذي يتضمن عملية ربط تالية ولكن بدون اتصال سابق فيمثل عادةً حدثًا، ويمكن إعداده للعرض باستخدام قبعة.
JSON
غير مكتوب:
{
...,
"nextStatement": null,
}
مكتوب (نادر):
{
"nextStatement": "Action",
...
}
JavaScript
غير مكتوب:
this.setNextStatement(true); // false implies no next connector, the default
مكتوب (نادر):
this.setNextStatement(true, 'Action');
عملية الربط السابقة
تنشئ شقًا في أعلى القطعة، بحيث يمكن ربطها كحزمة من العبارات.
لا يمكن إجراء اتصال ناتج عن الحظر باستخدام اتصال سابق.
JSON
غير مكتوب:
{
...,
"previousStatement": null,
}
مكتوب (نادر):
{
"previousStatement": "Action",
...
}
JavaScript
غير مكتوب:
this.setPreviousStatement(true); // false implies no previous connector, the default
مكتوب (نادر):
this.setPreviousStatement(true, 'Action');
حظر الإخراج
قد يكون للقطعة مخرج واحد، يتم تمثيله على شكل موصل jigsaw (وصلة) ذكر على الحافة الرائدة. ترتبط المخرجات بمدخلات القيمة. عادة ما يُطلق على الكتل التي لها مخرجات اسم كتل القيمة.
JSON
غير مكتوب:
{
// ...,
"output": null,
}
الكتابة:
{
// ...,
"output": "Number",
}
JavaScript
غير مكتوب:
init: function() {
// ...
this.setOutput(true);
}
الكتابة:
init: function() {
// ...
this.setOutput(true, 'Number');
}
لا يمكن أن تحتوي القوالب التي بها موصل إخراج على درجة سابقة أيضًا.
حظر الإدخالات
وتحتوي المجموعة على إدخال واحد أو أكثر، حيث يتوفر لكل إدخال سلسلة من الحقول وقد ينتهي باتصال. هناك العديد من أنواع المدخلات المضمنة.
- إدخال القيمة: يؤدي هذا الخيار إلى الاتصال باتصال ناتج لكتلة قيمة. كتلة
math_arithmetic
(الجمع والطرح) هي مثال على كتلة مع إدخالَين للقيمة. - إدخال عبارة: يؤدي هذا الخيار إلى الاتصال باتصال سابق ضمن مجموعة عبارات. القسم المتداخل من التكرار الحلقي while هو مثال على إدخال عبارة.
- الإدخال الوهمي: لا يتوفّر اتصال محدود. يعمل كسطر جديد عندما يتم ضبط الكتلة لاستخدام مدخلات القيمة الخارجية.
- إدخال صف النهاية: ليس به اتصال محظور، ويعمل دائمًا كخط جديد.
يمكنك أيضًا إنشاء إدخال مخصّص لتوفير العرض المخصّص.
يستخدم تنسيق JSON وواجهة برمجة تطبيقات JavaScript نماذج مختلفة قليلاً لوصف إدخالاتهما.
الإدخالات والحقول بتنسيق JSON
تكون كتل البرمجية المحددة بتنسيق JSON كسلسلة من سلاسل الرسائل المُدخلة ( message0
، message1
، ...)، حيث يكون كل رمز استقراء مميز
(%1
، %2
، ...) حقلاً أو نهاية إدخال (وبالتالي يتم عرض موصل الإدخال
داخل الرسالة) في مصفوفة JSON argsN
المطابقة. يهدف هذا التنسيق
لتسهيل عملية التدويل.
JSON
{
"message0": "set %1 to %2",
"args0": [
{
"type": "field_variable",
"name": "VAR",
"variable": "item",
"variableTypes": [""]
},
{
"type": "input_value",
"name": "VALUE"
}
]
}
يجب أن تتطابق الرموز المميّزة للاستيفاء مع مصفوفة args0
تمامًا: ما مِن تكرارات أو عمليات حذف. يمكن العثور على الرموز المميزة بأي ترتيب، ما يسمح للغات مختلفة بتغيير تنسيق الكتلة.
تتم إزالة النص الموجود على أي من جانبي رمز الاستيفاء المميز بمسافة بيضاء.
في النص الذي يستخدم الحرف %
(مثلاً، عند الإشارة إلى نسبة مئوية)، يجب استخدام
%%
لكي لا يتم تفسيره كرمز استقراء مطابق.
ويحدّد ترتيب الوسيطات وأنواع الوسيطات شكل الكتلة. يمكن أن يؤدي تغيير إحدى هذه السلاسل إلى تغيير تنسيق الكتلة بالكامل.
وهذا مهم بشكل خاص في اللغات التي يختلف ترتيب الكلمات فيها عن اللغة الإنجليزية. يُرجى وضع لغة افتراضية حيث يجب عكس "set %1 to %2"
(كما هو مستخدم
في المثال أعلاه) لتمثل "put %2 in %1"
. يؤدي تغيير هذه السلسلة الواحدة (وترك باقي سلسلة JSON
بدون أي تغييرات) إلى حدوث الكتلة التالية:
تم بشكل حظري تغيير ترتيب الحقول تلقائيًا وإنشاء إدخال وهمي والتبديل من مدخلات خارجية إلى داخلية.
يستبدل أيضًا بشكل تلقائي أي حرف سطر جديد (\n
) في سلسلة الرسالة
بإدخال صف النهاية.
JSON
{
"message0": "set %1\nto %2",
"args0": [
{
"type": "field_variable",
"name": "VAR",
"variable": "item",
"variableTypes": [""]
},
{
"type": "input_value",
"name": "VALUE"
}
]
}
أقواس
يتم إقران كل سلسلة رسالة بمصفوفة args
لها الرقم نفسه. على سبيل المثال، يتم استخدام message0
مع args0
. تشير الرموز المميّزة للاستيفاء
(%1
، %2
، ...) إلى عناصر مصفوفة args
. ويحتوي كل كائن على
سلسلة type
. وتختلف باقي المعلمات حسب النوع:
يمكنك أيضًا تحديد الحقول المخصّصة والإدخالات المخصّصة وضبطها كوسيطات.
قد يحتوي كل عنصر أيضًا على الحقل alt
. في حال لم يتعرّف تطبيق Blockly على type
للكائن، سيتم استخدام الكائن alt
بدلاً منه. على سبيل المثال، في حال إضافة حقل جديد يسمّى field_time
إلى حظر، قد تستخدم عمليات الحظر التي تستخدم هذا الحقل alt
لتحديد إجراء field_input
احتياطي للإصدارات الأقدم من حظر.
JSON
{
"message0": "sound alarm at %1",
"args0": [
{
"type": "field_time",
"name": "TEMPO",
"hour": 9,
"minutes": 0,
"alt":
{
"type": "field_input",
"name": "TEMPOTEXT",
"text": "9:00"
}
}
]
}
قد يكون للعنصر alt
كائن alt
خاص به، ما يسمح بالتسلسل.
في نهاية الأمر، إذا لم يتمكن حظر كائن في صفيف args0
(بعد محاولة
أي كائنات alt
)، يتم تخطي ذلك الكائن.
وستتم تلقائيًا إضافة إدخال وهمي إلى نهاية المجموعة إذا كانت
سلسلة message
تنتهي بنص أو حقول لا يتضمّنها أي إدخال.
وبالتالي، إذا كان الإدخال الأخير في الكتلة هو إدخال وهمي، قد يتم حذفه من الصفيف args
ولن يحتاج إلى الاستيفاء في message
. إنّ الإضافة التلقائية لإدخال وهمي مخصص للترجمات تسمح للمترجمين بتغيير message
بدون الحاجة إلى تعديل بقية ملفات JSON. يمكنك الاطّلاع على مثال "set %1 to %2"
(بدون إدخال وهمي) و"put %2 in %1"
(تمت إضافة إدخال وهمي)
في وقت سابق من هذه الصفحة.
implicitAlign0
في حالات نادرة، يجب محاذاة الإدخال الوهمي اللاحق الذي يتم إنشاؤه تلقائيًا مع "RIGHT"
أو "CENTRE"
. وتكون القيمة التلقائية هي "LEFT"
في حال عدم تحديدها.
في المثال أدناه، تكون القيمة message0
هي "send email to %1 subject %2 secure %3"
،
وتضيف بشكل تلقائي مدخلاً وهميًا إلى الصف الثالث. يؤدي ضبط
implicitAlign0
على "RIGHT"
إلى فرض محاذاة هذا الصف إلى اليمين. وتنطبق هذه
المحاذاة على جميع الإدخالات التي لم يتم تحديدها صراحةً في تعريف كتلة JSON،
بما في ذلك مدخلات صف النهاية التي تحل محل أحرف السطر الجديد
('\n'
) في الرسالة. هناك أيضًا السمة lastDummyAlign0
التي تم إيقافها نهائيًا والتي تتّبع سلوك implicitAlign0
نفسه.
عند تصميم القوالب من أجل RTL (العربية والعبرية)، يتم عكس اتجاهها إلى اليمين واليسار.
وبالتالي، سيؤدي الترميز "RIGHT"
إلى محاذاة الحقول إلى اليسار.
message1
وargs1
وimplicitAlign1
تنقسم بعض القوالب بشكل طبيعي إلى جزءين منفصلين أو أكثر. ضع في الاعتبار هذا الجزء المتكرر الذي يتضمن صفين:
إذا تم وصف هذا الحظر برسالة واحدة، ستكون السمة message0
هي "repeat %1 times %2 do %3"
. هذه السلسلة غير ملائمة للمترجم،
ومن الصعب توضيح معنى استبدال %2
. وقد لا يكون الإدخال الوهمي %2
مطلوبًا أيضًا في بعض اللغات. وقد تكون هناك عدة قوالب ترغب في مشاركة نص الصف الثاني. الطريقة الأفضل هي أن يستخدم JSON
أكثر من خصائص رسالة ووسيطات واحدة:
JSON
{
"type": "controls_repeat_ext",
"message0": "repeat %1 times",
"args0": [
{"type": "input_value", "name": "TIMES", "check": "Number"}
],
"message1": "do %1",
"args1": [
{"type": "input_statement", "name": "DO"}
],
"previousStatement": null,
"nextStatement": null,
"colour": 120
}
يمكن تحديد أي عدد من سمات message
وargs
وimplicitAlign
بتنسيق JSON، بدءًا من 0 ثم زيادة الأعداد بشكل تسلسلي. يُرجى ملاحظة أن Block factory غير قادر على تقسيم الرسائل إلى أجزاء متعدّدة، ولكن
القيام بذلك يدويًا أمر بسيط.
الإدخالات والحقول في JavaScript
تتضمن واجهة برمجة تطبيقات JavaScript طريقة append
لكل نوع إدخال:
JavaScript
this.appendEndRowInput()
.appendField('for each')
.appendField('item')
.appendField(new Blockly.FieldVariable());
this.appendValueInput('LIST')
.setCheck('Array')
.setAlign(Blockly.inputs.Align.RIGHT)
.appendField('in list');
this.appendStatementInput('DO')
.appendField('do');
this.appendDummyInput()
.appendField('end');
يمكن أن تأخذ كل طريقة إضافة سلسلة معرّف تستخدمها أدوات إنشاء الرموز. نادرًا ما تحتاج المدخلات الوهمية والصف النهائي إلى الرجوع، وعادةً ما يُترك المعرف بدون ضبط.
تشمل واجهة برمجة تطبيقات JavaScript أيضًا طريقة appendInput
عامة لإلحاق
المدخلات المخصّصة. لاحظ أنه في هذه الحالة، يجب تمرير المعرّف
مباشرةً إلى الدالة الإنشائية للإدخال المخصص.
JavaScript
this.appendInput(new MyCustomInput('INPUT_NAME'))
.appendField('an example label')
تعرض كل طرق appendInput
(العامة وغير العامة) كائن الإدخال
حتى يمكن ضبطها بشكل أكبر باستخدام تسلسل الطرق. هناك ثلاث طرق مدمجة تستخدم لتهيئة الإدخالات.
setCheck
JavaScript
input.setCheck('Number');
تُستخدم هذه الدالة الاختيارية لفحص نوع الإدخالات المتصلة. إذا تم توفير وسيطة فارغة، تكون القيمة التلقائية، حينئذٍ قد يتم ربط هذا الإدخال بأي كتلة. يُرجى الاطّلاع على عمليات التحقّق من النوع لمعرفة التفاصيل.
setAlign
JavaScript
input.setAlign(Blockly.inputs.Align.RIGHT);
وتُستخدم هذه الدالة الاختيارية لمحاذاة الحقول (انظر أدناه). هناك ثلاث قيم وصفية ذاتية يمكن تمريرها كوسيطة إلى هذه الدالة:
Blockly.inputs.Align.LEFT
وBlockly.inputs.Align.RIGHT
و
Blockly.inputs.Align.CENTER
.
عند تصميم القوالب من أجل RTL (العربية والعبرية)، يتم عكس اتجاهها إلى اليمين واليسار.
وبالتالي، سيؤدي الترميز Blockly.inputs.Align.RIGHT
إلى محاذاة الحقول إلى اليسار.
appendField
بعد إنشاء إدخال وإلحاقه بكتلة باستخدام appendInput
، يمكن إضافة أي عدد من الحقول اختياريًا إلى الإدخال. غالبًا ما تُستخدم هذه الحقول
كتسميات لوصف الغرض من كل مدخلات.
JavaScript
input.appendField('hello');
أبسط عنصر حقل هو النص. اصطلاح Bluely هو استخدام النص الكامل باستثناء أسماء العلم (مثل Google وSQL).
يمكن أن يحتوي صف الإدخال على أي عدد من عناصر الحقول. يمكن ربط طلبات appendField
المتعددة معًا لإضافة عدة حقول بكفاءة إلى صف الإدخال نفسه.
JavaScript
input.appendField('hello')
.appendField(new Blockly.FieldLabel('Neil', 'person'));
استدعاء appendField('hello')
هو في الواقع اختصار لاستخدام دالة إنشاء
FieldLabel صريحة: appendField(new Blockly.FieldLabel('hello'))
.
المرة الوحيدة التي قد ترغب فيها في استخدام الدالة الإنشائية هي عند تحديد اسم فئة بحيث يمكن تصميم النص باستخدام قاعدة CSS.
مضمّنة في مقابل خارجية
يمكن عرض إدخالات سياسة الحظر على أنّها خارجية أو داخلية.
يمكن أن يحدد تعريف الحظر أسلوبًا منطقيًا اختياريًا للتحكم في ما إذا كانت الإدخالات مضمّنة أم لا. في حال كانت القيمة false
، ستكون أي إدخالات قيمة خارجية (مثل الكتلة اليسرى). في حال كانت القيمة true
، ستكون أي إدخالات للقيم مضمّنة (مثل الكتلة اليمنى أعلاه).
JSON
{
// ...,
"inputsInline": true
}
JavaScript
init: function() {
// ...
this.setInputsInline(true);
}
إذا لم يتم تعريفه، فسيستخدم تطبيقBlockly بعض الأساليب لتخمين الوضع الأفضل. إذا افترضنا أنّ تطبيقBlockly هو الخيار الصحيح، من المفضّل ترك هذا الحقل بدون تحديد، لأنّ الترجمة بلغات مختلفة يمكن أن تتضمّن أوضاعًا مختلفة تلقائيًا. يمكنك الاطّلاع في وقت سابق على مثال JSON عن "set %1 to %2"
(الإدخالات الخارجية) و"put %2 in %1"
(الإدخالات المضمَّنة) في هذه الصفحة.
استخدِم الإدخالات المضمَّنة عندما يكون من المحتمل أن تحتوي إحدى الأجزاء على مدخلات صغيرة، مثل الأرقام.
ويمكن للمستخدم تبديل هذا الخيار من خلال قائمة السياقات في حال كانت إعدادات collapse
مفعَّلة (يتم ضبط الإعدادات التلقائية على "صحيح" إذا كان مربّع الأدوات يحتوي على فئات).
الحقول
تحدد الحقول معظم عناصر واجهة المستخدم في كتلة واحدة. ويشمل ذلك تسميات السلاسل والصور وإدخالات البيانات الحرفية مثل السلاسل والأرقام. وأبسط مثال هو كتلة math_number
التي تستخدم field_input
للسماح للمستخدم بكتابة رقم.
يتم إلحاق الحقول بالكتلة باستخدام appendField.
يوفر بشكل حظر عدد من الحقول المضمّنة، بما في ذلك إدخالات النص ومنتقي الألوان والصور. يمكنك أيضًا إنشاء حقولك الخاصة.
→ مزيد من المعلومات حول الحقول المضمّنة.
→ مزيد من المعلومات حول إنشاء حقل مُخصص.
الرموز
تحدد الأيقونات عناصر واجهة المستخدم على الكتلة التي تعرض معلومات "meta" حول الكتلة.
يتم إلحاق الرموز بالكتلة باستخدام addIcon.
يوفر بشكل أساسي عددًا من الأيقونات المضمنة، بما في ذلك أيقونات التعليقات وأيقونات التحذير. يمكنك أيضًا إنشاء أيقوناتك الخاصة.
← مزيد من المعلومات حول إنشاء الرموز المخصّصة.
تلميحات
تقدم التلميحات مساعدة فورية عندما يمرر المستخدم الماوس فوق القطعة. إذا كان النص طويلاً، سيتم التفاف النص تلقائيًا.
JSON
{
// ...,
"tooltip": "Tooltip text."
}
JavaScript
init: function() {
this.setTooltip("Tooltip text.");
}
في واجهة برمجة تطبيقات JavaScript، يمكن أيضًا تعريف التلميحات كدالة بدلاً من
سلسلة ثابتة. وهذا يسمح للمساعدة الديناميكية. راجِع math_arithmetic
للاطّلاع على
مثال لتلميح يتغير حسب خيار القائمة المنسدلة
الذي تم اختياره.
JavaScript
Blockly.Blocks['math_arithmetic'] = {
init: function() {
// ...
// Assign 'this' to a variable for use in the tooltip closure below.
var thisBlock = this;
this.setTooltip(function() {
var mode = thisBlock.getFieldValue('OP');
var TOOLTIPS = {
'ADD': Blockly.Msg.MATH_ARITHMETIC_TOOLTIP_ADD,
'MINUS': Blockly.Msg.MATH_ARITHMETIC_TOOLTIP_MINUS,
'MULTIPLY': Blockly.Msg.MATH_ARITHMETIC_TOOLTIP_MULTIPLY,
'DIVIDE': Blockly.Msg.MATH_ARITHMETIC_TOOLTIP_DIVIDE,
'POWER': Blockly.Msg.MATH_ARITHMETIC_TOOLTIP_POWER
};
return TOOLTIPS[mode];
});
}
};
باستخدام واجهة برمجة تطبيقات JavaScript، يمكن أن تحدد المجموعات دالة، بدلاً من سلسلة ثابتة، تعرض سلسلة التلميح. ويسمح ذلك بعرض التلميحات الديناميكية.
يمكنك مراجعة math_arithmetic
للاطّلاع على مثال.
تخصيص
يمكنك أيضًا تخصيص مظهر التلميحات من خلال توفير وظيفة عرض مخصصة. أنشئ دالة تقبل معلمتين:
- أولاً، عنصر
<div>
حيث تعرض المحتوى - وثانيًا، العنصر الفعلي الذي يتم تحريكه فوقه والذي سيظهر تلميحًا
في نص الدالة، يمكنك عرض أي محتوى تريده في div. للحصول على سلسلة التلميح المحدَّدة بشأن الكتلة التي يتم تمرير الماوس فوقها، يمكنك استدعاء Blockly.Tooltip.getTooltipOfObject(element);
حيث element
هي المعلمة الثانية أعلاه.
أخيرًا، سجّل هذه الدالة حتى يتمكن تطبيق Blockly من استدعائها في الوقت المناسب:
Blockly.Tooltip.setCustomTooltip(yourFnHere);
للحصول على مثال، اطّلِع على العرض التوضيحي لنصائح الأدوات المخصّصة.
عنوان URL للمساعدة
يمكن أن ترتبط عمليات الحظر بصفحة مساعدة. وهو متاح لمستخدمي
Blockly for Web من خلال النقر بزر الماوس الأيمن على الحظر واختيار "مساعدة"
من قائمة السياق. إذا كانت هذه القيمة هي null
، ستظهر القائمة باللون الرمادي.
JSON
{
// ...,
"helpUrl": "https://en.wikipedia.org/wiki/For_loop"
}
JavaScript
init: function() {
// ...
this.setHelpUrl('https://en.wikipedia.org/wiki/For_loop');
}
وباستخدام واجهة برمجة تطبيقات JavaScript، يمكن أن تحدّد عمليات الحظر دالة بدلاً من سلسلة ثابتة تعرض سلسلة عنوان URL، ما يسمح بالحصول على مساعدة ديناميكية.
تغيير المستمعين وأدوات التحقّق من الصحة
يمكن أن تؤدي الكتل إلى تغيير دوال المستمعين التي تستدعي أي تغيير في مساحة العمل (بما في ذلك المهام غير المرتبطة بالمجموعة). تُستخدَم هذه الإشعارات في المقام الأول لضبط نص التحذير الخاص بالمجموعة أو إشعارات المستخدمين المشابهة خارج مساحة العمل.
وتتم إضافة هذه الدالة عن طريق استدعاء setOnChange باستخدام إحدى الدوالّ ويمكن تنفيذها أثناء إنشائها أو عبر إضافة JSON إذا كنت تنوي استخدامها على كلّ الأنظمة الأساسية.
JSON
{
// ...,
"extensions":["warning_on_change"],
}
Blockly.Extensions.register('warning_on_change', function() {
// Example validation upon block change:
this.setOnChange(function(changeEvent) {
if (this.getInput('NUM').connection.targetBlock()) {
this.setWarningText(null);
} else {
this.setWarningText('Must have an input block.');
}
});
});
JavaScript
Blockly.Blocks['block_type'] = {
init: function() {
// Example validation upon block change:
this.setOnChange(function(changeEvent) {
if (this.getInput('NUM').connection.targetBlock()) {
this.setWarningText(null);
} else {
this.setWarningText('Must have an input block.');
}
});
}
}
يستدعي النظام الدالة ويمرر حدث التغيير.
داخل الدالة، يشير this
إلى مثيل الكتلة.
ولأن الدالة يتم استدعاء الدالة عند استخدامها، يجب على المطورين التأكد من تشغيل المستمع بسرعة. يجب أن يكون المرء حذرًا من التغييرات التي تطرأ على مساحة العمل التي قد تتدفّق أو تعود إلى المستمع.
يمكنك الاطّلاع على عناصر حظر controls_flow_statements
وlogic_compare
وprocedures_ifreturn
للحصول على أمثلة.
وتجدُر الإشارة إلى أنّ الحقول القابلة للتعديل تحتوي على أدوات معالجة أحداث خاصة بها للتحقّق من صحة الإدخال وإحداث آثار جانبية.
أداة تبديل
تسمح المغيرات للكتل المتقدمة بتغيير الشكل، لا سيما عندما يفتح المستخدمون مربّع حوار لإضافة مكونات أو إزالتها أو إعادة ترتيبها. ويمكن إضافة أدوات التغيُّر
من خلال JSON باستخدام مفتاح mutator
.
JSON
{
// ...,
"mutator":"if_else_mutator"
}
الإعدادات لكل قسم
تحتوي مثيلات الحظر على عدد من الخصائص التي تضبط سلوكها مع المستخدم. يمكن استخدامها لتقييد مساحة العمل لتعكس خصائص معيّنة للمجال (على سبيل المثال، هناك حدث "بدء" واحد بالضبط)، أو تركيز جهد المستخدم (مثل برنامج تعليمي).
حالة قابلة للحذف
block.setDeletable(false);
وعند ضبطها على "خطأ"، لن يتمكّن المستخدم من حذف الحظر. حظر الإعدادات التلقائية للحذف في مساحة عمل قابلة للتعديل
قد يتم حذف أي كتلة (حتى تلك غير القابلة للإلغاء) آليًا:
block.dispose();
حالة قابلة للتعديل
block.setEditable(false);
عند ضبط السياسة على "خطأ"، لن يتمكّن المستخدم من تغيير حقول مجموعة الحظر (مثل القوائم المنسدلة وإدخالات النص). يتم ضبط القوالب تلقائيًا على قابلة للتعديل في مساحة عمل قابلة للتعديل.
الحالة القابلة للنقل
block.setMovable(false);
وعند ضبطها على "خطأ"، لن يتمكّن المستخدم من نقل المجموعة مباشرةً. قد لا يتم فصل الكتلة غير القابلة للنقل التي هي تابعة لكتلة أخرى عن تلك الكتلة، على الرغم من أنها ستتحرك مع الوحدة الرئيسية في حال نقل العنصر الرئيسي. يؤدّي هذا الخيار إلى حظر النص تلقائيًا على أنّه قابل للنقل على مساحة عمل قابلة للتعديل.
يمكن نقل أي قطعة (حتى تلك غير القابلة للنقل) آليًا بعد توفُّرها على مساحة العمل.
block.moveBy(dx, dy)
يكون موضع البداية للكتلة في مساحة عمل هو القيمة التلقائية (0، 0).
حظر البيانات
this.data = '16dcb3a4-bd39-11e4-8dfc-aa07a5b093db';
البيانات هي سلسلة اختيارية عشوائية يتم إرفاقها بالكتلة. عندما يتم ترتيب الكتلة في تسلسل، يتم وضع سلسلة البيانات في تسلسل معها. وهذا يشمل وقت تكرار الكتلة أو نسخها/لصقها.
غالبًا ما يستخدم هذا لربط كتلة بمورد خارجي.
عند التسلسل بتنسيق JSON، يتم تخزين البيانات كخاصية من المستوى الأعلى في المجموعة:
{
"type": "my_block",
"data": "16dcb3a4-bd39-11e4-8dfc-aa07a5b093db",
// etc..
}
عند إنشاء سلسلة البيانات بتنسيق XML (نظام التسلسل القديم المعبّأ بغلاف ثلجي)، يتم تخزين سلسلة البيانات في علامة <data></data>
ضمن المجموعة:
<block type="my_block">
<data>16dcb3a4-bd39-11e4-8dfc-aa07a5b093db</data>
<!-- etc... -->
</block>
تدمير
تتضمّن القوالب عنصر جذب destroy
، ويتم استدعاؤه عند حذفها من
مساحة العمل. يمكن استخدامها لتدمير أي نماذج بيانات احتياطية/موارد خارجية
مرتبطة بالمجموعة لم تعد هناك حاجة إليها.
JSON
{
// ...,
"extensions":["destroy"],
}
Blockly.Extensions.registerMixin('destroy', {
destroy: function() {
this.myResource.dispose();
}
});
JavaScript
Blockly.Blocks['block_type'] = {
destroy: function() {
this.myResource.dispose();
}
}
يتم استدعاء طريقة destroy
بعد التخلص من العنصر الرئيسي للكتلة، ولكن
قبل التخلص من أي من عناصرها الثانوية أو حقولها.
قوائم السياقات
تتضمن المجموعات تلقائيًا قائمة سياقات عند النقر بزر الماوس الأيمن عليها، ما يتيح للمستخدمين تنفيذ إجراءات مثل إضافة تعليقات أو تكرار القوالب.
يمكنك إيقاف قائمة السياقات لحزمة فردية من خلال تنفيذ ما يلي:
block.contextMenu = false;
ويمكنك أيضًا تخصيص الخيارات المعروضة في القائمة. لتخصيص القائمة لجميع
القوالب، ارجع إلى
مستندات قوائم السياق.
لتخصيص القائمة لوحدة تنظيمية واحدة، يمكنك تطبيق
customContextMenu
. تستخدم هذه الدالة مجموعة من خيارات القائمة
وتقوم بتعديلها في مكانها، مما يعني أنه يمكنك إضافة العناصر وإزالتها.
يمثل كل خيار قائمة كائنًا له ثلاث خصائص:
text
هو النص المعروض.enabled
قيمة منطقية. عند الإيقاف، يظهر الخيار ولكن مع نص رمادي.callback
هي الدالة التي سيتم طلبها عند النقر على الخيار.