卡片

這頁係對英文翻譯過來个。若係兩片無共樣，以英文頁為準。看英文頁

一張卡片係一串簡短个元素，由 Lingara 用佢自家个風格畫出來。肚項無輸入欄、無圖片、無指令碼，也無標記。App 無法度將自家个程式碼抑係自家个外觀放到學習者个螢幕頂高，所以每張卡片看起來都摎 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 自家用佢兜个語言顯示个「這隻 App 無回應」卡片，抑係你最尾一張正常个卡片，標等「毋係新个」。學習者永遠毋會知原因。淨你，做 App 个主人，看得到原因：

你个回應：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.
}