跳转到使用指南
gsap-utils作者 GreenSock

GSAP Utils Skill.

Claude Code 和 Codex 的动效与视频 skill:gsap.utils 辅助函数:clamp、mapRange、interpolate、snap、wrap、pipe。

  • Motion & Video
  • UI 代码
greensock/gsap-skills · skills/gsap-utils/SKILL.mdSKILL.md
--- name: gsap-utils description: Official GSAP skill for gsap.utils — clamp, mapRange, normalize, interpolate, random, snap, toArray, wrap, pipe. Use when the user asks about gsap.utils, clamp, mapRange, random, snap, toArray, wrap, or helper utilities in GSAP. --- ## When to Use This Skill ## Clamping and Ranges ## Random and Snap ## Units and Parsing ## Arrays and Collections ## Best practices
前言和章节标题读取自 2026-09-14 的上游文件 · 完整内容 12,051 字符

01 功能说明

gsap-utils Skill 在 Claude Code 和 Codex 中的作用

摘要、工作流与产物,均读自该 skill 的 SKILL.md。

来自 SKILL.md读取于 2026-09-14 · 非实际运行记录

以 skill 自身的术语

gsap.utils 是 GSAP 提供的一组纯辅助函数,用于数学运算、区间、单位、颜色和集合处理,无需注册即可使用。该 skill 记录了 clamp、mapRange、normalize、interpolate、random、snap、shuffle、distribute、getUnit、unitize、splitColor、selector、toArray、pipe、wrap 和 wrapYoyo 的函数签名、默认值以及实际输出示例。

它适用于需要将 scroll 映射到某个数值、对输入进行归一化、按网格吸附或在组件内限定选择器范围的 GSAP 代码编写者与审阅者。文件中贯穿一个统一模式:省略末尾的值参数即可得到可复用的函数,唯一的例外是 random(),它需要传入 true。

它产出什么

  • 当你传入 value 参数时,直接返回转换后的值
  • 一个可复用的函数,用于对之后传入的值进行 clamp、映射、归一化或吸附处理
  • 一个元素相同但顺序随机打乱的新数组
  • 一个限定范围的选择器函数,只会在给定元素或 ref 内查找元素
查看示例提示词 ↗

工作方式

  1. 01
    辅助函数都挂在 gsap.utils 上

    这些 utils 都是无需注册的纯辅助函数,可以在任何由 JS 驱动 GSAP 的地方调用:tween 变量、ScrollTrigger 或 Observer 回调中均可使用。

  2. 02
    把值放在最后传入,立即得到结果

    大多数 util 会先接收配置参数,最后一个参数才是要转换的值,并立即返回转换结果。

  3. 03
    不传该值即可得到函数形式

    省略最后的值参数,util 就会返回一个函数,供你之后传入具体值调用,这样一份配置就能服务于多个不同的值。

  4. 04
    记住 random() 的模式是反过来的

    random() 的可复用形式并不依赖省略参数;你需要把 true 作为最后一个参数传入,才能得到一个每次调用都返回新值的函数。

  5. 05
    snap 也可以直接在 tween 中设置

    对于基于网格或步进的运动,你可以直接在 tween 变量中传入 snap,而不必先调用该 util。

  6. 06
    用 pipe 串联多个转换

    pipe 会从左到右组合函数,因此可以把 normalize 和 snap 组合成单个函数,直接在 tween 或回调中使用。

02 找到适合场景

何时使用 gsap-utils Skill

当工作涉及此类动效和视频时,在 Claude Code 或 Codex 中使用 gsap-utils skill。以下适配范围和限制取自该 skill 自身文件。

适合场景

  • 将 scroll 位置、0-1 的进度值或其他输入区间转换为动画区间
  • 在 tween 内按网格或固定步进进行动画
  • 用 wrap 和 wrapYoyo 处理无限滚动或其他循环取值场景
  • 一次性将 scale、opacity、x 或 delay 等值分配到多个元素上
  • 在交错排列元素之前随机打乱它们的顺序

了解边界

  • 诸如 CustomEase 之类的缓动工具,该文件将其归入 gsap-plugins 而非 gsap.utils
  • 覆盖 utils 或依赖未文档化的行为
  • 构建动画本身,该文件将其与 gsap-core、gsap-timeline 和 gsap-scrolltrigger 配对

需要提供的信息

  • 你想要转换的值将它作为最后一个参数传入即可立即得到结果;省略它并稍后将值提供给返回的函数。
  • selector() 的作用域元素或 ref传入一个 DOM 元素或框架 ref,使返回的选择器函数只匹配其后代元素。
  • splitColor 的颜色字符串rgb()、rgba()、hsl()、hsla()、十六进制及命名颜色都可用;将第二个参数传入 true 可改为获取 HSL 分量。
  • 一个 distribute 配置,所有键均为可选提供诸如 base、amount 或 each、from、grid、axis 与 ease 的分布设置,留空则使用默认值。

