流式布局 API 用法参考

流式扩展与对象初始化器配置同一套属性，可以按需要混用；链式调用不改变布局规则。基础用法和尺寸/溢出排错见流式布局教程，具体签名以 SDK 的 api/client/ 声明为准。

API架构

核心扩展类

csharp

// 布局相关的流式API
public static class LayoutExtensions
// 控件构建相关的流式API  
public static class BuilderExtensions
// 静态UI构建器
public static class UI

API详细说明

1. 尺寸设置 (Size)

csharp

// 设置宽高
control.Size(200, 100)
control.Square(150)  // 正方形
control.Width(200)
control.Height(100)

// 自动尺寸
control.AutoWidth()
control.AutoHeight()
control.AutoSize()

2. 位置设置 (Position)

csharp

// 相对父容器左上角的绝对定位
control.AbsolutePosition(100, 50)

// 相对正常排版位置的偏移
control.RelativeOffset(10, 20)

// Position(...) 只设置坐标并保留当前 PositionType。
// 除非前面已经显式调用 Absolute()/Relative()，否则优先使用上面两个语义明确的方法。

3. 对齐方式 (Alignment)

csharp

// 基础对齐
control.AlignLeft()
control.AlignRight()
control.AlignTop()
control.AlignMiddle()
control.AlignBottom()
control.Center()

// 拉伸对齐
control.StretchHorizontal()
control.StretchVertical()
control.Stretch()

// 居中对齐
control.Center()

4. 边距设置 (Margin & Padding)

csharp

// 统一边距
control.Margin(10)
control.Padding(15)

// 水平/垂直边距
control.Margin(20, 10)  // 水平20，垂直10
control.Padding(15, 5)

// 四个方向边距
control.Margin(10, 5, 10, 5)  // 左、上、右、下

5. 流式布局 (Flex Layout)

csharp

// 流式布局方向
control.FlowHorizontal()
control.FlowVertical()

// 子元素对齐
control.ContentAlignHorizontal(HorizontalContentAlignment.Left)
control.ContentAlignVertical(VerticalContentAlignment.Top)
control.ContentCenter()

// 内容对齐 - Flexbox风格（基于FlowOrientation智能选择轴向）
control.JustifySpaceBetween()     // 主轴均匀分布（space-between）
control.JustifySpaceAround()      // 主轴均匀分布（space-around）
control.AlignSpaceBetween()       // 交叉轴均匀分布（space-between）
control.AlignSpaceAround()        // 交叉轴均匀分布（space-around）
control.JustifyStretch()          // 主轴方向拉伸填充
control.AlignStretch()            // 交叉轴方向拉伸填充

// 显式轴向控制
control.JustifyHorizontalSpaceBetween()  // 明确控制水平分布
control.JustifyVerticalSpaceBetween()    // 明确控制垂直分布

// 组合方法
control.HorizontalSpread()        // 水平均匀分布容器
control.VerticalSpread()          // 垂直均匀分布容器

// Flexbox API - CSS标准命名
control.WidthGrow(1.0f)         // 宽度增长比例
control.HeightGrow(0.5f)        // 高度增长比例
control.GrowRatio(1, 2)         // 设置宽高增长比例

control.WidthShrink(0.5f)       // 宽度收缩比例
control.HeightShrink(0.3f)      // 高度收缩比例
control.ShrinkRatio(0.5, 0.5)   // 设置宽高收缩比例

control.FlexBasis(100, 50)      // Flex基础尺寸
control.FlexBasisWidth(100)     // 宽度基础尺寸
control.FlexBasisHeight(50)     // 高度基础尺寸

6. 复合布局方法

csharp

// 快速堆叠布局
control.VStack(spacing: 10)  // 垂直堆叠
control.HStack(spacing: 15)  // 水平堆叠

7. 控件属性设置

csharp

// 基础属性
control.Visible(true)
control.Hidden()
control.Enabled(false)
control.Disabled()
control.DataContext(data)

