کارت‌ها

این صفحه از انگلیسی ترجمه شده است. اگر این دو با هم تفاوت داشته باشند، صفحهٔ انگلیسی درست است. خواندن صفحهٔ انگلیسی

کارت فهرست کوتاهی از عناصر است که Lingara آن را به سبک خودش ترسیم می‌کند. هیچ فیلد ورودی، تصویر، اسکریپت یا نشانه‌گذاری‌ای در کار نیست. یک برنامه نمی‌تواند کد خودش یا ظاهر خودش را روی صفحهٔ زبان‌آموز بگذارد، بنابراین هر کارت مثل بقیهٔ Lingara خوانده می‌شود. پاسخ شما JSON است: یک card که elements خود را در بر دارد، و به‌طور اختیاری یک tutor_note (نگاه کنید به یادداشت معلم).

عناصر

هر عنصر یک type دارد که یکی از این هشت مورد است:

یک 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 (از قبل درخواست‌های در حال اجرای زیادی وجود دارد).

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.
}

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
}

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

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

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

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.
}