کارت‌ها

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

کارت فهرست کوتاهی از عناصر است که 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.
}