文档核心目标：

提供一个系统化、详细的 JSBox 学习路径，帮助学习者从入门到精通，最终能开发完整的 iOS 应用脚本。这份材料强调准确性、最佳实践，并经过了专业审阅。

JSBox 是什么？

• iOS 脚本工具。

• 允许使用 JavaScript (ES6) 深度调用 iOS 原生功能。

• 核心能力：自动化、自定义 UI、开发实用工具。

• 主要特点：$符号开头的扩展API、轻量化设计、移动编程优先、沙盒环境运行安全。

学习路线概述 (八大阶段)：

1. 阶段一：快速开始 (Quick Start)

   • 目标： 建立概念基础，熟悉环境。

   • 核心概念：

     • 基础语言： JavaScript。

     • API 风格： 所有扩展 API 以 $开头 (如$ui, $http)。

     • 设计哲学： 轻量、简洁、移动端友好。

     • 运行环境: 独立沙盒 (安全隔离)。

     • 运行/编辑方式： 应用内编写、URL Scheme 安装、VSCode 插件同步、AirDrop。

   • 实践示例： 文档列出了展示基础交互（如输出、用户选择、提示框）的 API 示例片段（具体代码未完整显示）。

2. 阶段二：基础接口 (Core API)

   • 目标： 掌握与应用基础、设备、网络、数据存储相关的核心API。

   • 涵盖范围（示例）：

     • 应用 ($app): 获取信息、管理主题。

     • 设备 ($device): 获取设备信息、电池状态。

     • 网络 ($http): 发起网络请求，处理响应。

     • 文件系统 ($file)： 读写文件。

     • 数据存储： $key (键值对存储),$cache (临时缓存), $drive (iCloud)。

   • 实践重点： 使用 $http 进行网络请求并处理响应数据；理解不同存储选项的适用场景 ($key, $cache,$drive, $file)。

3. 阶段三：构建界面 (UI Building)

   • 目标： 学习使用 JavaScript 定义和布局原生 iOS UI。

   • 核心组件： $ui。

   • 核心流程：

     • 创建视图树： 使用 $ui.render() 或$ui.create() 等方法构建视图组件。

     • 布局： 使用 layout() 方法或属性 (left, right, top, bottom, width, height) 进行灵活布局。

     • 事件处理： 通过事件属性 (events) 绑定 JavaScript 函数处理用户交互（如按钮点击）。

   • 基本控件介绍： Label, Button, Input, Slider, Switch, Stepper 等的基本创建与交互。

4. 阶段四：控件列表 (UI Controls)

   • 目标： 深入探索 JSBox 提供的各种 UI 控件及其高级用法。

   • 覆盖控件（更深入详细）：

     • 导航组件: Navigation Bar (nav), Tab Bar (tab), Tool Bar (toolbar).

     • 容器组件: List (list：高性能列表核心), Table (table), Matrix View (matrix：瀑布流), Scroll View (scroll), Stack View (stack), Page Control (pager), Web View (web), Canvas (canvas).

     • 复杂输入: Picker (picker), Date Picker (date), Color Picker (color).

     • 可视化组件: Chart (chart), Map (map), Image (image), Video (video), Progress (progress), Activity Indicator (loading).

     • 其他实用组件: Blur View (blur), Text View (text), Rating View (rating), Menu Button (menu), Keyboard (keyboard).

   • 学习重点： 理解每个控件的特定配置项、事件和最佳实践场景（尤其是 list 及其 template 机制）。

5. 阶段五：数据类型与内置函数 (Data Types & Utils)

   • 目标： 处理 JavaScript 与 Native 数据间的转换；掌握内置辅助函数库。

   • 关键内容：

     • 数据类型转换: $data (json, string, utf8, base64),$image (PNG, JPEG)。

     • 辅助函数 ($util/$objc.utils):

       • 文件系统路径：$addin,$path。

       • 时间日期：$date.

       • 文本处理：$text (size, md5).

       • 设备功能：$clipboard,$photo.scan, $photo.pick,$photo.save.

       • 其他实用：$random, 调试函数 ($console, $log,$debug), $alert,$delay, $objc.utils.invoke().

     • 二进制数据处理： $blob。

6. 阶段六：Promise 与高级特性 (Promise & Advanced)

   • 目标： 掌握 JSBox 异步编程最佳实践；学习高级扩展功能。

   • 核心：

     • Promise & async/await： JSBox API 广泛支持 Promise ($http,$drive, $photo.pick 等)。推荐使用 async/await 语法进行异步操作和优雅的错误处理 (try...catch)。

     • Notification / Action Center ($push): 管理通知。

     • Shortcuts ($shortcut): 创建/运行 iOS 快捷指令。

     • Safari Extension ($safari): 与 Safari 交互。

     • Share Extension ($share): 响应系统分享。

     • Today Widget ($widget): 开发小组件。

     • 其他高级 API: $location (地理定位),$siri (Siri 交互), $audio (音频处理),$qr (二维码扫描), $int/$int.launch (应用间跳转 - URL Scheme)。

   • 实践重点： 熟练掌握 async/await 和错误处理；探索感兴趣的扩展 API (如 $share,$widget, $safari) 或原生 SDK。

   • 注意： 部分 API 需要用户授权（运行时弹出提示）。

