ArozOS WebApp开发指南：从入门到实践

2026-02-04 04:13:22作者：谭伦延

前言

ArozOS作为一个现代化的Web操作系统，提供了强大的WebApp开发能力。本文将深入解析ArozOS的WebApp开发体系，帮助开发者快速掌握核心开发技术。

AGI接口详解

AGI（Aroz Gateway Interface）是ArozOS的核心接口，类似于PHP在Apache中的作用，它允许开发者通过JavaScript风格的接口实现前后端交互。

AGI执行模式

AGI脚本支持四种执行模式，每种模式具有不同的权限和作用域：

WebApp初始化脚本（系统级权限）
WebApp后端逻辑（系统级权限）
Serverless工具执行（当前用户权限）
系统调度任务（当前用户权限）

WebApp基础结构

一个标准的ArozOS WebApp应包含以下目录结构：

└── web/
    └── mywebapp/
        ├── init.agi          # 应用初始化脚本
        ├── index.html        # 主入口文件
        ├── embedded.html     # 嵌入式模式入口
        ├── floatwindow.html  # 浮动窗口入口
        ├── img/              # 资源目录
        └── backend/          # 后端逻辑目录

WebApp初始化配置

init.agi是WebApp的必备文件，用于定义应用的基本信息和启动配置。下面是一个完整的配置示例：

var moduleLaunchInfo = {
    Name: "音乐播放器",
    Desc: "ArozOS最佳音乐播放器",
    Group: "Media",
    IconPath: "Music/img/module_icon.png",
    Version: "1.0.0",
    StartDir: "Music/index.html",
    SupportFW: true,
    LaunchFWDir: "Music/index.html",
    SupportEmb: true,
    LaunchEmb: "Music/embedded.html",
    InitFWSize: [800, 600],
    InitEmbSize: [400, 300],
    SupportedExt: [".mp3",".flac",".wav"]
};

关键配置项解析

配置项	说明	示例值
Name	应用名称	"音乐播放器"
Group	应用分类	"Media"
SupportFW	是否支持浮动窗口模式	true
SupportEmb	是否支持嵌入式文件打开模式	true
SupportedExt	支持打开的文件扩展名列表	[".mp3",".flac"]

应用分类指南

ArozOS预定义了多个应用分类，开发者应根据应用功能选择合适的分类：

媒体(Media)
办公(Office)
下载(Download)
文件(Files)
互联网(Internet)
系统设置(System Settings)
系统工具(System Tools)

前后端交互实践

后端逻辑调用

在HTML前端中，可以通过ao_module_agirun调用后端逻辑：

<script>
function runBackendLogic() {
    ao_module_agirun(
        "myapp/backend/logic.js",  // 后端脚本路径
        {param1: "value"},         // 传递参数
        function(resp) {           // 成功回调
            console.log(resp);
        },
        function() {               // 失败回调
            alert("请求失败");
        },
        30                         // 超时时间(秒)
    );
}
</script>

后端脚本示例

后端脚本(logic.js)可以通过SendResp函数返回数据：

// 获取前端传递的参数
var param1 = getParam("param1");

// 处理逻辑
var result = "处理结果: " + param1;

// 返回响应
SendResp(result);

浮动窗口开发技巧

窗口控制API

ArozOS提供了丰富的浮动窗口控制API：

// 设置窗口大小
ao_module_setWindowSize(800, 600);

// 设置窗口标题
ao_module_setWindowTitle("我的应用");

// 关闭当前窗口
ao_module_close();

// 创建新浮动窗口
ao_module_newfw({
    url: "app/index.html",
    title: "新窗口",
    width: 1024,
    height: 768
});

父子窗口通信

实现父子窗口间的数据传递：

// 子窗口向父窗口发送数据
if(ao_module_hasParentCallback()) {
    ao_module_parentCallback(JSON.stringify({
        action: "update",
        data: "新数据"
    }));
}

// 父窗口接收子窗口数据
function childCallbackHandler(data) {
    console.log("收到子窗口数据:", data);
}

文件处理最佳实践

文件选择器集成

// 打开文件选择器
ao_module_openFileSelector(
    function(files) {          // 回调函数
        files.forEach(file => {
            console.log(file.filename);
        });
    },
    "user:/Desktop",           // 初始路径
    "file",                    // 选择类型(file/folder/all/new)
    true                       // 允许多选
);

文件上传实现

// 上传文件示例
function uploadFile(file, targetPath) {
    ao_module_uploadFile(
        file,
        targetPath,
        function() {           // 上传成功回调
            alert("上传成功");
        },
        function(progress) {   // 进度回调
            console.log(progress + "%");
        },
        function() {           // 失败回调
            alert("上传失败");
        }
    );
}

实用工具函数

ArozOS提供了丰富的工具函数简化开发：

// 存储操作
ao_module_storage.setStorage("myapp", "config", {theme: "dark"});
var config = ao_module_storage.loadStorage("myapp", "config");

// 格式转换
var size = ao_module_utils.formatBytes(1024); // "1 KB"
var time = ao_module_utils.timeConverter(Date.now()/1000);

// 文件处理
var blob = ao_module_utils.stringToBlob("文本内容");