حقول القائمة المنسدلة

يخزن حقل القائمة المنسدلة سلسلة كقيمتها والسلسلة كنص لها. وتكون القيمة مفتاحًا محايدًا لغويًا وسيتم استخدامه للوصول إلى النص ولن تتم ترجمته عند تبديل حظري بين اللغات. النص عبارة عن سلسلة يمكن لشخص عادي قراءتها وسيتم عرضها للمستخدم.

حقل القائمة المنسدلة

حقل قائمة منسدلة مع فتح المحرِّر

حقل القائمة المنسدلة على الجزء المصغَّر

إنشاء الفيديوهات

تستخدم الدالة الإنشائية للقائمة المنسدلة أداة إنشاء قوائم وvalidator اختيارية. يتمتع منشئ القائمة بالكثير من المرونة، ولكنه في الأساس مجموعة من الخيارات، كل خيار يحتوي على جزء يمكن للإنسان قراءته وسلسلة محايدة لغوية.

قوائم منسدلة نصية بسيطة

JSON

{
  "type": "example_dropdown",
  "message0": "drop down: %1",
  "args0": [
    {
      "type": "field_dropdown",
      "name": "FIELDNAME",
      "options": [
        [ "first item", "ITEM1" ],
        [ "second item", "ITEM2" ]
      ]
    }
  ]
}

JavaScript

Blockly.Blocks['example_dropdown'] = {
  init: function() {
    this.appendDummyInput()
        .appendField('drop down:')
        .appendField(new Blockly.FieldDropdown([
            ['first item', 'ITEM1'],
            ['second item', 'ITEM2']
        ]), 'FIELDNAME');
  }
};

يتيح فصل المعلومات التي يمكن للإنسان قراءتها عن المفتاح اللغوي المحايد الاحتفاظ بإعداد القائمة المنسدلة بين اللغات. على سبيل المثال، قد تحدّد نسخة باللغة الإنجليزية من كتلة [['left', 'LEFT'], ['right', 'RIGHT]]، بينما تحدِّد نسخة ألمانية من المجموعة نفسها [['links', 'LEFT'], ['rechts', 'RIGHT]].

القوائم المنسدلة للصور

قد تكون الخيارات في القائمة المنسدلة أيضًا صورًا بدلاً من نص. ويتم تحديد كائنات الصور باستخدام السمات src وwidth وheight وalt.

لاحظ أنه على الرغم من أن القائمة المنسدلة يمكن أن تحتوي على مزيج من خيارات النص وخيارات الصور، فإن الخيار الفردي لا يمكن أن يحتوي حاليًا على صورة ونص.

JSON

{
  "type": "image_dropdown",
  "message0": "flag %1",
  "args0": [
    {
      "type": "field_dropdown",
      "name": "FLAG",
      "options": [
        ["none", "NONE"],
        [{"src": "canada.png", "width": 50, "height": 25, "alt": "Canada"}, "CANADA"],
        [{"src": "usa.png", "width": 50, "height": 25, "alt": "USA"}, "USA"],
        [{"src": "mexico.png", "width": 50, "height": 25, "alt": "Mexico"}, "MEXICO"]
      ]
    }
  ]
}

JavaScript

Blockly.Blocks['image_dropdown'] = {
  init: function() {
    var input = this.appendDummyInput()
        .appendField('flag');
    var options = [
        ['none', 'NONE'],
        [{'src': 'canada.png', 'width': 50, 'height': 25, 'alt': 'Canada'}, 'CANADA'],
        [{'src': 'usa.png', 'width': 50, 'height': 25, 'alt': 'USA'}, 'USA'],
        [{'src': 'mexico.png', 'width': 50, 'height': 25, 'alt': 'Mexico'}, 'MEXICO']
    ];
    input.appendField(new Blockly.FieldDropdown(options), 'FLAG');
  }
};

القوائم المنسدلة الديناميكية

JSON

{
  "type": "dynamic_dropdown",
  "message0": "day %1",
  "args0": [
    {
      "type": "input_dummy",
      "name": "INPUT"
    }
  ],
  "extensions": ["dynamic_menu_extension"]
}

Blockly.Extensions.register('dynamic_menu_extension',
  function() {
    this.getInput('INPUT')
      .appendField(new Blockly.FieldDropdown(
        function() {
          var options = [];
          var now = Date.now();
          for(var i = 0; i < 7; i++) {
            var dateString = String(new Date(now)).substring(0, 3);
            options.push([dateString, dateString.toUpperCase()]);
            now += 24 * 60 * 60 * 1000;
          }
          return options;
        }), 'DAY');
  });