7. 阶段七：包管理 (Package Management)

   • 目标： 组织大型、模块化、可维护的 JSBox 项目。

   • 概念： .box 文件本质是包含项目所有内容的 zip 包。

   • 包结构：

     • main.js: 必需，脚本入口。

     • config.json: 必需，定义名称、版本号、作者等元数据，以及图标文件路径、主题模式、依赖权限等配置。

     • scripts/: (推荐)存放模块化 JS 文件 (*.js)。

     • assets/: 存放icon.png、图片、图标等静态资源文件。在代码中通过相对路径引用（如 assets/icon.png）。

     • strings/: (推荐)存放 .strings 文件实现本地化（如 en.strings, zh-Hans.strings）。通过 $l10n("key")函数调用。

   • 模块化：

     • require('./scripts/module_file.js'): 导入其他 JS 模块。模块文件通过 module.exports = {...} 导出其功能。避免全局污染，提高复用性。

   • 安装方式： AirDrop, 文件分享, URL Scheme。

   • 实践流程示例：

     1. 在电脑上创建规定结构的文件夹 (MyPackageScript/...)。

     2. 填充 main.js (入口), config.json (元数据), 模块文件 (如 data_manager.js), .strings 文件 (多语言), icon.png 等。

     3. 压缩整个文件夹为 MyPackageScript.zip。

     4. 通过 AirDrop 等方式分享到 iOS 设备，选择用 JSBox 打开安装。

     5. 运行脚本包测试功能，理解模块协调和工作流程。

8. 阶段八：Objective-C Runtime (Runtime)

   • 目标： 掌握最高级能力，直接与 iOS Objective-C 原生底层交互 (当 JSBox 封装层功能不足时)。

   • 核心概念 & API：

     • $objc("ClassName"): 获取原生类对象。

     • .methodName() / .invoke("methodName:", ...args): 调用原生方法（后者用于带参数名）。

     • .jsValue(): 将原生对象转换为 JS 对象。

     • .ocValue(): 将 JS 对象转换为原生对象。

     • $define(...): 动态创建 Objective-C 类。

     • $delegate(... , { delegateMethods }): 动态创建 代理对象。

     • $block((...args) => {...}): 将 JS 函数封装成 Objective-C Block。

     • 导入规范： 必须使用 const ClassName = $objc("ClassName"); 单独导入每个类 禁止 使用逗号分隔字符串批量导入。

   • 示例用途： 文档列出了调用原生方法的示例（如 NSString、UIImage、UIColor），但未显示完整代码。

阶段九：综合实践案例 - 提醒应用小程序

• 目标： 综合运用前八个阶段的知识构建一个完整的应用。

• 项目结构 (MyReminderApp/)：

  • main.js: 主入口脚本。

  • config.json: 应用配置元数据。

  • scripts/: 包含功能模块：

    • reminder_model.js: 负责提醒事项的数据模型（增删改查）。

    • reminder_view.js: 负责构建和管理用户界面 ($ui)。

    • util.js: (新增) 存放通用的辅助函数（如日期格式化、数据处理）。

  • strings/: 多语言文本 (en.strings, zh-Hans.strings)。

  • assets/icon.png: 应用图标。

• 功能实践：

  • UI (reminder_view.js)： 运用布局、列表 (list 控件的 data, template, events) 展示和管理提醒列表，包括添加/编辑界面（使用 input, button, date 等控件）。

  • 数据 (reminder_model.js)： 使用 $key,$cache 或 $drive 持久化存储提醒数据（含创建时间、标题、到期时间等信息）。

  • 入口协调 (main.js)： 初始化应用，协调数据模型和界面视图的交互。可能使用 $router。

  • 模块化： require 引入各个模块 (reminder_model, reminder_view, util)。

  • 本地化： 通过 strings/ 里的定义和 $l10n() 实现多语言。

• 最终文件： 所有源文件被打包成一个 .box (zip) 文件（如 MyReminderApp.box），可在 JSBox 中安装并运行。

总结：

这份文档提供了一个结构清晰、循序渐进的 JSBox 学习路线，从基础概念（环境、API风格）到核心功能（基础接口、UI构建、控件、工具），再到高级开发（异步、包管理、原生交互 Runtime），最终通过一个完整的项目演练巩固所有知识点。它强调了模块化、最佳实践（如使用 async/await、require/module.exports）、以及对包结构和配置的规范要求。掌握这份路线图的知识点，即可进行高效的 JSBox 脚本开发。