这篇怎么用

你在界面应用的 Build() 里返回的每一个控件,都能在这里查到完整签名、参数含义和最简示例。所有控件都可以在末尾链式 .Styled(...) 覆盖外观(见《界面应用进阶》的「自定义样式」)。

下面按类别列出每个组件的完整签名和最简示例。所有组件都可以在末尾链式 .Styled(...) 覆盖外观(见后文「自定义样式」)。

布局

Column(params View[] children)        // 纵向排列
Column(int gap, params View[] children)
Row(params View[] children)           // 横向排列
Row(int gap, params View[] children)
Grid(int columns, params View[] children)   // 2~6 列等宽网格
Card(params View[] children)          // 带边框与背景的分组卡片
Divider()                             // 一条分隔线
Spacer(int size)                      // 固定高度的留白
return Column(16,
    Card(
        Row(12,
            Avatar("码"),
            Column(Text("码巢用户"), Muted("今天已签到"))
        )
    ),
    Divider(),
    Grid(2,
        Card(Text("左")),
        Card(Text("右"))
    ),
    Spacer(24)
);

Grid 的列数会做上下限裁剪(小于 2 按 2、大于 6 按 6),不必自己判断。

文本

Text(string value)                    // 正文
Text(string value, TextKind kind)     // TextKind.Normal / Muted / Bold 等
Title(string value)                   // 页面大标题
Subtitle(string value)                // 次级标题
Muted(string value)                   // 灰色弱化文字
Bold(string value)                    // 加粗正文
return Column(
    Title("学习计划"),
    Muted("每天 10 分钟"),
    Text("今天:变量与类型"),
    Bold("坚持第 7 天")
);

按钮与交互

Button(string label, Action onClick)          // 普通按钮
PrimaryButton(string label, Action onClick)   // 高亮主按钮
Switch(string label, bool value, Action<bool> onChange)
Checkbox(string label, bool value, Action<bool> onChange)
bool notify = false;
int count = 0;

return Column(
    Text("已点击 " + count + " 次"),
    PrimaryButton("点我", () => count++),
    Switch("每日提醒", notify, value => notify = value)
);

回调里改的字段,会在下一次 Build() 时反映到界面。

输入

Field(string value, Action<string> onChange)
Field(string value, string placeholder, Action<string> onChange)
MultilineField(string value, string placeholder, Action<string> onChange)
string name = "";
string note = "";

return Column(
    Field(name, "请输入姓名", value => name = value),
    MultilineField(note, "备注(可多行)", value => note = value),
    Muted("你好," + (name == "" ? "陌生人" : name))
);

输入框在回车或失焦时回调,不是每敲一个字都回调。

选择类

RadioGroup(string[] options, int selected, Action<int> onChange)   // 单选,回调下标
Segmented(string[] options, int selected, Action<int> onChange)    // 分段切换,回调下标
Slider(double value, double min, double max, Action<double> onChange)
Slider(double value, double min, double max)                        // 只读展示
Rating(int value, Action<int> onChange)                             // 1~5 星
Rating(int value)                                                   // 只读展示
var plans = new[] { "按月", "按年" };
int plan = 0;
double volume = 60;
int stars = 4;

return Column(
    Segmented(plans, plan, value => plan = value),
    Text("已选:" + plans[plan]),
    Slider(volume, 0, 100, value => volume = value),
    Muted("音量 " + (int)volume),
    Rating(stars, value => stars = value)
);

展示类

