组件美化使用指导
不可见工具组件：给组件添加圆角、边框、渐变背景、卡片阴影、字体和行距字距，也可注册、取消点击事件；按钮等组件原有的点击事件仍会触发。
卡片样式在设计器属性里设一次，所有卡片统一；背景色、圆角、边框先后设置互不覆盖；颜色参数传列表（一个颜色为纯色，两个以上为渐变）。
另外还能给标签、图像、布局等原本没有点击事件的组件加上点击事件（注册点击（组件）（SetClickable）），
以及把组件背景设为透明（设置背景透明（组件，是否透明）（SetTransparent））。
快速上手
界面：拖入 垂直布局1，在里面放 标签1 和 按钮1；再拖一个组件美化（默认名 组件美化1）。
代码块：屏幕打开时把布局变成白底圆角卡片、按钮换成蓝色渐变圆角，并让标签可以点击。卡片样式用组件美化的「卡片」属性（默认白底、圆角 14），在设计器里改一次，所有卡片一起变。
各案例独立使用；组合到同一屏幕时，将同名事件的处理合并到一个事件积木中。
when Screen1.Initialize() {
组件美化1.SetAsCard(垂直布局1)
组件美化1.SetBgColor(按钮1, list(&HFF42A5F5, &HFF1E88E5), 0)
组件美化1.SetRoundCorner(按钮1, 24)
组件美化1.SetClickable(标签1)
}
when 组件美化1.ComponentClicked(组件) {
if 组件 == 标签1 {
标签1.Text = "点了标签"
}
}
运行效果：布局变成带阴影的白色圆角卡片，按钮是左浅右深的蓝色渐变圆角按钮；点标签，标签文字变成「点了标签」。
要点：
- 卡片样式（布局）（
SetAsCard）只传布局；背景色、圆角、边框、内边距、外边距、阴影都取组件美化的卡片属性，长度单位都是 dp。个别卡片要不一样，之后再单独设圆角、内边距。 - 背景色、圆角、边框先后顺序无关：先设圆角再设背景色，圆角不会丢。
- 设置背景色（组件，颜色列表，渐变方向）（
SetBgColor）的颜色列表只放一个颜色就是纯色；最后一个参数是渐变方向（0 左到右、6 上到下）。 - 多个组件都要点击时，都用注册点击（组件）（
SetClickable）注册，在同一个点击事件里用「组件 = 某组件」区分。
搭建与测试
在设计器拖入本组件和案例涉及的按钮、标签、布局等组件，按案例中的名称重命名。先运行最小案例，确认事件返回，再增加业务逻辑。示例中的素材先上传到项目，服务器地址、令牌、文件路径换成自己的值。
可见组件需要有非零宽高；不可见工具组件必须由属性或方法启动。设计器展示样式不等于运行时已加载数据或绑定目标。联机测试应使用包含本组件的 AI 伴侣；涉及系统入口或权限的行为还要编译安装后验证。
案例：文字排版与取消点击
再放两个按钮，分别用于设置文字排版和取消标签的额外点击处理。
when 按钮_排版.Click() {
组件美化1.SetPadding(标签1, 12)
组件美化1.SetLineSpace(标签1, 6)
组件美化1.SetLetterSpace(标签1, 0.05)
}
when 按钮_取消点击.Click() {
组件美化1.RemoveClickable(标签1)
}
美化改变的是已有组件的视图。点击事件用事件参数里的组件区分是哪一个；背景色、圆角、边框按组件记录，先后设置互不覆盖。
案例：图片卡片、透明切换与按钮点击
先在设计器里上传一张背景图素材 card.png，拖入 垂直布局1（里面放 标签1）、复选框1（文字「透明」）、按钮1，再拖一个组件美化。
when Screen1.Initialize() {
// 代码里改卡片属性，之后调用的「卡片样式」都按新值
组件美化1.CardRadius = 8
组件美化1.CardPadding = 10
组件美化1.SetAsCard(垂直布局1)
// 背景图只传图片；圆角、边框另外设，先后顺序无关
组件美化1.SetBackgroundImage(垂直布局1, "card.png")
组件美化1.SetRoundCorner(垂直布局1, 16)
组件美化1.SetBorder(垂直布局1, 2, &HFFFFFFFF)
组件美化1.SetClickable(按钮1)
}
when 复选框1.Changed() {
组件美化1.SetTransparent(垂直布局1, 复选框1.Checked)
}
when 按钮1.Click() {
标签1.Text = "按钮自己的被点击照常触发"
}
when 组件美化1.ComponentClicked(组件) {
if 组件 == 按钮1 {
复选框1.Text = "组件被点击也触发了"
}
}
运行效果：
- 布局显示
card.png铺满的背景，四角是 16dp 圆角，外面一圈 2dp 白色边框；内边距 10dp 来自刚改的卡片属性； - 勾选「透明」，背景图消失、透出屏幕背景，圆角边框还在；取消勾选，背景图原样回来（不是变成白色）；
- 点按钮，标签显示「按钮自己的被点击照常触发」，复选框文字变成「组件被点击也触发了」——注册点击不会吞掉按钮原来的点击。
属性、方法与事件速查
完整参数类型、默认值和平台说明见组件参考。下表按调用入口列出用途；有完成事件的方法在事件中读取结果。
| 入口 | 用途 |
|---|---|
取消点击注册（组件）（RemoveClickable） |
取消组件的点击注册。按钮等本来有点击事件的组件恢复原来的点击，其它组件恢复为不可点击。 |
卡片背景色、卡片圆角、卡片边框宽度、卡片边框颜色、卡片内边距、卡片外边距、卡片阴影（CardColor 等七个属性） |
卡片样式用的样式，设计器里设一次；默认白底、圆角 14、无边框、内边距 14、外边距 10、阴影 2。 |
卡片样式（布局）（SetAsCard） |
把布局容器设置成卡片：背景色、圆角、边框、内边距、外边距、阴影都用组件美化的卡片属性。 |
设置背景图片（组件，图片地址）（SetBackgroundImage） |
设置组件背景图片，图片拉伸铺满组件。圆角、边框用 SetRoundCorner、SetBorder 设置，对图片同样生效，和先后顺序无关；之后再 SetBgColor 会用颜色取代图片。 |
设置背景色（组件，颜色列表，渐变方向）（SetBgColor） |
设置组件背景色或渐变背景。colors 传颜色列表：单个颜色为纯色，两个及以上为渐变（从列表第一种渐变到最后一种）。orientation 为渐变方向 0-7：0 左到右、1 左下到右上、2 下到上、3 右下到左上、4 右到左、5 右上到左下、6 上到下、7 左上到右下。已设置的圆角和边框保留。 |
设置边框（组件，边框宽度，边框颜色）（SetBorder） |
设置组件边框。borderWidth 为边框宽度 dp（0 去掉边框），borderColor 为边框颜色。已有的背景色、渐变和圆角保留，和其它设置的先后顺序无关。 |
注册点击（组件）（SetClickable） |
为任意组件注册点击事件。标签、图片、布局等原本没有点击事件的组件，注册后点击时会触发 ComponentClicked 事件，事件参数就是被点击的组件本身。按钮等本来有点击事件的组件，原来的被点击事件照常触发。 |
设置阴影（组件，阴影高度）（SetElevation） |
设置组件阴影高度，单位 dp（需 Android 5.0 及以上）。 |
设置字体（组件，字体名称）（SetFont） |
设置文本组件字体。fontName 以 // 开头表示素材字体（如 //font.ttf），否则按本地文件路径处理。只能用于标签、按钮、文本输入框等文本类组件。 |
设置字间距（组件，间距）（SetLetterSpace） |
设置文本组件字间距，0 为默认值（需 Android 5.0 及以上）。 |
设置行间距（组件，间距）（SetLineSpace） |
设置文本组件的行间距增量，单位为像素。 |
设置外边距（组件，外边距）（SetMargin） |
设置组件外边距，四边同样大小，单位 dp。要求组件所在父布局支持外边距（AI2 的布局容器均支持）。 |
设置内边距（组件，内边距）（SetPadding） |
设置组件内边距，四边同样大小，单位 dp。 |
设置圆角（组件，半径）（SetRoundCorner） |
设置组件圆角，四个角同样大小。radius 为圆角半径，单位 dp。已有的背景色、渐变和边框保留，和其它设置的先后顺序无关。 |
设置背景透明（组件，是否透明）（SetTransparent） |
设置组件背景是否透明。为真时透明（圆角、边框保留）；为假时恢复设成透明之前的背景，包括布局的背景图片。 |
组件被点击（组件）（ComponentClicked） |
点击 SetClickable 注册过的组件时触发。component 为被点击的组件本身。 |
常见问题与验收
| 检查项 | 操作与预期 |
|---|---|
| 初始化 | 对照案例检查是否已经调用加载、注册、连接或显示方法；仅拖入组件不会替你执行这些步骤。 |
| 结果返回 | 将成功事件和失败事件都接到标签，记录事件参数；异步操作完成前不读取结果属性。 |
| 输入配置 | 检查素材名大小写、网址是否为直接资源地址、文件是否存在。 |
| 平台与权限 | 按组件参考中的平台说明测试；授权被拒绝时应有明确提示，不继续假定操作成功。 |
| 最小案例 | 先验证页面中的最小案例，再验证第二个场景；重复操作、取消、返回屏幕后结果应符合事件说明。 |
完整 .aia 源码与操作指导
一个可填写、保存、更换主题并点击查看详情的设备信息卡。主界面是设备信息表单和主题选择，字体、间距、阴影和点击注册等细节收在“外观细节与点击设置”里；不把接口按钮当应用主界面。
我的设备信息卡
导入方法：项目 → 导入项目（.aia）→ 选择下载的 .aia 源码文件。 填写设备名称、状态和手动记录温度，保存后显示在设备卡片；重新打开恢复内容，点击卡片看详情，主题可选择白色、渐变或素材背景。外观细节与点击设置默认收起。 覆盖检查 36/36，正式编辑器首次载入和保存重开均零错误，后台导入、安卓安装包与鸿蒙 HAP 编译通过。真机／伴侣尚未实测。
先运行这个实际案例
- 修改设备名称、状态和手动记录温度，点击“保存设备信息”，上方卡片立即显示真实填写内容。
- 点击卡片查看详情；重新打开后核对本地保存的信息。
- 用“更换卡片主题”选择白色、渐变或素材背景，再打开高级设置调整细节。
- 温度是手动记录，不是传感器读数；信息只保存在本案例独立TinyDB。
高级面板默认收起，原完整功能入口仍可打开使用。源码为中文app.json和Screen1.ai-blocks，AIA包含全部素材和完整积木。正式编辑器、后台导入及安装包检查以更新后的最终归档报告为准；真机／伴侣尚未实测。
| API / 功能 | 操作入口 | 预期结果 |
|---|---|---|
| SetAsCard | 启动／恢复 | 按设计器卡片属性（圆角16、边框1、内边距12、外边距6、无阴影）设置卡片，文字字体与间距保留 |
| CardColor、CardRadius、CardBorderWidth、CardBorderColor、CardPadding、CardMargin、CardElevation | 设计器配置；高级面板“切换紧凑／宽松卡片属性” | 七个属性在代码里写入后再 SetAsCard，状态栏读回七个值；紧凑为圆角8、蓝色边框2、内边距6、外边距2、阴影4 |
| SetBgColor、SetRoundCorner、SetBorder、SetPadding、SetMargin、SetElevation | 各自按钮、阴影再次切换 | 观察真实卡片变化；无对应读取API，不虚构已读回数值 |
| SetBackgroundImage、SetFont | 图片／字体 | 真实已打包PNG铺满卡片并沿用卡片圆角与边框；TTF字体；缺图显示实际错误，原配置保留 |
| SetLetterSpace、SetLineSpace | 字距／行距分别再次切换 | 多行英文和数字观察字号不变时的间距变化；中文回退系统字体 |
| SetTransparent | 透明开关 | 打开：透出页面背景，圆角与边框保留；关闭：恢复透明之前的背景（颜色、渐变或图片） |
| SetClickable、RemoveClickable、ComponentClicked | 注册→点卡片→取消→再点→重注册 | 事件参数是被点的组件，显示“点的是卡片：真”与次数；取消后次数不增加 |
| 错误与素材 | 缺图入口 | 真实缺图方法错误显示在底部，原卡片配置保留 |
所有返回值均用于界面反馈，错误由底部错误区展示。设计器采用明确非默认配置，初始化与界面同步。API 覆盖检查按最终 AIA 检查方法、事件、属性读取与设置及设计器配置，不能替代真实设备验证。
扫码添加客服咨询
