Thẻ

Trang này được dịch từ tiếng Anh. Nếu hai bản khác nhau, trang tiếng Anh là bản đúng. Đọc trang tiếng Anh

Thẻ là một danh sách ngắn các phần tử mà Lingara vẽ theo phong cách riêng của mình. Không có ô nhập liệu, hình ảnh, script hay markup. Ứng dụng không thể đưa mã riêng hay giao diện riêng của nó lên màn hình của người học, nên mọi thẻ đều trông giống phần còn lại của Lingara. Phản hồi của bạn là JSON: một card chứa các elements của nó, và tùy chọn một tutor_note (xem Ghi chú cho gia sư).

Các phần tử

Mỗi phần tử có một type, là một trong tám loại sau:

Một lang là mã ngôn ngữ như ja, để Lingara vẽ đúng hệ chữ. Giá trị không phải mã ngôn ngữ sẽ bị xóa.

Các giới hạn

• Một thẻ chứa tối đa 24 phần tử. Các phần tử sau phần tử thứ 24 bị loại bỏ.
• Một danh sách chứa tối đa 20 mục. Các mục sau mục thứ 20 bị loại bỏ, và danh sách rỗng cũng bị loại bỏ.
• Một thẻ chứa tối đa 4 nút. Các nút sau nút thứ 4 bị loại bỏ.
• Văn bản dài hơn giới hạn của nó sẽ bị cắt cho vừa và kết thúc bằng …. Ký tự được đếm theo giá trị vô hướng Unicode (Unicode scalar value).
• Ký tự điều khiển và ký tự ghi đè hướng bị xóa khỏi mọi chuỗi.
• Liên kết có địa chỉ không phải HTTPS, chứa tên người dùng, hoặc trỏ đến một địa chỉ IP sẽ bị loại bỏ.
• Nút có action dài hơn 64 ký tự, hoặc dùng bất kỳ thứ gì ngoài chữ cái, chữ số, _, ., : và -, sẽ bị loại bỏ.
• Phần tử không còn văn bản nào sau các quy tắc này sẽ bị loại bỏ.

Các quy tắc này khoan dung: Lingara cắt bớt hoặc loại bỏ những gì không vừa và vẽ phần còn lại. Các bộ công cụ áp dụng cùng những quy tắc này trước khi bạn trả lời, để bạn thấy được điều gì sẽ thay đổi.

Phân tích cú pháp nghiêm ngặt

Bộ từ vựng là đóng. Một loại phần tử không xác định, một trường mà phần tử không có, một giá trị sai kiểu JSON, hoặc một phản hồi hoàn toàn không phải JSON sẽ biến toàn bộ phản hồi thành thẻ dự phòng. Lingara không bao giờ vẽ một phần của thẻ mà nó không đọc được.

Kích thước và thời gian

Phản hồi dài tối đa 32 KiB. Lingara cho máy chủ của bạn 3 giây để trả lời một yêu cầu render và 5 giây để trả lời một hành động, và không thử lại cái nào. Phản hồi phải có trạng thái 200 và kiểu nội dung JSON. Chuyển hướng không được đi theo.

Nút và hành động

Khi người học nhấn một nút, Lingara gửi đến máy chủ của bạn một yêu cầu hành động mang action của nút đó. Máy chủ của bạn trả lời bằng một thẻ mới, thay thế thẻ cũ. Cùng một lần nhấn có thể đến hai lần, vì vậy hãy làm cho mỗi hành động an toàn khi lặp lại.

Khi thẻ gặp lỗi

Khi Lingara không lấy được một thẻ mà nó có thể vẽ, người học sẽ thấy thẻ “Ứng dụng này không trả lời” của chính Lingara bằng ngôn ngữ của họ, hoặc thẻ hợp lệ gần nhất của bạn được đánh dấu “Chưa cập nhật”. Người học không bao giờ được cho biết lý do. Chỉ bạn, với tư cách chủ sở hữu ứng dụng, mới thấy lý do:

• Phản hồi của bạn: invalid (không phải thẻ mà Lingara đọc được), empty (không còn gì để hiển thị sau các giới hạn) hoặc too_large (lớn hơn 32 KiB).
• Kết nối đến máy chủ của bạn: timeout, http_error (bất kỳ trạng thái nào khác 200), transport (lỗi kết nối hoặc TLS, chẳng hạn như chứng chỉ hết hạn) hoặc blocked (một render_url dẫn đến địa chỉ riêng tư hoặc địa chỉ IP dạng literal).
• Phía Lingara: unavailable (Lingara không thể ký yêu cầu) hoặc busy (đã có quá nhiều yêu cầu đang được xử lý).

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