# affinity-svg

**Repository Path**: wavef/affinity-svg

## Basic Information

- **Project Name**: affinity-svg
- **Description**: 让Affinity导出的SVG动起来
- **Primary Language**: JavaScript
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-24
- **Last Updated**: 2025-12-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Affinity SVG

Affinity SVG 是一个轻量级的 JavaScript 库，用于为从 Affinity Designer 导出的 SVG 文件添加动画和操作功能。它通过解析在 Affinity 设计软件中添加的特殊标记属性来启用 SVG 元素上的动画。

## 功能特性

- **轻量级**: 最小化占用，无重型依赖
- **动画库**: 由 AnimeJS 驱动，实现流畅动画效果
- **Affinity 集成**: 与从 Affinity 导出的 SVG 文件无缝协作
- **声明式语法**: 使用 SVG 中的标记属性定义动画
- **多种动画类型**: 支持各种动画效果，包括透明度、移动、旋转、缩放等


## 使用方法

1. 执行 `packer/index.html` 启动封装器
2. 选择 Affinity 输出的带有表达式的 SVG 文件预览动画
3. 点击按钮保存封装后的 SVG 动画文件

## 工作原理

Affinity SVG 会查找 SVG 中带有 `serif:id` 属性且包含特殊格式表达式的元素。这些表达式定义了元素应该如何进行动画。

### 表达式

表达式遵循以下格式：
```
command(*children)_(#pad)value(*delay)_(@forward)(!reversed)duration(*loop)_ease

指令(*子元素)_(#占位)数值_(*延时)_(@单向)(!倒放)时长(*循环)_缓动曲线
```

其中主要分为四部分，每部分用 下划线`_` 分隔：

#### 第 1 部分：指令
- `command`: 动画类型指令 (alpha, move, rotate, scale 等)
- `*`: 对子元素应用动画

#### 第 2 部分：数值
- `#`: 数值补零
- `value`: 动画的目标值
- `*`: 多个元素的交错延迟

#### 第 3 部分：时长
- `@`: 单向
- `!`: 倒放
- `duration`: 动画持续时间（秒）
- `*loop`: 循环次数 (默认无此参数表示无限循环)

#### 第 4 部分：缓动
- `ease`: 缓动函数 (<, >, <>, 0, 或自定义，如`inOutCibuc`)

### `command` 支持的指令

- `alpha`: 透明度动画
- `x`, `y`: 位置动画
- `rotate`: 旋转动画
- `scale`: 缩放动画
- `line`: 线条绘制动画
- `time`: 动态时间显示
- `num`: 数值动画
- `frame`: 帧动画

### 示例表达式

```xml
<!-- 在 2 秒内淡出至 50% 透明度 -->
<g serif:id="{{alpha_0.5_2}}">

<!-- 将元素水平往右移动 100 像素，持续 1 秒 -->
<g serif:id="{{x_100}}">

<!-- 逆时针线性旋转 360 度 -->
<g serif:id="{{rotate_1_!@0"}}>

<!-- 对所有子元素应用交错延迟动画 -->
<g serif:id="{{alpha_0_*0.2_2}}">
```

## 开发

```bash
# 安装依赖
pnpm install

# 调试
pnpm dev

# 构建，执行后会自动更新 packer/af-svg.js
pnpm build
```

### 项目结构

```
src/
├── main.js          # 主库入口文件
├── tween/           # 动画函数
│   ├── alpha.js     # 透明度动画
│   ├── move.js      # 位置动画
│   ├── rotate.js    # 旋转动画
│   ├── scale.js     # 缩放动画
│   ├── line.js      # 线条绘制动画
│   ├── time.js      # 时间显示更新
│   ├── num.js       # 数值动画
│   └── frame.js     # 帧动画
└── utils/           # 工具函数
    └── utils.js     # 辅助函数

packer/
├── index.html       # 封装器
├── af-svg.js        # svg内嵌脚本
└── pack.js          # 构建后更新af-svg.js的自动化脚本

```

## 依赖

- [AnimeJS](https://animejs.com/) - 轻量级 JavaScript 动画库
- [Vite](https://vitejs.dev/) - 构建工具 (使用 rolldown-vite 实现更快的构建速度)

## 许可证

该项目基于 APGLv3 许可证 - 详情请参见 LICENSE 文件。