// 样式属性
control.Background(Color.Blue)
control.Background(brush)
control.Opacity(0.8f)

8. 文本控件专用

csharp

// Label专用方法
label.Text("Hello World")
     .TextColor(Color.Red)
     .FontSize(16)
     .Bold()
     .Italic()

// Button文本方法
button.Text("按钮文本")
      .TextColor(Color.White)
      .FontSize(16)
      .Bold()
      .Italic()

自定义字体

Label.Font、Input.Font、TextButton.Font 传的是字体 family，不是具体 .ttf / .otf 文件路径。项目私有字体放在 res/font/<family>/... 时，代码和 ref/fontref.txt 都从 res/ 下一级开始写。

text

MyProject/
├── ref/fontref.txt
└── res/font/my_title/my_title.ttf

text

font/my_title

csharp

#if CLIENT
var title = UI.Label("标题");
title.Font = "font/my_title"u8;
title.FontSize = 32;
#endif

公共 UI 字体使用 ui/font/<family>，例如 ui/font/Regular。新增字体后必须重启本局或重新进入地图，因为运行时只在地图初始化阶段根据 ref/fontref.txt 预加载 Label / Input 字体 family。

排查字体不生效时，先看 ui-custom-font skill 和自定义字体指南。当前版本需要手写维护 ref/fontref.txt；未来可能会有类似资源收集工具的字体 ref 自动收集工具。

9. 容器管理

csharp

// 子控件管理
container.AddChild(child)
         .AddChildren(child1, child2, child3)
         .AddChildren(childList)

10. 事件处理

csharp

// Button事件
button.OnClick((sender, e) => { /* 处理逻辑 */ })
      .OnClick(() => { /* 简化处理逻辑 */ })

11. 外观样式

csharp

// 圆角设置
control.CornerRadius(8)

// Z轴层级
control.ZIndex(10)

// 透明度
control.Opacity(0.8f)

// 内容裁剪
control.ClipContent()       // 启用裁剪，超出边界的子控件被裁剪
       .ClipContent(true)   // 显式启用裁剪
       .NoClip()            // 禁用裁剪，允许子控件超出边界显示

// 尺寸限制（预留接口）
control.MinWidth(100)
       .MaxWidth(300)
       .MinHeight(50)
       .MaxHeight(200)

12. 响应式设计

csharp

// 响应式尺寸 - 基于断点系统自动调整
control.ResponsiveWidth(100, 300)      // 最小100px，最大300px
       .ResponsiveHeight(50, 150)      // 最小50px，最大150px
       .ResponsiveSize(100, 300, 50, 150) // 同时设置宽高

// 响应式字体 - 根据屏幕尺寸调整
label.ResponsiveFontSize(12, 24, 1.2f)  // 最小12px，最大24px，倍数1.2

// 响应式间距 - 自适应屏幕尺寸
control.ResponsiveSpacing(8, 24)        // 最小8px，最大24px间距
       .ResponsivePadding(12, 32)       // 最小12px，最大32px内边距

// 响应式容器 - 预设容器尺寸
control.ResponsiveContainer(ResponsiveContainerSize.Standard)  // 标准容器
       .ResponsiveContainer(ResponsiveContainerSize.Compact)   // 紧凑容器

// 响应式按钮尺寸
button.ResponsiveButton(ResponsiveButtonSize.Medium)

// 响应式布局方向 - 根据屏幕方向自动切换
container.ResponsiveOrientation(
    Orientation.Horizontal,  // 横屏时水平布局
    Orientation.Vertical     // 竖屏时垂直布局
)

// 响应式可见性 - 基于断点控制显示/隐藏
control.ResponsiveVisibility(ResponsiveVisibility.MediumAndUp) // 中等屏幕及以上显示
       .ResponsiveVisibility(ResponsiveVisibility.SmallOnly)   // 仅小屏幕显示