03 Skill 内部

gsap-utils skill 赋予 Claude Code 与 Codex 的规则

SKILL.md 为 Agent 设定的 6 条具体指令、默认值与边界——文件中真正改变结果的那部分。

  1. 范围重复使用时省略该值

    当同一范围或配置被重复使用时,比如在滚动处理函数或 tween 回调中,应保留返回的函数,而不是每次调用都重新构建配置。

  2. 在 tween vars 中使用随机字符串形式

    将 "random(-100, 100)"、"random(-100, 100, 5)" 或 "random([0, 100, 200])" 写作属性值;GSAP 会针对每个目标对该字符串求值。

  3. 对齐网格用 snap,其余用 toArray

    对网格对齐或基于步长的值使用 snap,只要 GSAP 或你自己的代码需要从选择器或 NodeList 得到真正的数组,就使用 toArray。

  4. 在组件内部限定选择器作用域

    调用 gsap.utils.selector(scope),使像 ".box" 这样的选择器只匹配该容器或 ref 的后代元素,而不是整个文档。

  5. amount 或 each,二者不可兼得

    在 distribute 配置中,amount 将总量分配到所有目标上(100 个目标上的 amount 为 1 时间隔为 0.01),而 each 为每个目标设置固定步长,例如 0、1、2、3。

  6. mapRange 与 normalize 仅适用于数字

    不要指望它们能处理单位;当单位重要时,请改用 getUnit 或 unitize。

04 投入使用

在 Claude Code 或 Codex 中安装 gsap-utils

一条 npx skills add 命令,然后在你的 Agent 中执行第一个任务和对结果的清单检查。

将 gsap-utils 添加到 Claude Code、Codex 或你的 Agent

在你的项目中运行;安装程序会询问要把它添加到哪个 Agent。

Terminal
npx skills add https://github.com/greensock/gsap-skills --skill gsap-utils

针对 skills/gsap-utils/SKILL.md 的通用 skills CLI 形式;该仓库可能记录了自己的路径。

给 Skill 一个首次动效和视频任务

按 skill 自身的术语撰写;把括号中的部分换成你的内容。

Starter prompt
Use gsap.utils to drive a [scroll-linked effect] in [my component]: map the ScrollTrigger progress from 0-1 to 0-360 and snap the result to the nearest 5, then set the starting x of each [card] with the string form "random(-100, 100, 5)". Scope the selectors to the [container] ref with gsap.utils.selector so they do not match the whole document.

来源:依据 SKILL.md,按 skill 自身的术语撰写。

检查首次结果

SKILL.md 本身如何描述正确的结果:

  • 将一个示例调用与文档化的结果进行比较,例如 mapRange(0, 100, 0, 500, 50) 应得到 250
  • 在范围的两端测试 wrap,以确认循环结果正确
  • 传入容器作为 toArray 的第二个参数,确认结果的作用域是受限的
  • 检查 RGBA 颜色是否返回四个元素而不是三个
  • 确认 getUnit 返回单位字符串,对于无单位数字则返回空字符串

在 OpenDesign 中,gsap-utils 已内置:Plugins → Skills,在顶部栏中选择它即可。

05 开源、可追溯

来源、许可与验证

本页面事实的来源,以及最后检查时间。

Author
GreenSock
Repository
github.com/greensock/gsap-skills 分支 main
Skill 文件
skills/gsap-utils/SKILL.md 验证时记录的内容校验和;commit aed9cfd
License
MIT 来自 LICENSE;SKILL.md 注明「MIT」。
仓库星标数
15,248 GitHub 快照取自 2026-09-14,针对整个 greensock/gsap-skills 仓库,该仓库在本目录中包含 8 个 Skill。不是 gsap-utils 的评分或使用计数。
已由 OpenDesign 验证
2026-09-14 已检查源文件、路径、许可证文本和星标数。已捆绑在 OpenDesign 主版本中(检查于 2026-08-28);此页面尚未记录实际运行。
Skill 自身的描述
"GSAP 官方 Skill,用于 gsap.utils——clamp、mapRange、normalize、interpolate、random、snap、toArray、wrap、pipe。当用户询问 gsap.utils、clamp、mapRange、random、snap、toArray、wrap 或 GSAP 中的辅助工具时使用。"

来自 SKILL.md 的前置描述。完整文件约 12,051 字符。在 GitHub 上阅读完整文件。

GSAP Utils

在真实的动效与视频任务中运行 gsap-utils。

gsap-utils Skill 内置于 OpenDesign 中。下载应用,在 Plugins → Skills 中选择该 Skill,粘贴上面的提示词,在结果生成前阅读计划。

终端
npx skills add https://github.com/greensock/gsap-skills --skill gsap-utils