Kérdőívek készítése QML-lel
Ez az útmutató bemutatja, hogyan készíthet kérdőíveket QML-lel (Questionnaire Markup Language), amely egy YAML-alapú nyelv összetett kérdőívekhez, formális ellenőrzéssel, dinamikus folyamatvezérléssel és adatvalidálással.

Az Armiger böngészős szerkesztője: a projektböngésző és az MI-generálás csevegője (balra), a QML-kód (középen), a folyamatábra és a kiválasztott kérdés élő előnézete (jobbra).
Gyors kezdés
Szekció neve “Gyors kezdés”Minden QML-kérdőív ezzel a szerkezettel kezdődik:
qmlVersion: "2.0"questionnaire: title: "Your Survey Title" blocks: - id: b_first_section title: "First Section" items: - id: q_first_question kind: Question title: "Your first question" input: control: Radio labels: 1: "Option 1" 2: "Option 2"A qmlVersion mező adja meg, hogy a dokumentum a QML melyik főverziójához készült. A jelenlegi főverzió a 2, ezért "2.0" értéket adjon meg (vagy "2.1" értéket, ha a legújabb opcionális funkciókat is használni szeretné). A régi 1.x nyelvtanhoz írt dokumentumok már nem tölthetők be, ezeket migrálni kell. A teljes nyelvtant, az elemtípusokat és a haladó blokkokat a QML-szintaxis referenciája ismerteti.
Alapfogalmak
Szekció neve “Alapfogalmak”Blokkok: a kérdőív tagolása
Szekció neve “Blokkok: a kérdőív tagolása”Egy blokknak három feladata van:
- Csoportosítás: az összetartozó kérdéseket egy szakaszba gyűjti.
- Elágazás: az előfeltétele a benne lévő összes kérdésre érvényes, így egyetlen feltétel dönti el, hogy a válaszadó látja-e a teljes szakaszt.
- Ismétlés: egy
Rosterblokk a kérdéseit minden kiválasztott entitásra egyszer teszi fel (lásd: Haladó blokktípusok).
A legegyszerűbb felhasználás a csoportosítás:
blocks: - id: b_demographics title: "About You" items: # Questions about the respondent
- id: b_preferences title: "Your Preferences" items: # Questions about preferencesBlokkszintű előfeltételek
Szekció neve “Blokkszintű előfeltételek”A blokkoknak saját előfeltételeik is lehetnek. Ha egy blokknak van előfeltétele, az automatikusan a blokk minden elemére vonatkozik – nem kell ugyanazt a feltételt minden kérdésnél megismételnie.
blocks: - id: b_employment title: "Employment Details" precondition: - predicate: q_employed.outcome == 1 items: - id: q_job_title kind: Question title: "What is your job title?" input: control: Dropdown labels: 1: "Manager" 2: "Professional" 3: "Technician"
- id: q_years_employed kind: Question title: "How many years have you worked there?" input: control: Editbox min: 0 max: 50Ebben a példában a q_job_title és a q_years_employed is örökli a blokk q_employed.outcome == 1 előfeltételét. Az elemek saját, további előfeltételeket is megadhatnak – a blokk előfeltétele és az elemszintű előfeltételek együtt érvényesülnek.
Bevált gyakorlatok:
- Használjon beszédes,
b_előtaggal kezdődő azonosítókat (pl.b_demographics,b_experience) - Csoportosítsa a tematikusan összetartozó kérdéseket
- Ha lehetséges, a függőségeket tartsa blokkon belül
- Ha két vagy több kérdésnek ugyanaz a megjelenítési feltétele, tegye őket saját blokkba, és a feltételt egyszer, a blokknál írja meg; elemszintű előfeltételt csak az adott kérdésre jellemző feltételhez használjon
- A blokk előfeltétele a blokk előtti kérdések válaszait és változóit olvassa, ezért a blokkot az azt eldöntő kérdés után helyezze el
Haladó blokktípusok
Szekció neve “Haladó blokktípusok”Alapértelmezés szerint a blokk egy Group, amely minden elemét egyszer kérdezi meg. Két opcionális változat dinamikusabb kérdőívekhez nyújt megoldást:
- Ismétlődő szakaszok (
Roster) – egy kérdéssort minden kiválasztott elemre megismétel (például ugyanazokat a részleteket kérdezi meg a válaszadó által elfogyasztott minden étkezésről vagy minden családtagról). - Adaptív kiválasztás (
count) – egyGroupblokkot úgy korlátoz, hogy csak az első N szóba jövő elemet kérdezze meg (például egy nagyobb kérdéskészletből 3 kérdést mutat).
Mindkettőt részletesen, példákkal ismerteti a QML-szintaxis referenciája.
Elemek: a kérdések típusai
Szekció neve “Elemek: a kérdések típusai”A QML négy elemtípust támogat:
1. Comment (tájékoztató szöveg)
Szekció neve “1. Comment (tájékoztató szöveg)”Szöveget jelenít meg válasz gyűjtése nélkül:
- id: q_intro kind: Comment title: "Please answer honestly. Your responses are confidential."2. Question (egyetlen válasz)
Szekció neve “2. Question (egyetlen válasz)”Egy kérdést tesz fel, és egy választ gyűjt:
- id: q_age kind: Question title: "What is your age?" input: control: Editbox min: 18 max: 1203. QuestionGroup (több összetartozó kérdés)
Szekció neve “3. QuestionGroup (több összetartozó kérdés)”Több kérdést tesz fel azonos válaszformátummal:
- id: q_satisfaction kind: QuestionGroup title: "Rate your satisfaction with:" questions: - "Customer service" - "Product quality" - "Delivery speed" input: control: Radio labels: 1: "Very Dissatisfied" 2: "Dissatisfied" 3: "Neutral" 4: "Satisfied" 5: "Very Satisfied"4. MatrixQuestion (rács)
Szekció neve “4. MatrixQuestion (rács)”Sorok és oszlopok szerinti formátumban gyűjti a válaszokat:
- id: q_skills kind: MatrixQuestion title: "Rate your proficiency in:" rows: - "Python" - "JavaScript" - "SQL" columns: - "Beginner" - "Intermediate" - "Advanced" input: control: Radio labels: 1: "No experience" 2: "Some experience" 3: "Proficient"Beviteli vezérlők
Szekció neve “Beviteli vezérlők”Minden kérdésnek meg kell adnia, hogyan gyűjti a válaszokat.
Switch (igen/nem)
Szekció neve “Switch (igen/nem)”Kétértékű választás:
input: control: Switch on: "Yes" off: "No"Radio (egy választás)
Szekció neve “Radio (egy választás)”Egy lehetőség kiválasztása több közül:
input: control: Radio labels: 1: "Option A" 2: "Option B" 3: "Option C"Checkbox (több választás)
Szekció neve “Checkbox (több választás)”Nulla vagy több lehetőség kiválasztása:
input: control: Checkbox labels: 1: "Feature A" 2: "Feature B" 4: "Feature C" 8: "Feature D"Dropdown (választás listából)
Szekció neve “Dropdown (választás listából)”Tömör kiválasztás sok lehetőség közül:
input: control: Dropdown labels: 1: "High School" 2: "Bachelor's" 3: "Master's" 4: "PhD" left: "Education:"Editbox (számbevitel)
Szekció neve “Editbox (számbevitel)”Szabad számbevitel:
input: control: Editbox min: 0 max: 1000000 left: "Annual income: $"Slider (vizuális skála)
Szekció neve “Slider (vizuális skála)”Vizuális kiválasztás egy skála mentén:
input: control: Slider min: 0 max: 10 step: 1 labels: 0: "Not at all" 5: "Somewhat" 10: "Extremely"Range (intervallum kiválasztása)
Szekció neve “Range (intervallum kiválasztása)”Intervallum kiválasztása két csúszkafogóval (-tól -ig). A válasz egy [low, high] pár, ahol min <= low <= high <= max.
input: control: Range min: 0 max: 100 step: 5 labels: 0: "Minimum" 50: "Mid" 100: "Maximum" default: [20, 80]Textarea (szabad szöveg)
Szekció neve “Textarea (szabad szöveg)”Nyitott, kvalitatív válaszokhoz használja a Textarea vezérlőt. Minden más vezérlővel ellentétben az eredménye karakterlánc, nem egész szám – ezért nem használható elágazási logikában vagy formális ellenőrzésben (ha egy előfeltétel, utófeltétel vagy kódblokk egy Textarea eredményére hivatkozik, az tervezési hiba). Olyan megjegyzésekhez, javaslatokhoz vagy magyarázatokhoz használja, amelyeket később el szeretne olvasni vagy kódolni.
input: control: Textarea placeholder: "Tell us more..." maxLength: 500A placeholder (az üres mezőben megjelenő tippszöveg) és a maxLength (karakterkorlát) egyaránt elhagyható.
Feltételes logika
Szekció neve “Feltételes logika”Kérdések feltételes megjelenítése (előfeltételek)
Szekció neve “Kérdések feltételes megjelenítése (előfeltételek)”Előfeltételekkel a korábbi válaszoktól függően jeleníthet meg kérdéseket:
- id: q_has_car kind: Question title: "Do you own a car?" input: control: Switch
- id: q_car_brand kind: Question title: "What brand is your car?" precondition: - predicate: q_has_car.outcome == 1 input: control: Dropdown labels: 1: "Toyota" 2: "Honda" 3: "Ford"A q_car_brand kérdés csak akkor jelenik meg, ha a válaszadó „Igen”-nel válaszolt arra, hogy van-e autója.
Összetett előfeltételek:
precondition: - predicate: q_age.outcome >= 25 and q_employment.outcome in [1, 2, 3]Az elágazások áttekintése: a diagram fanézete
Szekció neve “Az elágazások áttekintése: a diagram fanézete”A QML melletti folyamatábrának két nézete van, amelyek között a bal felső sarokban található Sorrend és Fa gombokkal válthat.
- A Sorrend (az alapértelmezett) minden kérdést abban a sorrendben mutat, ahogyan az interjú felteszi őket, mellettük a feltételeikkel.
- A Fa ugyanezeket a kérdéseket elágazásokként mutatja. Az azonos feltételű kérdések – akár a blokkjukon szerepel a feltétel, akár minden kérdésnél megismétlődik – egy ágat alkotnak, és az az ág, amelynek feltétele csak egy másikon belül teljesülhet, annak belsejében jelenik meg. Egy szűrőkérdés „igen” és „nem” ágai egymás mellett láthatók, az a kiegészítő kérdés pedig, amelyet csak az „igen” ágon tesznek fel, ebbe az ágba ágyazva jelenik meg.
Az összefüggéseket a Z3 bizonyítja, nem a szövegből következtetünk rájuk. A fát a rendszer akkor számítja ki, amikor átvált rá, ezért az első váltás eltart egy pillanatig; ha nem számítható ki, a diagram a sorrendnézetben marad, és megmondja, miért. Minden ág címkéje azt jelzi, mit állapított meg a Z3:
| Jelölés | Jelentés |
|---|---|
| vagy-vagy | Ez az ág és a szomszédja soha nem érvényes egyszerre: a válaszadó vagy az egyik, vagy a másik utat járja be |
| párhuzamos | Mindkettő érvényes lehet ugyanarra a válaszadóra: opcionális szakaszok, amelyeket akár mindkettőt is feltehetnek |
| ? kizáró, ? beágyazott, ? teljesül | A Z3 nem tudta eldönteni (például egy olyan feltételnél, amelyet nem tud teljesen kifejezni, vagy egy olyannál, amely egy válaszra vagy számított értékre vonatkozik az interjú két különböző pontján): az ág ott jelenik meg, ahol bizonyított, a jelölés pedig megmondja, mi maradt eldöntetlen |
| soha / mindig | Az ág feltétele soha nem teljesülhet, illetve mindig teljesül |
Két azonos feltételszövegű kérdés csak akkor alkot egy ágat, ha a feltétel mindkettőnél ugyanazt jelenti: ha a kettő között egy kódblokk megváltoztat egy változót, amelyet a feltétel olvas, mindkettő saját ágat kap.
Az utófeltételek nem ágaznak el, ezért mindkét nézetben a kérdéseik mellett maradnak.
A válaszok ellenőrzése (utófeltételek)
Szekció neve “A válaszok ellenőrzése (utófeltételek)”Utófeltételekkel biztosíthatja a logikai következetességet:
- id: q_household_size kind: Question title: "How many people live in your household?" input: control: Editbox min: 1 max: 20
- id: q_children kind: Question title: "How many children under 18 live in your household?" postcondition: - predicate: q_children.outcome < q_household_size.outcome hint: "Number of children must be less than household size" input: control: Editbox min: 0 max: 15Ha egy válaszadó érvénytelen adatot ad meg (pl. 5 gyereket egy háromfős háztartásban), megjelenik a tippüzenet.
Kódblokkok és változók
Szekció neve “Kódblokkok és változók”A QML beágyazott Python-kódot tesz lehetővé számításokhoz és dinamikus logikához.
Változók inicializálása
Szekció neve “Változók inicializálása”A codeInit segítségével állíthatja be a nyilvántartásra szolgáló segédváltozókat:
questionnaire: codeInit: | total_score = 0 risk_level = 0Számítás a válaszok után
Szekció neve “Számítás a válaszok után”Kódblokkokat csatolhat az elemekhez számítások futtatásához:
- id: q_satisfaction kind: Question title: "Rate your overall satisfaction (0-10)" codeBlock: | # Calculate satisfaction category if q_satisfaction.outcome >= 9: satisfaction_category = 3 # Promoter elif q_satisfaction.outcome >= 7: satisfaction_category = 2 # Passive else: satisfaction_category = 1 # Detractor
# Add to running total total_score += q_satisfaction.outcome input: control: Slider min: 0 max: 10Támogatott Python-funkciók
Szekció neve “Támogatott Python-funkciók”A QML-kód sandboxban fut, de a Pythonnak csak egy részhalmaza fordítható le arra a formális (Z3) modellre, amely a kérdőívét ellenőrzi. Maradjon ezen a részhalmazon belül, hogy a logikájára kiterjedjen az ellenőrzés:
✓ Ellenőrzött részhalmaz:
- Aritmetika:
+,-,*,//,% - Összehasonlítások:
<,<=,>,>=,==,!=(láncolva is, pl.0 < x < 10) - Tartalmazás:
in,not in(pl.q_x.outcome in [1, 2, 3]) - Logikai műveletek:
and,or,not - Feltételes utasítások:
if,elif,else - Háromoperandusú kifejezések:
x = 1 if condition else 0 - For ciklusok:
for i in range(n)(n ≤ 20) - Lista-, tuple- és halmazliterálok (≤ 20 elem)
- Tuple-kibontás:
a, b = 1, 0 - Értékadás:
x = value,x += value - Beépített függvények:
range(),abs(),int(),bool() - Eredmények elérése:
q_age.outcome
✗ Az ellenőrzött részhalmazon kívül (lásd az alábbi megjegyzést):
- Importok, függvények, osztályok
- While ciklusok,
break,continue - Szótárműveletek
- Karakterlánc-metódusok
- Listaértelmezések (list comprehension)
- Print utasítások (a rendszer jelzés nélkül figyelmen kívül hagyja őket)
Gyakori minták
Szekció neve “Gyakori minták”Fokozatos feltárás
Szekció neve “Fokozatos feltárás”A kérdéseket a korábbi válaszok alapján fokozatosan jelenítse meg. Blokkszintű előfeltételekkel elkerülheti, hogy ugyanazt a feltételt minden elemnél meg kelljen ismételnie:
- id: b_screening items: - id: q_employed kind: Question title: "Are you currently employed?" input: control: Switch
- id: b_employment precondition: - predicate: q_employed.outcome == 1 items: - id: q_job_title kind: Question title: "What is your job title?" input: control: Dropdown labels: 1: "Manager" 2: "Professional" 3: "Technician"
- id: q_years_employed kind: Question title: "How many years have you worked there?" input: control: Editbox min: 0 max: 50A q_job_title és a q_years_employed automatikusan örökli a blokk előfeltételét – csak akkor jelennek meg, ha a válaszadónak van munkája.
Pontozás és kategorizálás
Szekció neve “Pontozás és kategorizálás”Pontszámok kiszámítása és a válaszadók kategorizálása:
questionnaire: codeInit: | risk_score = 0
blocks: - id: b_assessment items: - id: q_factor1 kind: Question title: "Do you smoke?" codeBlock: | if q_factor1.outcome == 1: risk_score += 20 input: control: Switch
- id: q_factor2 kind: Question title: "Do you exercise regularly?" codeBlock: | if q_factor2.outcome == 0: risk_score += 15 input: control: Switch
- id: q_result kind: Comment title: "Assessment complete" codeBlock: | if risk_score >= 30: risk_category = "high" elif risk_score >= 15: risk_category = "moderate" else: risk_category = "low"Adatminőség-ellenőrzés
Szekció neve “Adatminőség-ellenőrzés”Biztosítsa a válaszok minőségét elemek közötti ellenőrzéssel:
- id: q_age kind: Question title: "Your age" input: control: Editbox min: 18 max: 100
- id: q_work_experience kind: Question title: "Years of work experience" postcondition: - predicate: q_work_experience.outcome <= (q_age.outcome - 16) hint: "Work experience cannot exceed your potential working years" input: control: Editbox min: 0 max: 60Bevált gyakorlatok
Szekció neve “Bevált gyakorlatok”Kérdéstervezés
Szekció neve “Kérdéstervezés”- Legyen konkrét: „Mennyi a háztartása éves jövedelme?” a „Jövedelem?” helyett
- Használjon megfelelő vezérlőket: Editbox a pontos számokhoz, Slider a szubjektív értékelésekhez
- Állítson be reális tartományokat: a min/max értékek tükrözzék a valós korlátokat
- Adjon kontextust: a mértékegységekhez és pontosításokhoz használja a
left/rightszöveget
Függőségek kezelése
Szekció neve “Függőségek kezelése”- Tartsa együtt az összetartozó elemeket ugyanabban a blokkban
- A sorrend számít: a kérdéseknek meg kell előzniük azokat a helyeket, ahol hivatkoznak rájuk
- Tesztelje az összes útvonalat: győződjön meg róla, hogy minden kérdés elérhető
Ellenőrzési stratégia
Szekció neve “Ellenőrzési stratégia”- Állítson be értéktartomány-korlátokat a beviteli vezérlő min/max értékeivel
- Használjon utófeltételeket a logikai következetességhez
- Adjon hasznos tippeket: az egyértelmű hibaüzenetek eligazítják a válaszadókat
- Gondoljon a szélsőséges esetekre: mi történik, ha valaki szélsőséges értéket ad meg?
Irányelvek a kódblokkokhoz
Szekció neve “Irányelvek a kódblokkokhoz”- Inicializáljon korán: a változókat a
codeInitrészben állítsa be - Törekedjen az egyszerűségre: az összetett számításokban nehéz megtalálni a hibát
- Gondoljon a hatókörre: minden változó globális
- Teszteljen alaposan: futtassa a kérdőív-ellenőrzőt
Formális ellenőrzés
Szekció neve “Formális ellenőrzés”A rendszer a QML-kérdőíveket automatikusan ellenőrzi a következők szempontjából:
- Elérhetőség: elérhető-e minden kérdés?
- Konzisztencia: teljesíthetők-e az ellenőrzési szabályok?
- Körök: alkotnak-e kört a függőségek?
- Teljesség: van-e legalább egy érvényes kitöltési útvonal?
Az ellenőrző matematikai elemzéssel (SMT-megoldással) még az élesítés előtt felismeri a tervezési hibákat.
A matematikai részleteket az Elmélet fejezet tartalmazza.
Ha ugyanazt a kérdőívet több nyelven szeretné felvenni, másolás helyett adjon hozzá fordításokat: a fordítás csak a szöveget cseréli le, így az ellenőrzés, az elágazások és a válaszkódok az Ön által írt kérdőívhez kötődnek.
Teljes példa
Szekció neve “Teljes példa”qmlVersion: "2.0"questionnaire: title: "Customer Feedback Survey" codeInit: | nps_score = 0 follow_up_needed = 0
blocks: - id: b_intro title: "Welcome" items: - id: q_welcome kind: Comment title: "Thank you for taking our survey. It will take about 3 minutes."
- id: b_experience title: "Your Experience" items: - id: q_nps kind: Question title: "How likely are you to recommend us? (0 = Not at all, 10 = Extremely likely)" codeBlock: | nps_score = q_nps.outcome if nps_score <= 6: follow_up_needed = 1 input: control: Slider min: 0 max: 10 labels: 0: "Not likely" 5: "Maybe" 10: "Very likely"
- id: q_reason kind: Question title: "What is the primary reason for your score?" precondition: - predicate: follow_up_needed == 1 input: control: Dropdown labels: 1: "Product quality" 2: "Customer service" 3: "Pricing" 4: "Other"
- id: q_aspects kind: QuestionGroup title: "Please rate these aspects:" questions: - "Product quality" - "Customer service" - "Value for money" input: control: Radio labels: 1: "Poor" 2: "Fair" 3: "Good" 4: "Excellent"
- id: b_closing title: "Thank You" items: - id: q_comments kind: Comment title: "Thank you for your valuable feedback!"