البطاقات

هذه الصفحة مترجمة من الإنجليزية. إذا اختلفت النسختان، فالصفحة الإنجليزية هي الصحيحة. اقرأ الصفحة الإنجليزية

البطاقة قائمة قصيرة من العناصر ترسمها Lingara بأسلوبها الخاص. لا توجد حقول إدخال ولا صور ولا نصوص برمجية ولا وسوم. لا يستطيع التطبيق أن يضع شيفرته الخاصة أو مظهره الخاص على شاشة المتعلّم، لذا تبدو كل بطاقة مثل بقية Lingara. ردّك بصيغة JSON: card يحمل elements الخاصة به، واختياريًا tutor_note (انظر ملاحظة المدرّس).

العناصر

لكل عنصر type، وهو واحد من هذه الثمانية:

العنصر	الحقول	ما يعرضه
`heading`	`text`, `level`	عنوان. قيمة `level` هي 1 أو 2، وأي قيمة أخرى تصبح 2. نصّه 80 حرفًا على الأكثر.
`text`	`text`, `lang`	فقرة من 600 حرف على الأكثر. وهي المكان الوحيد الذي يُحتفظ فيه بفاصل الأسطر.
`term`	`word`, `reading`, `gloss`, `lang`	كلمة للتعلّم. الحقل `word` وحده مطلوب. الكلمة 60 حرفًا على الأكثر، والقراءة 120، والشرح 160.
`list`	`items`	حتى 20 عنصرًا. كل عنصر هو `text` أو `term`، بالحقول نفسها التي للعنصر الذي يحمل هذا الاسم.
`progress`	`value`, `label`	شريط تقدّم. تتراوح `value` من 0 إلى 1، والتسمية 60 حرفًا على الأكثر.
`divider`		خط بين أجزاء البطاقة.
`button`	`label`, `action`, `style`	زر يرسل `action` الخاص به إلى خادمك. قيمة `style` هي `primary` أو `secondary`، والتسمية 32 حرفًا على الأكثر.
`link`	`label`, `url`	رابط يفتحه المتعلّم في متصفحه، بعد أن تسأله Lingara. التسمية 60 حرفًا على الأكثر.

قيمة lang هي وسم لغة مثل ja، كي ترسم Lingara الكتابة الصحيحة. وأي قيمة ليست وسم لغة تُزال.

الحدود

تحمل البطاقة 24 عنصرًا على الأكثر. تُسقَط العناصر التي تلي العنصر الـ 24.
تحمل القائمة 20 بندًا على الأكثر. تُسقَط البنود التي تلي البند الـ 20، وتُسقَط القائمة الفارغة.
تحمل البطاقة 4 أزرار على الأكثر. تُسقَط الأزرار التي تلي الزر الـ 4.
النص الأطول من حدّه يُقصّ ليتّسع وينتهي بـ …. تُعدّ الأحرف بوصفها قيمًا قياسية في Unicode.
تُزال أحرف التحكم وأحرف تجاوز الاتجاه من كل سلسلة نصية.
يُسقَط الرابط الذي لا يكون عنوانه HTTPS، أو يحمل اسم مستخدم، أو يشير إلى عنوان IP.
يُسقَط الزر الذي يزيد طول action الخاص به عن 64 حرفًا، أو يستخدم أي شيء غير الحروف والأرقام و_ و. و: و-.
يُسقَط العنصر الذي لا يبقى فيه نص بعد هذه القواعد.

هذه القواعد متسامحة: تقصّ Lingara أو تُسقط ما لا يتّسع وترسم الباقي. وتطبّق الحِزم القواعد نفسها قبل أن تردّ، كي ترى ما الذي سيتغيّر.

التحليل الصارم

المفردات مغلقة. نوع عنصر غير معروف، أو حقل لا يملكه العنصر، أو قيمة من نوع JSON خاطئ، أو ردّ ليس JSON أصلًا، كل ذلك يحوّل الرد بأكمله إلى بطاقة بديلة. لا ترسم Lingara أبدًا جزءًا من بطاقة لم تستطع قراءتها.

الحجم والوقت

يمكن أن يبلغ الرد 32 KiB على الأكثر. تمنح Lingara خادمك 3 ثوانٍ للإجابة عن طلب عرض و5 ثوانٍ للإجابة عن إجراء، ولا تعيد المحاولة في أيٍّ منهما. يجب أن يحمل الرد الحالة 200 ونوع محتوى JSON. لا تُتَّبع عمليات إعادة التوجيه.

الأزرار والإجراءات