Image(string src)                        // 支持 http(s) 与 data: 地址
Image(string src, string caption)
Video(string src)
Video(string src, bool autoplay, bool loop)
Avatar(string text)                      // 显示首字
Avatar(string text, string src)          // 有图片地址时显示图片
Icon(string glyph, double size)
Link(string label, string url)           // 用系统浏览器打开
Code(string value)                       // 等宽代码块
Note(string value)                       // 提示条
Note(string value, string tone)          // tone 可为 info / ok / warn
Badge(string label)
Badge(string label, string tone)         // tone 可为 info / ok / warn
Progress(double value)                   // 0~100,越界自动截断
Spinner()                                // 转圈
Loading(string label)                    // 转圈 + 文字
ListItem(string title, string subtitle)
ListItem(string title, string subtitle, string trailing)
return Column(
    Image("https://pan.qzyun.net/f/Y19ZTR/1.mp4", "网络视频需要联网"),
    Code("int x = 1;"),
    Note("记得先保存再运行", "warn"),
    Row(ListItem("设置", "账号与偏好", "›")),
    Loading("正在加载")
);

离线显示图片:把图片转成 data: 地址,例如 Image("data:image/svg+xml;utf8,<svg ...></svg>")。 Video 的地址是网络文件,播放需要联网。

首页之外还要有第二、第三个页面时,用 Nav。它是一个页面栈:

Button("查看详情", () => Nav.Push("详情页", () => Column(
    Subtitle("详情"),
    Text("当前计数:" + count),
    Button("在这里加一", () => count++)
)));

要点:

  • Nav.Push("标题", 页面工厂) 压入新页面,顶部自动出现返回按钮,点击即返回上一页。
  • 第二个参数是工厂(() => Column(...)),每次渲染都会重新调用,所以页面里读到的字段永远是最新值。
  • Nav.Pop() 返回上一页;Nav.Replace("标题", 工厂) 替换当前页;Nav.Reset() 回到首页。
  • Nav.Depth 是当前页数,Nav.Title 是当前标题,需要时可以读。

本地存储

Store 让数据在关掉应用后仍然存在:

int total = Store.GetInt("total", 0);   // 读,第二个参数是默认值

void CheckIn()
{
    total++;
    Store.SetInt("total", total);       // 写
}

可用的方法:

  • 字符串:Get(key, 默认值) / Set(key, 值)
  • 数字:GetInt / SetInt
  • 布尔:GetBool / SetBool
  • 其它:Has(key)、Remove(key)、Keys、Clear()

要点:

  • 只在需要时写:Set 的值会在每次运行结束后由应用保存下来,下次运行这个项目时自动回填,读到 defaultValue 就说明还没存过。
  • 按项目隔离:每个项目有自己的一份存储,换项目互不影响。
  • 数据在本机:不上传、不同步,删除项目会一并清掉。
  • 初始值在字段初始化时读:像 int total = Store.GetInt("total", 0); 这样写在字段上最直观。

表单类控件

单选、分段、滑块、评分这些控件,回调拿到的就是「新的下标」或「新的数值」,直接把字段改掉即可:

double volume = 60;
int plan = 0;
int stars = 3;
string[] plans = { "基础版", "标准版", "专业版" };

return Column(
    Text("音量:" + (int)volume),
    Slider(volume, 0, 100, value => volume = value),

    RadioGroup(plans, plan, value => plan = value),
    Segmented(plans, plan, value => plan = value),
    Rating(stars, value => stars = value)
);
  • RadioGroup / Segmented 的回调参数是被选中项的下标(从 0 开始)。
  • Slider 回调是小数,显示时可用 (int) 转成整数。
  • Rating 默认 1 到 5 星,回调是整数。

图片、视频与图标

Image("data:image/svg+xml;utf8,<svg ...></svg>", "内嵌图片不怕离线"),
Video("https://pan.qzyun.net/f/Y19ZTR/1.mp4"),
Avatar("码"),
Icon("⭐", 22),
  • Image 的地址可以是 https:// 网址,也可以是 data: 内嵌数据。想要离线也能显示,就把图片转成 data: 地址。
  • Video 带播放控件;若要自动播放,浏览器通常要求静音,可写 Video("地址", true, true)。
  • Avatar 传入文字时显示首字,传入图片地址时显示图片。
  • Icon 用 emoji 或符号充当图标,第二个参数是字号。