秋之盒

快速开始

# 快速开始

3 分钟创建你的第一个秋之盒插件。

技术栈说明

秋之盒插件 UI 使用 React 19 + Ant Design 构建。编写 App 和 Card 组件时，你将使用 JSX/TSX 语法和 React Hooks。如果你不熟悉 React，建议先阅读 React 官方文档 (opens new window)。

不需要 React 的场景（Canvas、WebGL、第三方非 React 库），可以使用 mount 模式直接操作 DOM——详见 非 React 界面开发。

# 前置条件

  • Node.js 20+
  • pnpm 9+

# 创建项目

git clone https://github.com/zsh2401/AutumnBoxPluginTemplate.git my-plugin
cd my-plugin
pnpm install

package.json 的 name 字段就是插件的唯一标识（pluginPackageName）。创建项目后请先修改为你自己的包名。

# 编写一个 App

App 是用户从应用列表打开的标签页页面。我们来写一个显示设备信息的 App：

// src/apps/MyFirstApp.tsx
import { Card, Typography, Button } from 'antd';
import { useService, useRequiredDevice } from '@autumnbox/sdk/hooks';
import { ShellService } from '@autumnbox/sdk/services';

import type { AutumnApp } from '@autumnbox/sdk';

const { Title, Text } = Typography;

const MyFirstAppView: React.FC = () => {
  const device = useRequiredDevice();
  const shell = useService(ShellService);

  const checkSdk = async () => {
    const output = await shell.exec(device, 'getprop ro.build.version.sdk');
    alert('Android SDK 版本: ' + output.trim());
  };

  return (
    <div style={{ padding: 24, maxWidth: 600 }}>
      <Title level={3}>My First App</Title>
      <Card>
        <p>设备: <Text code>{device.sn}</Text></p>
        <Button type="primary" onClick={checkSdk}>检查 SDK 版本</Button>
      </Card>
    </div>
  );
};

// SVG 图标，直接内联
const myIcon = `data:image/svg+xml,${encodeURIComponent(`
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128">
  <rect width="128" height="128" rx="28" fill="#6366f1"/>
  <text x="64" y="82" text-anchor="middle" font-size="52" fill="white">Hi</text>
</svg>`)}`;

export const MyFirstApp: AutumnApp = {
  id: 'my-first-app',
  name: 'app.name.my_first_app',    // i18n key
  icon: myIcon,
  shallSelectAdbDevice: true,        // 打开前要求用户选择设备
  component: MyFirstAppView,
};

要点：

  • shallSelectAdbDevice: true 让宿主在打开 App 前提示用户选设备
  • useRequiredDevice() 获取设备句柄，保证非空
  • useService(ShellService) 从 IoC 容器获取 Shell 服务
  • shell.exec(device, command) 执行 ADB 命令并返回输出

# 添加翻译

创建语言文件：

// resources/lang/zh-CN.json
{
  "app.name.my_first_app": "我的第一个插件"
}

// resources/lang/en-US.json
{
  "app.name.my_first_app": "My First Plugin"
}

name 字段的值是 i18n key，宿主会自动查找对应语言的翻译。

# 构建

pnpm run build

输出 .atmb 文件，这就是你的插件包：

my-plugin/
└── myplugins-my-first-app.atmb    ← 构建产物

# 安装到秋之盒

打开 app.atmb.top (opens new window)，进入设置 → 插件管理，导入 .atmb 文件即可。

或者手动复制到秋之盒的插件目录：

cp *.atmb /path/to/AutumnBoxRevive/packages/app/builtin-plugins/

# 清理模板文件

模板自带的示例文件可以删除：

rm src/apps/ExampleApp.tsx
rm src/cards/ExampleCard.tsx
rm src/services/ExampleService.ts

保留 src/ 目录结构和 resources/lang/ 语言文件即可。

# 下一步

最后更新: 4/8/2026, 2:35:44 AM

基础知识