13. 高级布局容器

csharp

// 真正的网格布局 - 支持多列布局
var grid = TrueGrid(3,              // 3列
    rowSpacing: 8,                  // 行间距
    columnSpacing: 12,              // 列间距
    child1, child2, child3,         // 子元素自动分配到网格
    child4, child5, child6
);

// 简单网格布局 - 自动计算列数
var autoGrid = SimpleGrid(10,       // 统一间距10px
    item1, item2, item3, item4, item5  // 自动计算最佳列数
);

// 卡片容器样式
control.Card(padding: 20, radius: 8, elevation: 2)  // 创建卡片样式

// 语义化组件
button.Button(height: 44, padding: 16, radius: 4)   // 按钮样式
input.Input(height: 40, width: 280, padding: 12)    // 输入框样式
item.ListItem(height: 48, padding: 16)              // 列表项样式

// 文本样式组件
label.Title(fontSize: 24, margin: 16)               // 标题样式
label.Subtitle(fontSize: 18, margin: 12)            // 副标题样式
label.Body(fontSize: 16, margin: 8)                 // 正文样式
label.Caption(fontSize: 12, margin: 4)              // 说明文字样式

14. 预定义控件样式

csharp

// 预定义文本样式
UI.Title("标题文字", size: 24)      // 标题
UI.Subtitle("副标题文字", fontSize: 18)  // 副标题

// 预定义按钮样式
UI.Primary("主要按钮")     // 主要按钮
UI.Secondary("次要按钮")   // 次要按钮

// 创建带文本的按钮
UI.Button("普通按钮")            // 自动添加Label子控件

静态UI构建器

UI 静态类提供了更简洁的控件创建方式：

csharp

// 创建控件
var page = UI.Page();
var panel = UI.Panel();
var button = UI.Button();
var label = UI.Label("Hello");

// 快速布局容器
var vstack = UI.VStack(spacing: 10,
    UI.Label("标题"),
    UI.Button(),
    UI.Label("底部文字")
);

var hstack = UI.HStack(spacing: 15,
    UI.Button(),
    UI.Label("按钮说明")
);

// 居中容器
var centered = CenterContainer(
    UI.Label("居中的文本")
);

使用示例

简单登录界面

csharp

var loginScreen = Page(
    VStack(20,
        // 标题
        Label("欢迎登录", Colors.Primary)
            .FontSize(32)
            .Bold()
            .Center()
            .Margin(0, 50, 0, 30),

        // 输入区域
        VStack(15,
            Label("用户名输入框")
                .Background(Colors.Surface)
                .Padding(15, 10)
                .StretchHorizontal()
                .Height(40),

            Label("密码输入框")
                .Background(Colors.Surface)
                .Padding(15, 10)
                .StretchHorizontal()
                .Height(40)
        ).Margin(40, 0),
        
        // 按钮区域
        HStack(20,
            Button().Size(120, 40).Background(Colors.Secondary),
            Button().Size(120, 40).Background(Colors.Primary)
        ).Center().Margin(0, 30, 0, 0)
    )
    .FillParent()
)
.Background(Colors.Background);

完整页面或菜单根容器优先用 Page；FillParent() 继续用于页面内部需要占满父容器的布局块。

内容裁剪使用示例

csharp

// 滚动列表容器 - 需要裁剪超出边界的内容
var scrollList = Panel()
    .Size(300, 400)
    .Background(DesignColors.SurfaceContainer)
    .ClipContent()  // 启用裁剪，保持列表边界整洁
    .FlowVertical()
    .Add(
        Label("列表项 1").Height(50).Background(DesignColors.Surface),
        Label("列表项 2").Height(50).Background(DesignColors.Surface),
        Label("列表项 3").Height(50).Background(DesignColors.Surface),
        // ... 更多列表项，超出容器的部分将被裁剪
    );

