BasicRoot 基础根容器

最近更新时间:2025-12-30 17:25:52

我的收藏

组件功能

BasicRoot(基础根容器) 是 Widget 结构中的最外层容器组件,用于承载并组织整个 Widget 的内容结构。
该组件主要负责全局主题控制与基础布局能力,不承担具体业务展示或交互逻辑。

基础用法

BasicRoot 通常作为 Widget JSON 的根节点使用,用于定义整体布局方向与主题模式。
Template 示例:
<Basic theme="light" direction="col" gap="16px">
<Title value="应用标题" />
<Text value="这是应用的主要内容" />
</Basic>
效果展示如下:




属性说明

属性名
类型
描述
默认值
children
ChatKitComponent[]
子组件列表
-
theme
"light" | "dark"
主题模式
"light"
direction
"row" | "col"
布局方向
"col"
gap
number | string
子元素间距
-
padding
number | string | Spacing
内边距
-
align
Alignment
交叉轴对齐方式
-
justify
Justification
主轴对齐方式
-
注意:
★ 标记为必填属性。

类型定义

Alignment
用于控制子组件在交叉轴方向上的对齐规则,交叉轴方向由 direction 决定:
当 direction = "row" 时,交叉轴为纵向。
当 direction = "col" 时,交叉轴为横向。
可选值如下:
"start" | "center" | "end" | "baseline" | "stretch"
可选值说明如下:
"start":子组件在交叉轴起始位置对齐。
"center":子组件在交叉轴居中对齐。
"end":子组件在交叉轴结束位置对齐。
"baseline":子组件按文本基线对齐,常用于包含文本的横向布局。
"stretch":子组件在交叉轴方向拉伸,占满可用空间。
Justification
用于控制子组件在主轴方向上的分布和对齐方式,主轴方向由 direction 决定:
当 direction = "row" 时,主轴为横向。
当 direction = "col" 时,主轴为纵向。
可选值如下:
"start" | "end" | "center" | "between" | "around" | "evenly"
可选值说明如下:
"start":子组件从主轴起始位置依次排列。
"end":子组件向主轴末端对齐。
"center":子组件整体在主轴方向居中。
"between":首尾贴边,其余子组件等间距分布。
"around":子组件两侧留有等量空间。
"evenly":子组件及两侧空隙完全等分。
Spacing
用于描述内边距(padding)或间距类属性的配置方式。
支持以下三种形式:
number | string | { x?: number; y?: number; top?: number; right?: number; bottom?: number; left?: number }

使用场景

BasicRoot 通常用于以下场景:
1. 顶层容器: 作为 Widget 配置的最外层节点,承载全部子组件。
2. 主题控制:为整个 Widget 指定浅色或深色主题,确保视觉风格一致。
3. 基础布局:提供最基础的纵向或横向布局能力,作为其他容器组件的布局基础。

与 Card 的区别

BasicRoot 更侧重于结构与布局,而 Card 更偏向于内容承载与视觉呈现。
特性
BasicRoot
Card
背景
透明
有背景色
边框
不支持
支持
阴影
不支持
支持
状态显示
不支持
支持
表单模式
不支持
支持

使用示例

以下示例展示了使用 BasicRoot 作为根容器,在其内部组合多个 Card 组件的典型场景。
JSON 格式:
{
"type": "Basic",
"theme": "light",
"direction": "col",
"gap": "24px",
"padding": "20px",
"children": [
{
"type": "Card",
"children": [
{ "type": "Title", "value": "卡片 1" }
]
},
{
"type": "Card",
"children": [
{ "type": "Title", "value": "卡片 2" }
]
}
]
}
效果展示如下: