从零封装一个能在火山里调用的安卓组件

一、先看目标与现状

本教程讲的是火山安卓的界面组件封装，不是 Windows 视窗或 MFC 控件。目标是把常用界面能力整理成独立组件，让普通使用者只需在窗口中声明变量并调用中文方法。

二、五个基本概念

关键区别：写好一个 `.wsv` 文件，只代表有源码。加入项目、设计器能找到、完整编译、安卓上实际运行，是四次独立检查。

三、准备软件与工程

1. 打开火山安卓开发环境。

   在 Windows 上启动火山开发平台。官方新手教程的建项目路径为“文件 → 新建 → 项目”，选择“空白安卓程序”和“空窗口”。已有工程可直接打开桌面交付目录里的解决方案文件。

2. 打开当前案例。

   远程桌面交付目录：C:\Users\Administrator\Desktop\火山安卓项目交付。打开案例\uninativedemo.vsln。左侧项目树应看到 main.wsv、uni_button.wsv 等文件。

3. 确认基础模块。

   项目树的“模块”下应有“Java基本类”和“安卓基本类”。没有这两个模块，安卓控件名称可能无法识别。

4. 准备模拟器。

   远程电脑已安装 MuMu。测试时先启动模拟器，再编译或安装 APK。新建自己的项目时，使用自己的 Android 包名和签名配置。

四、认清目录和文件

火山安卓项目交付\
├─ 安卓组件库\
│  ├─ uni_button.wsv              ← 已验证的统一按钮源码
│  ├─ 卡片组件.wsv                ← 初版容器组件
│  ├─ 列表组件.wsv                ← 初版容器组件
│  ├─ 表格组件.wsv                ← 初版容器组件
│  └─ 其他初版组件...
├─ 案例\
│  ├─ uninativedemo.vsln          ← 双击它打开解决方案
│  ├─ uninativedemo\
│  │  ├─ uninativedemo.vprj       ← 项目结构文件
│  │  └─ src\
│  │     ├─ main.wsv              ← 案例窗口和调用代码
│  │     ├─ uni_button.wsv        ← 加入案例工程的组件源码
│  │     └─ 其他源码...
│  └─ uni_button_测试.apk          ← 独立测试包，非正式发布包
└─ UniApp组件对齐清单.md           ← 逐项验收状态

“组件库”和“案例”分开，是为了同一个组件未来能放进多个应用。案例工程中的 uni_button.wsv 是工程已引用的副本；修改后要同步这两处，避免一个新一个旧。

五、逐行理解按钮组件为什么这样写

本项目的按钮类写在 uni_button.wsv。它继承火山原有的 按钮，所以原有点击能力仍在；我们只增加五个简单的中文样式方法。

六、完整按钮源码

下面直接展示当前文件的实际内容。复制进新项目之前，先确认你的项目确实是火山安卓项目，并使用对应版本的安卓基础类库。这个类保留火山内置按钮能力，新增五种颜色方案；尚未实现 uni-app 按钮的所有属性和状态。

<火山程序 类型 = "通常" 版本 = 1 />
包 火山Uni.界面

类 统一按钮 <公开 基础类 = 按钮 注释 = "火山安卓 uni 风格按钮；继承安卓原生按钮，保留原有点击事件" @安卓.窗口组件.布局配置 = "native_class = \"android.widget.Button\"\ncategory = \"uni-ui 组件\"">
{
    # @ public @sn<current_class> (android.content.Context context, Button view) { super (context, view); }
    方法 设置主要样式 <公开 注释 = "蓝色主要按钮">
    参数 标题 <类型 = 文本型>
    {
        本对象.内容 = 标题
        本对象.背景色 = 0xFF007AFF
        本对象.文本颜色 = 0xFFFFFFFF
        本对象.文本字体尺寸 = 16
        本对象.置内边距 (16, 12, 16, 12)
    }

    方法 设置次要样式 <公开 注释 = "浅灰色次要按钮">
    参数 标题 <类型 = 文本型>
    {
        本对象.内容 = 标题
        本对象.背景色 = 0xFFF1F3F5
        本对象.文本颜色 = 0xFF333333
        本对象.文本字体尺寸 = 16
        本对象.置内边距 (16, 12, 16, 12)
    }

    方法 设置成功样式 <公开 注释 = "绿色成功按钮">
    参数 标题 <类型 = 文本型>
    {
        本对象.内容 = 标题
        本对象.背景色 = 0xFF18BC37
        本对象.文本颜色 = 0xFFFFFFFF
        本对象.文本字体尺寸 = 16
        本对象.置内边距 (16, 12, 16, 12)
    }

    方法 设置警告样式 <公开 注释 = "橙色警告按钮">
    参数 标题 <类型 = 文本型>
    {
        本对象.内容 = 标题
        本对象.背景色 = 0xFFFFA500
        本对象.文本颜色 = 0xFFFFFFFF
        本对象.文本字体尺寸 = 16
        本对象.置内边距 (16, 12, 16, 12)
    }

    方法 设置危险样式 <公开 注释 = "红色危险按钮">
    参数 标题 <类型 = 文本型>
    {
        本对象.内容 = 标题
        本对象.背景色 = 0xFFE43D33
        本对象.文本颜色 = 0xFFFFFFFF
        本对象.文本字体尺寸 = 16
        本对象.置内边距 (16, 12, 16, 12)
    }
}

五种方法怎么调用

七、把组件加入自己的安卓工程

1. 先复制源码到自己的项目目录。

   可从交付目录的 安卓组件库\uni_button.wsv 复制。建议放到自己项目的 src 下，名字保持不变。不要直接改交付库的唯一原件；先留好一份备份。

2. 在火山 IDE 中加入现有文件。

   在左侧项目名称上右键，选择“添加”里的现有文件入口，选刚复制的 uni_button.wsv。不同版本菜单文字可能略有差异。成功后，项目树中要能看到它。

3. 检查类名冲突。

   整个项目中只留一份名为 统一按钮 的类。同名类若同时来自多个源文件，编译器可能报重复定义。包名也要按项目实际情况组织。

4. 保存并重新打开布局设计器。

   设计器通常在启动时扫描当前项目的组件类。外部复制文件之后，必要时先关闭再重新打开源文件或设计器。

八、在 main.wsv 中最简单地调用

下面只保留和按钮有关的代码，方便第一次学习。当前案例的完整 main.wsv 还有工作台、订单等演示内容。

<火山程序 类型 = "通常" 版本 = 1 />
包 com.example.tablecase

类 启动类 <公开 基础类 = 窗口>
{
    变量 示例按钮 <类型 = 统一按钮 隐藏值属性 = "0"
        @安卓.窗口.布局 = "ctrl_order = 2\np_layout_height_type = wrap_content\np_layout_width_type = match_parent">

    方法 通知_被创建 <公开 @虚拟方法 = 可覆盖>
    参数 启动信息对象 <类型 = 启动信息类>
    参数 载入参数 <类型 = "对象类 []">
    参数 参数数目 <类型 = 整数>
    {
        父对象.通知_被创建 (启动信息对象, 载入参数, 参数数目)
        示例按钮.设置主要样式 ("立即体验")
    }
}

执行时机：通知_被创建 是窗口创建后的初始化方法。先调用 父对象.通知_被创建，再设置按钮文字和样式。调用没有返回参数；成功与否通过编译和运行结果判断。

九、怎样让组件出现在左侧拖拽列表

1. 确认源码已加入当前安卓项目。

   设计器读取的是项目已识别的窗口组件类，不会自动扫描桌面上所有文件。

2. 打开窗口布局。

   在 main.wsv 的窗口类处右键，选“设计启动类的界面布局”。若你用的是别的窗口类，菜单名称会随类名变化。

3. 在左侧找“uni-ui 组件”。

   按钮源码中写了 category = "uni-ui 组件"。远程测试已能在这个分类看到 统一按钮。

4. 尝试拖入窗口并命名。

   把组件拖入预览区，在属性中设置名称、宽高和边距。保存后检查窗口类是否出现类型为 统一按钮 的成员变量。

5. 最后一定完整编译并运行。

   “列表里看得到”只说明分类识别，不能代替拖入保存、Java 编译和安卓运行。当前已验证的是设计器分类可见与案例变量运行；直接拖入后保存的完整流程仍需单独记录。

十、从源码到 APK：按顺序验证

1. 先保存所有源文件。

   火山 IDE 若提示“文件已在外部修改，是否重新载入”，选重新载入，确保编译的是最新文件。避免只修改了桌面库副本，案例工程仍引用旧版。

2. 做完整构建。

   在“生成”菜单选择“生成活动项目”。只做“生成对应项目目标代码”不能证明 Java 编译和 APK 打包成功。

3. 看底部输出。

   成功应出现生成的 APK 路径和“编译并链接成功”。如果只看到代码生成成功，但 Java 构造方法报错，仍算失败。

4. 配置签名。

   安卓 APK 需要正确的签名配置。官方新手教程有“建立密钥文件”“编译发布版本”的步骤。测试可以用独立测试签名；正式发布应使用你自己妥善保管的签名密钥，不要把测试密钥当正式密钥。

5. 安装到 MuMu 并启动。

   本项目在独立测试副本 C:\unidemo 中修改成独立包名 com.example.unibuttontest，避免覆盖模拟器内已有同包名应用。APK 安装成功后，使用 ADB 启动，实际看到了“立即体验”按钮；点击后页面继续运行。

"D:\Program Files\Netease\MuMu\nx_main\adb.exe" devices -l
"D:\Program Files\Netease\MuMu\nx_main\adb.exe" install -r "C:\unidemo\_int\uninativedemo\release\linker\uninativedemo.apk"
"D:\Program Files\Netease\MuMu\nx_main\adb.exe" shell monkey -p com.example.unibuttontest -c android.intent.category.LAUNCHER 1
"D:\Program Files\Netease\MuMu\nx_main\adb.exe" shell pidof com.example.unibuttontest

这组命令解释的是本次测试流程；普通使用者也可以通过火山 IDE 的调试入口启动。devices -l 应看到 device；install 返回 Success；pidof 返回进程编号表示应用仍在运行。

十一、按钮以外：怎样封装“容器组件”

按钮是单个原生控件；卡片、列表、表格通常由多个子控件组成，需要一个能添加子控件的容器。现有初版采用 基础类 = 自定义窗口容器组件。下面是从本项目卡片源码提炼的核心结构：

类 卡片组件 <公开 基础类 = 自定义窗口容器组件
    @安卓.窗口组件.布局配置 = "native_class = \"@安卓自定义窗口容器组件\"\ncategory = \"uni-ui 组件\"">
{
    方法 设置内容 <公开>
    参数 标题 <类型 = 文本型>
    参数 正文 <类型 = 文本型>
    参数 提示 <类型 = 文本型>
    {
        变量 标题框 <类型 = 文本框 参考>
        本对象.布局器.删除所有子组件 ()
        标题框 = 本对象.取安卓窗口容器组件 ().创建窗口组件 (文本框, 空对象)
        标题框.内容 = 标题
        本对象.布局器.添加子组件 (标题框, 空对象)
        # 同样方式创建正文框、提示框并加入布局器
    }
}

十二、表格要特别注意：外观与数据结构不能混为一谈

当前演示页的“最近订单”把一整行文字放进一个文本框，例如订单号、客户、状态被空格和换行拼在一起。这能做视觉演示，不是真正的三列表格。独立 表格组件.wsv 有“清空、设置表头、添加行”的初版方法，但它的 添加行 仍以整段文本创建一个文本框。

真正的表格应该怎样设计

1. 先定义列：例如“订单号、客户、状态”，每列有字段名、宽度、显示类型。
2. 每条数据行创建一个横向容器；每列在这个容器中创建独立单元格。
3. 状态列若要下拉，创建真正的选择控件，不能只显示“待处理”三个字。
4. 每行绑定稳定的业务 ID，例如 A1002；改变下拉值时保存 ID 和新状态。
5. 重新渲染时从数据恢复选中值；输入错误行号或列号时返回中文错误。
6. 窄屏和大字体下检查对齐、横向滚动与可访问性。

十三、现有组件有哪些公开命令

下表只列当前独立源码文件里能看到的公开方法。按钮已完成基础运行验证；其余仍为待验收初版。参数顺序按源文件实际声明填写。

十四、常见错误及修复

十五、一个组件怎样才算“真的封装完成”

做完整组件库，不应只用“有类名”作为完成标准。以下清单每一项都要有证据：

• 独立源文件存在，类名、包名和公开方法清楚。
• 加入一个全新安卓工程后，项目树能识别它。
• 设计器左侧能找到，实际拖入并保存后能生成窗口变量。
• 属性有默认值、边界值和错误处理；多次更新内容不会重复堆叠。
• 事件能绑定并拿到正确参数，点击或选择后能执行实际动作。
• 完整构建通过：火山代码生成、Java 编译、签名和 APK 链接。
• 安卓模拟器或真机可显示、可交互，关闭与重新进入后状态正确。
• 有完整调用案例，传入什么、返回什么、出错如何处理都写明白。
• 对照 uni-app 官方文档，逐条记录已支持、未支持和 Android 特有限制。

当前按钮达到“基础可构建、可显示、可点击后继续运行”，尚未达到上面全部验收项。官方组件对齐进度以 UniApp组件对齐清单.md 为准。

十六、新手最常问的几个问题

十七、第一次动手：照着做一遍按钮案例

这一节按“你正在远程 Windows 桌面前操作”来写。每做完一步先核对结果，再做下一步；失败时从对应步骤返回，不要跳到编译末尾猜原因。

1. 找到交付目录。

   在 Windows 文件资源管理器打开桌面，进入 火山安卓项目交付。应同时看到 安卓组件库、案例 和本教程。若只看到 APK 而找不到源码，说明当前打开的不是交付目录。

   完成标志：安卓组件库\uni_button.wsv 和 案例\uninativedemo.vsln 都存在。

2. 打开解决方案，不要只双击源码。

   双击 案例\uninativedemo.vsln。火山 IDE 左侧出现解决方案树，展开项目后能看到 main.wsv 与 uni_button.wsv。只双击一个孤立的 .wsv 文件可能看得到代码，却没有正确的项目模块与编译配置。

   完成标志：标题栏显示工程名，左侧存在“Java基本类”“安卓基本类”模块。

3. 先打开按钮源码核对类名。

   双击项目树里的 uni_button.wsv。上方应有 包 火山Uni.界面，类名应为 统一按钮，公开方法包括 设置主要样式。若看不到这些内容，可能打开了旧副本。

   完成标志：编辑器中可以看到五种样式方法和构造函数嵌入行。

4. 再看案例窗口怎么调用。

   双击 main.wsv，找到变量 示例按钮 和窗口创建方法中的 示例按钮.设置主要样式 ("立即体验")。前者是“放了一个按钮”，后者是“给这个按钮设置外观”。二者的变量名必须相同。

   完成标志：变量声明的类型为 统一按钮，调用目标也是同一个 示例按钮。

5. 看设计器分类。

   在窗口类位置右键打开界面布局设计器。查看左侧 uni-ui 组件 分类，确认有 统一按钮。本步骤只核对分类识别；若你自己拖入新按钮，还应保存布局并检查生成的窗口变量，不能只看预览图。

   完成标志：左侧分类中能看到组件名称。

6. 执行完整构建。

   返回代码界面，保存文件，从“生成”菜单选“生成活动项目”。等待底部输出结束。成功时输出里有 APK 路径和“编译并链接成功”；如果只出现“目标代码生成成功”，还需要继续确认 Java 编译和打包。

   完成标志：完整构建成功，无错误，APK 文件确实生成。

7. 启动 MuMu 看实际画面。

   先让模拟器启动到安卓桌面，再安装测试 APK。当前交付目录的 案例\uni_button_测试.apk 是独立包名的测试产物。打开后应在“工作台”标题下看到蓝色“立即体验”按钮。点一下按钮，页面应继续显示。

   完成标志：蓝色按钮真实显示在安卓界面上，点击后没有退出。

十八、把按钮方法再拆开：每一行改变了什么

初学时只看“蓝色按钮”会不知道颜色从哪里来。下面以 设置主要样式 为例，按执行顺序解释实际源码。

方法 设置主要样式 <公开 注释 = "蓝色主要按钮">
参数 标题 <类型 = 文本型>
{
    本对象.内容 = 标题
    本对象.背景色 = 0xFF007AFF
    本对象.文本颜色 = 0xFFFFFFFF
    本对象.文本字体尺寸 = 16
    本对象.置内边距 (16, 12, 16, 12)
}

想改成自己的按钮，最少改哪三处？

1. 把调用参数 "立即体验" 改成实际标题，例如 "提交订单"。
2. 需要另一种预设颜色时，换调用的方法名，例如 设置危险样式；不要在每个页面重复写颜色。
3. 需要新的品牌颜色时，在组件库新增一个公开样式方法，再从窗口调用；不要直接改坏已经通过验证的五个方法。

十九、发生错误时，按哪一层排查

从最靠近错误的一层查起。这样可以避免“设计器列表看不到，就去改安卓签名”之类的无效操作。

什么时候需要保存“错误原文”？

看到任何编译失败时，把底部输出中的源文件路径、行号、错误内容一起保存。只说“编译失败”无法判断是火山语法、Java 构造、签名，还是模拟器连接问题。改动后重新构建，并确认旧错误确实消失。

二十、学会按钮后，怎样独立封装下一个组件

新组件按固定流程推进，别一次复制几十个同名空壳。下面以“列表组件”为例，说明工作顺序；这是开发步骤，不代表它已经通过验收。

1. 先明确用途和最小调用。

   例如 列表.添加项目 ("订单 A1001", "张三 · 已完成")。先写明调用者传两个文本参数，方法把一条项目加到列表末尾；列表.清空 () 则删除全部项目。把这两个行为写清楚，再动源码。

2. 确定组件结构。

   每项要有标题和说明两个独立子控件。列表本身需容纳多项，因此继承容器组件比继承单个文本框更合适。

3. 写一个独立 `.wsv`。

   定义公开类、布局配置与最少的公开方法。检查包名和类名不与案例里的 uni_components.wsv 重复。若已有同名聚合类，先整理工程引用。

4. 只把这个组件加入案例。

   在 main.wsv 声明一个该类型的变量，调用 添加项目 两次、清空 一次，再添加一次。预期应只有最后一项；这样能测出追加和清空是否正确。

5. 逐层验收。

   先设计器识别，再完整编译 APK，然后在 MuMu 中核对显示、点击、重复添加、清空后重建。每一步记录结果。

6. 最后写文档。

   把公开方法、参数类型、调用示例、返回值、错误行为、当前限制写到教程和对齐清单里。没有运行证据就标“未验收”。

二十一、建议怎样保存验收记录

每个组件维护一张简单记录表。这样以后换一台 Windows 电脑或换一个火山版本，也能快速知道什么被验证过。

记录时请把“看得到”“能拖入”“能保存”“能编译”“能运行”分成不同列。它们互相不能替代。正式发布前还应验证签名、包名、安装升级和目标安卓版本。

二十二、参考资料和文件入口

• 火山官方：安卓新手入门，包括新建项目、模拟器调试、包名、密钥和编译发布。
• 火山官方：封装语法手册，用于理解包、类、继承、嵌入目标语言代码等封装层语法。
• uni-app 官方组件目录，用来逐项核对目标组件能力。
• uni-ui 官方说明，用来核对扩展组件范围。
• 本机工作区：/Users/songguoqing/Downloads/Bug/火山/安卓组件库/uni_button.wsv、安卓表格案例/main.wsv、UniApp组件对齐清单.md。

本页是离线 HTML，双击即可在浏览器打开；源码示例仅展示，不会在网页里编译或运行火山代码。复制按钮只复制可见代码。