// 卡片容器 - 保持圆角边界整洁
var card = Panel()
    .Size(250, 150)
    .Background(DesignColors.Surface)
    .CornerRadius(DesignTokens.RadiusM)
    .ClipContent(true)  // 裁剪超出控件边界的内容
    .Padding(DesignTokens.SpacingM)
    .Add(
        Label("卡片标题").Bold(),
        Label("长文本内容会被自动裁剪...")
    );

// 特效容器 - 允许内容溢出显示阴影等效果
var effectContainer = Panel()
    .Size(200, 100)
    .Background(DesignColors.Primary)
    .NoClip()  // 允许子控件超出边界，用于阴影等效果
    .Add(
        Button("悬浮按钮")
            .Size(250, 120)  // 故意超出父容器
            .Center()
            // 可以添加阴影等超出边界的视觉效果
    );

内容对齐使用示例

csharp

// 工具栏 - 水平均匀分布按钮
var toolbar = Panel()
    .Size(400, 50)
    .HorizontalSpread()  // 等同于 .FlowHorizontal().JustifySpaceBetween()
    .Add(
        Button("新建"),
        Button("编辑"),
        Button("删除"),
        Button("设置")
    );

// 侧边栏 - 垂直均匀分布菜单
var sidebar = Panel()
    .Size(200, 300)
    .VerticalSpread()  // 等同于 .FlowVertical().JustifySpaceBetween()
    .Add(
        Button("首页"),
        Button("设置"),
        Button("帮助")
    );

// 卡片网格 - 主轴均匀分布含边距
var cardGrid = Panel()
    .Size(600, 200)
    .FlowHorizontal()    // 主轴为水平
    .JustifySpaceAround()  // 主轴（水平）均匀分布含边距
    .Add(
        Panel().Size(150, 180).Background(DesignColors.Surface),
        Panel().Size(150, 180).Background(DesignColors.Surface),
        Panel().Size(150, 180).Background(DesignColors.Surface)
    );

// 表单布局 - 交叉轴拉伸填充
var form = Panel()
    .Size(300, 200)
    .FlowVertical()    // 主轴为垂直
    .AlignStretch()    // 交叉轴（水平）拉伸，输入框填满宽度
    .Add(
        Input("用户名"),
        Input("密码"),
        Button("登录")
    );

// 导航栏 - 左中右分布
var navbar = Panel()
    .Size(800, 60)
    .FlowHorizontal()
    .JustifySpaceBetween()
    .Add(
        Label("Logo").AlignLeft(),
        HStack(10,
            Button("首页"),
            Button("产品"),
            Button("关于")
        ).Center(),
        Button("登录").AlignRight()
    );

复杂仪表板布局

csharp

var dashboard = Page(
    VStack(0,
        // 顶部导航栏
        HStack(20,
            Title("仪表板").TextColor(Colors.OnPrimary),
            HStack(10,
                CreateNavButton("首页", true),
                CreateNavButton("数据", false),
                CreateNavButton("设置", false)
            ).Flex(1).AlignRight()
        ).StretchHorizontal().Padding(20, 15).Background(Colors.Primary),
        
        // 主要内容区域
        HStack(20,
            // 左侧边栏
            VStack(20,
                CreateInfoCard("在线用户", "1,234"),
                CreateInfoCard("今日收入", "$12,345"),
                CreateInfoCard("活跃服务器", "8/10")
            ).Width(250).Padding(20),

            // 主要内容区
            VStack(20,
                Card(Label("图表区域").Center(), padding: 20).Height(300),
                Card(Label("数据表格").Center(), padding: 20).Flex(1)
            ).Flex(1).Padding(20, 20, 20, 0)
        ).Flex(1)
    )
    .FillParent()
)
.Background(Colors.Background);

完整示例演示

示例按默认设计画布选择桌面字号；单位换算和移动端验收见 UI 字号与可读性。

csharp

