卡片

這頁是對英文翻譯過來的。若兩篇無仝，以英文頁為準。看英文頁

一張卡片是一串簡短的元素，由 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.
}