ويتم ذلك باستخدام إضافة JSON.

JavaScript

Blockly.Blocks['dynamic_dropdown'] = {
  init: function() {
    var input = this.appendDummyInput()
      .appendField('day')
      .appendField(new Blockly.FieldDropdown(
        this.generateOptions), 'DAY');
  },

  generateOptions: function() {
    var options = [];
    var now = Date.now();
    for(var i = 0; i < 7; i++) {
      var dateString = String(new Date(now)).substring(0, 3);
      options.push([dateString, dateString.toUpperCase()]);
      now += 24 * 60 * 60 * 1000;
    }
    return options;
  }
};

يمكن أيضًا توفير قائمة منسدلة بدالة بدلاً من قائمة من الخيارات الثابتة، مما يسمح بأن تكون الخيارات ديناميكية. يجب أن تعرض الدالة مجموعة من الخيارات بتنسيق [human-readable-value, language-neutral-key] نفسه كخيارات ثابتة. في كل مرة يتم فيها النقر على القائمة المنسدلة، يتم تشغيل الدالة وإعادة حساب الخيارات.

ملاحظة: لا تحدث مطابقة البادئة/اللاحقة للقوائم المنسدلة الديناميكية.

التسلسل

JSON

يبدو ملف JSON لحقل القائمة المنسدلة كما يلي:

{
  "fields": {
    "FIELDNAME": "LANGUAGE-NEUTRAL-KEY"
  }
}

حيث تكون FIELDNAME سلسلة تشير إلى حقل قائمة منسدلة، والقيمة هي القيمة المطلوب تطبيقها على الحقل. يجب أن تكون القيمة مفتاح خيار محايدًا لغويًا.

XML

يبدو نموذج XML لحقل القائمة المنسدلة على النحو التالي:

<field name="FIELDNAME">LANGUAGE-NEUTRAL-KEY</field>

تتضمّن السمة name الخاصة بالحقل سلسلة تشير إلى حقل قائمة منسدلة، ويكون النص الداخلي هو القيمة المطلوب تطبيقها على الحقل. يجب أن يكون النص الداخلي مفتاح خيار صالحًا ومحايدًا لغويًا.

التخصيص

سهم القائمة المنسدلة

يمكن استخدام السمة Blockly.FieldDropdown.ARROW_CHAR لتغيير حرف unicode الذي يمثّل سهم القائمة المنسدلة.

يتم ضبط السمة ARROW_CHAR تلقائيًا على \u25BC (▼) في نظام التشغيل Android و\u25BE (⋮) وغير ذلك.

هذا موقع عام، لذا سيعدّل جميع حقول القائمة المنسدلة عند إعدادها.

ارتفاع القائمة

يمكن استخدام السمة Blockly.FieldDropdown.MAX_MENU_HEIGHT_VH لتغيير الحد الأقصى لارتفاع القائمة. ويتم تعريفه كنسبة مئوية من ارتفاع إطار العرض، حيث يمثل إطار العرض النافذة.

القيمة التلقائية للسمة MAX_MENU_HEIGHT_VH هي 0.45.

هذا موقع عام، لذا سيعدّل جميع حقول القائمة المنسدلة عند إعدادها.

مطابقة البادئة/اللاحقة

إذا كانت جميع خيارات القائمة المنسدلة تشترك في كلمات بادئة و/أو لاحقة شائعة، فسيتم تحليل هذه الكلمات تلقائيًا وإدراجها كنص ثابت. على سبيل المثال، إليك طريقتين لإنشاء نفس الكتلة (الأولى بدون مطابقة اللاحقة والثانية باستخدام):

بدون مطابقة اللاحقة:

JSON

{
  "type": "dropdown_no_matching",
  "message0": "hello %1",
  "args0": [
    {
      "type": "field_dropdown",
      "name": "MODE",
      "options": [
        ["world", "WORLD"],
        ["computer", "CPU"]
      ]
    }
  ]
}

JavaScript

Blockly.Blocks['dropdown_no_matching'] = {
  init: function() {
    var options = [
      ['world', 'WORLD'],
      ['computer', 'CPU']
    ];

    this.appendDummyInput()
        .appendField('hello')
        .appendField(new Blockly.FieldDropdown(options), 'MODE');
  }
};

مع مطابقة اللاحقة:

JSON

{
  "type": "dropdown_with_matching",
  "message0": "%1",
  "args0": [
    {
      "type": "field_dropdown",
      "name": "MODE",
      "options": [
        ["hello world", "WORLD"],
        ["hello computer", "CPU"]
      ]
    }
  ]
}