var advancedExample = Page(
    VStack(0,
        // 顶部标题区域
        Card(
            VStack(10,
                Title("高级API示例", 40),
                Subtitle("展示完善后的流式布局API功能").FontSize(24)
            ).Center(),
            padding: 30
        ).Margin(20),
        
        // 中间内容区域
        HStack(20,
            // 左侧卡片
            Card(
                VStack(15,
                    Label("用户信息").FontSize(32).Bold(),
                    Divider(),
                    Label("姓名：张三").FontSize(26),
                    Label("邮箱：zhang@example.com").FontSize(26).AutoWidth().StretchHorizontal().AutoHeight().TextWrap(),
                    Spacer(10),
                    Primary("编辑资料").StretchHorizontal()
                ),
                padding: 20
            ).Width(360),

            // 中间分隔线
            Divider(isHorizontal: false, thickness: 2),

            // 右侧卡片
            Card(
                VStack(15,
                    Label("操作面板").FontSize(32).Bold(),
                    Divider(),
                    HStack(10,
                        Primary("保存"),
                        Secondary("取消"),
                        FlexSpacer(),
                        Button("帮助").TextColor(Colors.Primary)
                    ),
                    Spacer(20),
                    Label("状态：已保存").FontSize(22).TextColor(Colors.Success)
                ),
                padding: 20
            ).Flex(1)
        ).Margin(20, 0),

        // 底部状态栏
        HStack(15,
            Label("版本 1.0.0").FontSize(22).TextColor(Colors.Secondary),
            FlexSpacer(),
            Label("在线").FontSize(22).TextColor(Colors.Success)
                .Background(Color.FromArgb(50, 52, 199, 89))
                .Padding(5, 2)
                .CornerRadius(3)
        )
        .Background(Colors.Surface)
        .Padding(15, 10)
    )
    .FillParent()
)
.Background(Colors.Background);

内置颜色预设

csharp

UI.Colors.Primary      // 主色调
UI.Colors.Secondary    // 次要色调
UI.Colors.Success      // 成功状态色
UI.Colors.Warning      // 警告状态色
UI.Colors.Error        // 错误状态色
UI.Colors.Background   // 背景色
UI.Colors.Surface      // 表面色
UI.Colors.OnPrimary    // 主色调上的文字色
UI.Colors.OnSurface    // 表面上的文字色
UI.Colors.OnBackground // 背景上的文字色

流式布局 API 用法参考 ​

API架构 ​

核心扩展类 ​

API详细说明 ​

1. 尺寸设置 (Size) ​

2. 位置设置 (Position) ​

3. 对齐方式 (Alignment) ​

4. 边距设置 (Margin & Padding) ​

5. 流式布局 (Flex Layout) ​

6. 复合布局方法 ​

7. 控件属性设置 ​

8. 文本控件专用 ​

自定义字体 ​

9. 容器管理 ​

10. 事件处理 ​

11. 外观样式 ​

12. 响应式设计 ​

13. 高级布局容器 ​

14. 预定义控件样式 ​

静态UI构建器 ​

使用示例 ​

简单登录界面 ​

内容裁剪使用示例 ​

内容对齐使用示例 ​

复杂仪表板布局 ​

完整示例演示 ​

内置颜色预设 ​

流式布局 API 用法参考

API架构

核心扩展类

API详细说明

1. 尺寸设置 (Size)

2. 位置设置 (Position)

3. 对齐方式 (Alignment)

4. 边距设置 (Margin & Padding)

5. 流式布局 (Flex Layout)

6. 复合布局方法

7. 控件属性设置

8. 文本控件专用

自定义字体

9. 容器管理

10. 事件处理

11. 外观样式

12. 响应式设计

13. 高级布局容器

14. 预定义控件样式

静态UI构建器

使用示例

简单登录界面

内容裁剪使用示例

内容对齐使用示例

复杂仪表板布局

完整示例演示

内置颜色预设