عندما يضغط المتعلّم زرًا، ترسل Lingara إلى خادمك طلب إجراء يحمل action الخاص بذلك الزر. يجيب خادمك ببطاقة جديدة تحلّ محل القديمة. قد تصل الضغطة نفسها مرتين، لذا اجعل كل إجراء آمنًا للتكرار.

عندما تفشل البطاقة

عندما لا تستطيع Lingara الحصول على بطاقة يمكنها رسمها، يرى المتعلّم بطاقة Lingara الخاصة «هذا التطبيق لم يُجب» بلغته، أو آخر بطاقة سليمة لك مع علامة «غير محدَّث». لا يُخبَر المتعلّم أبدًا بالسبب. وحدك، بصفتك مالك التطبيق، ترى السبب:

ردّك: invalid (ليس بطاقة يمكن لـ Lingara قراءتها)، أو empty (لم يبقَ شيء لعرضه بعد الحدود) أو too_large (أكثر من 32 KiB).
الوصول إلى خادمك: timeout، أو http_error (أي حالة غير 200)، أو transport (فشل في الاتصال أو في TLS، مثل شهادة منتهية الصلاحية) أو blocked (قيمة render_url تؤدي إلى عنوان خاص أو عنوان IP حرفي).
جانب Lingara: unavailable (تعذّر على Lingara توقيع الطلب) أو busy (طلبات جارية كثيرة جدًا بالفعل).

TypeScriptRustGoJavaKotlinRubyPHP

TypeScript

function todayCard(streak: number): Card {
  return card()
    .heading("Today's five", 1)
    .term({ word: "雨", reading: "yǔ", gloss: "rain", lang: "zh" })
    .list([item.text("Review 3 words"), item.term({ word: "二", reading: "èr" })])
    .button(`Done (${streak})`, "done")
    .build(); // Throws CardLimitError naming the rule the relay would clamp.
}

Rust

fn today_card(title: &str, lang: &str) -> Result<lingara_apps::Card, BoxError> {
    Ok(card()
        .heading(title, 1)
        .term(Term::new("雨").reading("yǔ").gloss("rain").lang(lang))
        .list([item::text("Say it aloud"), item::term(Term::new("下雨").gloss("to rain"))])
        .button("Next word", "next")
        .build()?)
}

card, err := lingaraapps.NewCard().
	Heading("Today", 1).
	Term(lingaraapps.Term{Word: "雨", Reading: "yǔ", Gloss: "rain", Lang: "zh"}).
	List(
		lingaraapps.Item.Text("Say it aloud three times."),
		lingaraapps.Item.Term(lingaraapps.Term{Word: "雨天", Gloss: "rainy day", Lang: "zh"}),
	).
	Button("Next", "next").
	Build()
if err != nil {
	// A *lingaraapps.CardLimitError names the rule the card breaks,
	// such as text_length or list_items. Nothing is cut for you.
	return lingaraapps.Card{}, err
}

Java

import com.getlingara.apps.Card;
import com.getlingara.apps.Item;

Card card =
    Card.card()
        .heading("Today's five", 1)
        .term("雨", "yǔ", "rain", "zh")
        .list(Item.text("Say it aloud"), Item.term("二", "èr", "two", "zh"))
        .button("Next", "next")
        .build(); // a CardLimitException names the first rule the card breaks

Kotlin

import com.getlingara.apps.kotlin.Card
import com.getlingara.apps.kotlin.card

val c =
    card {
        heading("Today's five", 1)
        term("雨", reading = "yǔ", gloss = "rain", lang = "zh")
        list(item.text("Say it aloud"), item.term("二", reading = "èr", gloss = "two", lang = "zh"))
        button("Next", "next")
    } // a CardLimitException names the first rule the card breaks

Ruby

def self.today_card(streak)
  Lingara::Apps.card
    .heading("Today's five", 1)
    .term(word: "雨", reading: "yǔ", gloss: "rain", lang: "zh")
    .list([Lingara::Apps.item.text("Review 3 words"), Lingara::Apps.item.term(word: "二", reading: "èr")])
    .button("Done (#{streak})", "done")
    .build # Raises Lingara::Apps::CardLimitError naming the rule Lingara would clamp.
end

PHP

use Lingara\Apps\Card;
use Lingara\Apps\Generated\Card as CardModel;
use Lingara\Apps\Item;

function todayCard(int $streak): CardModel
{
    return Card::create()
        ->heading("Today's five", 1)
        ->term('雨', reading: 'yǔ', gloss: 'rain', lang: 'zh')
        ->list([Item::text('Review 3 words'), Item::term('二', reading: 'èr')])
        ->button("Done ({$streak})", 'done')
        ->build(); // Throws CardLimitException naming the rule the relay would clamp.
}