JavaScript

Blockly.Blocks['dropdown_with_matching'] = {
  init: function() {
    var options = [
      ['hello world', 'WORLD'],
      ['hello computer', 'CPU']
    ];

    this.appendDummyInput()
        .appendField(new Blockly.FieldDropdown(options), 'MODE');
  }
};

تتمثل إحدى ميزات هذا النهج في سهولة ترجمة الحظر إلى لغات أخرى. تحتوي التعليمة البرمجية السابقة على السلاسل 'hello' و'world' و'computer'، بينما تحتوي التعليمة البرمجية التي تمت مراجعتها على السلاسل 'hello world' و'hello computer'. وقت ترجمة العبارات أسهل بكثير من ترجمة الكلمات المعزولة.

الميزة الأخرى لهذا النهج هي أن ترتيب الكلمات غالبًا ما يتغير بين اللغات. تخيَّل لغة استخدمت 'world hello' و'computer hello'. ستكتشف خوارزمية مطابقة اللاحقة السمة 'hello' الشائعة وتعرضها بعد القائمة المنسدلة.

ومع ذلك، تفشل أحيانًا مطابقة البادئة/اللاحقة. هناك بعض الحالات التي يجب فيها دائمًا جمع كلمتين معًا ولا ينبغي وضع البادئة في الاعتبار. على سبيل المثال، يجب تضمين 'drive' فقط في 'drive red car' و'drive red truck'، وليس 'drive red'. يمكن استخدام مسافة '\u00A0' غير الفاصلة في يونيكود بدلاً من مسافة عادية لإيقاف مُطابق البادئة/اللاحقة. وبالتالي يمكن إصلاح المثال أعلاه باستخدام 'drive red\u00A0car' و'drive red\u00A0truck'.

هناك مكان آخر تفشل فيه مطابقة البادئة/اللاحقة وهو في اللغات التي لا تفصل الكلمات الفردية بمسافات. اللغة الصينية هي مثال جيد. السلسلة '訪問中國' تعني 'visit China'. يُرجى العلم أنّ هناك عدم وجود مسافات بين الكلمات. ويمثّل آخر حرفين ('中國') معًا كلمة 'China'، ولكن في حال تقسيمه، يعني ذلك 'centre' و'country' على التوالي. للتمكّن من مطابقة البادئات أو اللاحقة بلغات مثل الصينية، أدخِل مسافة في المكان الذي يجب وضع الفاصل فيه. على سبيل المثال، سيؤدي الترميزان '訪問 中國' و'訪問 美國' إلى "visit [China/USA]"، بينما ينتج عن '訪問 中 國' و'訪問 美 國' النتيجة "visit [centre/beautiful] country".

إنشاء أداة التحقق من القائمة المنسدلة

ملاحظة: للحصول على معلومات عن أدوات التحقّق بشكل عام، يمكنك الاطّلاع على أدوات التحقّق.

إنّ قيمة حقل القائمة المنسدلة هي سلسلة محايدة لغوية، لذلك يجب أن تقبل أي أداة تحقق سلسلة وتعرض سلسلة تمثّل خيارًا متاحًا أو null أو undefined.

إذا أعادت أداة التحقق عرض أي شيء آخر، سيكون سلوك تطبيق Blockly غير محدّد، وقد يتعطّل برنامجك.

على سبيل المثال، يمكنك تحديد حقل قائمة منسدلة بثلاثة خيارات وأداة تحقق على النحو التالي:

validate: function(newValue) {
  this.getSourceBlock().updateConnections(newValue);
  return newValue;
},

init: function() {
  var options = [
   ['has neither', 'NEITHER'],
   ['has statement', 'STATEMENT'],
   ['has value', 'VALUE'],
  ];

  this.appendDummyInput()
  // Pass the field constructor the options list, the validator, and the name.
      .appendField(new Blockly.FieldDropdown(options, this.validate), 'MODE');
}

تعرض validate دائمًا القيمة التي تم تمريرها، ولكنها تستدعي الدالة المساعِدة updateConnection التي تضيف الإدخالات أو تزيلها استنادًا إلى قيمة القائمة المنسدلة:

updateConnections: function(newValue) {
  this.removeInput('STATEMENT', /* no error */ true);
  this.removeInput('VALUE', /* no error */ true);
  if (newValue == 'STATEMENT') {
    this.appendStatementInput('STATEMENT');
  } else if (newValue == 'VALUE') {
    this.appendValueInput('VALUE');
  }
}