iOS Scriptable TSX 项目快速入门指南

项目概述

iOS Scriptable TSX 是一个基于 TypeScript 和 JSX 语法开发 iOS Scriptable 小工具的开源框架。它允许开发者使用熟悉的 React-like 语法来构建 iOS 桌面小组件，大大提升了开发效率和代码可维护性。

环境准备

在开始之前，请确保你的开发环境中已经安装以下工具：

1. Node.js (建议使用最新LTS版本)
2. npm 或 yarn 包管理器
3. Git 版本控制工具
4. 一台运行 iOS 的设备，并已安装 Scriptable 应用

项目初始化

首先需要获取项目代码到本地开发环境：

git clone 项目仓库地址
cd ios-scriptable-tsx
npm install

安装过程会自动下载所有必要的依赖项，包括 TypeScript 编译器、打包工具以及 Scriptable 特有的类型定义。

创建第一个组件

在 src/scripts 目录下创建 helloWorld.tsx 文件，这是我们的第一个组件示例：

class HelloWorld {
  async init() {
    const widget = (await this.render()) as ListWidget
    Script.setWidget(widget)
    !config.runsInWidget && (await widget.presentMedium())
    Script.complete()
  }
  
  async render(): Promise<unknown> {
    return (
      <wbox>
        <wspacer></wspacer>
        <wtext font={30} textAlign="center">
          Hello World
        </wtext>
        <wspacer></wspacer>
      </wbox>
    )
  }
}

new HelloWorld().init()

这段代码展示了一个基本的 Scriptable 组件结构：

1. init 方法是组件入口，负责初始化并渲染组件
2. render 方法使用 JSX 语法定义组件UI
3. 组件中使用了一些 Scriptable 特有的元素：
   • wbox: 容器组件
   • wtext: 文本组件
   • wspacer: 间距组件

配置入口文件

修改 src/index.ts 文件，引入我们新创建的组件：

import './scripts/helloWorld.tsx'

这个文件是项目的打包入口，所有需要打包的组件都应该在这里引入。

开发与调试

运行以下命令启动开发服务器：

npm run watch

这个命令会：

1. 启动 TypeScript 编译器监视文件变化
2. 开启本地开发服务器
3. 在终端显示二维码和访问地址

设备同步设置

在 iOS 设备上执行以下操作：

1. 打开 Scriptable 应用
2. 创建新脚本并命名为"你好世界"
3. 选择"远程开发"选项
4. 输入开发服务器提供的同步地址（格式为 http://IP地址:端口/index.js）
5. 同步成功后即可预览组件效果

添加到桌面

将组件添加到 iOS 桌面的步骤：

1. 长按桌面空白处进入编辑模式
2. 添加 Scriptable 小组件
3. 编辑小组件，选择"你好世界"脚本
4. 保存后即可在桌面看到效果

构建命令说明

项目提供了多种构建命令以适应不同开发场景：

命令	用途描述	特点
npm run dev	开发环境构建单个文件	不混淆代码，便于调试
npm run dev:all	开发环境构建多个文件	批量构建scripts目录下所有文件
npm run build	生产环境构建单个文件	代码混淆和优化
npm run build:all	生产环境构建多个文件	批量构建并优化
npm run watch	开发模式并启动热更新服务器	实时编译，支持设备同步

开发注意事项

1. 由于打包器保留字 module 与 Scriptable 全局变量冲突，建议使用 MODULE 替代
2. 确保开发设备和电脑在同一局域网下
3. 首次使用需要安装基础包
4. 生产环境构建会自动进行代码混淆和优化

进阶建议

掌握了基础用法后，你可以进一步探索：

1. 使用 TypeScript 强类型特性增强代码健壮性
2. 尝试更复杂的布局和样式
3. 集成网络请求和数据展示
4. 开发可配置参数的组件
5. 实现组件间的数据共享

通过这个框架，你可以用现代前端开发的方式构建功能丰富的 iOS 桌面组件，享受类型安全和组件化开发带来的便利。