Ae 表达式语言引用：Property

Property（属性及方法）组中的方法和属性，可用于查看或操作属性的关键帧、取值、时间采样、循环与平滑等方面的信息。通过这些方法，可以实现复杂的动画逻辑和自定义行为，例如通过 loop* 系列方法重复关键帧动画，通过 wiggle 或 smooth 制作随机或平滑的动态效果，通过 valueAtTime 和 velocityAtTime 等进行更精确的时间操作，等等。

value

获取属性在当前时间的值。

返回值 ：Number、Array 或 String，具体取决于属性类型。例如，位置属性通常返回二维或三维数组，旋转属性返回数值，不透明度返回数值，文本属性可能返回字符串。

应用：

// 示例 1：获取当前属性并加以改动
value + 10;

//示例 2：使用另一个属性进行混合
value * thisComp.layer("Control").effect("滑块控制")("滑块");

valueAtTime(t)

获取属性在指定时间点的值。

参数 ：

t ：Number，要采样的时间，以秒为单位。

返回值 ：与 value 相同类型，可以是 Number、Array 或 String，具体取决于属性类型。

应用：

// 示例 1：假设在 0、1、2、3 秒处设置了四个关键帧，随机在这四个时间点的关键帧中选择属性值。
randomValue = Math.floor(Math.random() * 4);
ransform.rotation.valueAtTime(randomValue);

// 示例 2：让属性等于1秒前的值
valueAtTime(time - 1);

// 示例 3：为形状图层设置“旋转”关键帧动画并添加表达式，。之后，复制图层多次。
valueAtTime(time - index/10)

velocity

获取属性在当前时间的“速度”或“速率”值。

对于时域属性（如透明度），它表示数值随时间的变化速率。

对于空间属性（如位置），它表示切线向量（X、Y、Z 的变化速率）。

返回值 ：Number 或 Array 。如果是数值属性（如不透明度），返回一个数值；如果是空间属性（如位置），返回一个与其维度对应的数组。结果与属性的维度相同，且根据运动方向会出现负值的速度。

应用：

// 示例 1：返回在 x 轴上的运动速度
thisComp.layer("mediaTEA").transform.position.velocity[0]

// 示例 2：可以根据当前属性的速度进一步调整动画，从而实现惯性或动力学效果。
var v = velocity;
value + v; // 根据速度来改变属性，比如给位置增加动力学效果

velocityAtTime(t)

获取属性在指定时间点的“速度”或“速率”值。

参数 ：

t ：Number，要采样的时间，以秒为单位。

返回值 ：与 velocity 返回相同类型，可为 Number 或 Array，取决于属性类型。

应用：

// 示例 1：取比当前时间早 0.1 秒处的速度，用于延迟动画
velocityAtTime(time - 0.1);

// 示例 2：检测一段时间前属性的变化速率
prevVel = velocityAtTime(time - 0.5);
// 如果在 0.5 秒前速度较大，当前做某些处理
preVel<10 ? value - 10 : value + 10;

speed

获取属性在当前时间的“速度标量”，即一个正数值表示属性变化的速率。仅适用于空间属性（如位置） 。

返回值 ：Number，表示属性在当前时间的变化速率（标量），不含方向信息。

应用：

// 示例 1：让缩放属性随着位置属性的速度而变化，速度越快，变得越小。
var s = position.speed/20;
value - [s,s]

// 示例 2：在速度较小时添加缓动
if (speed < 5) {
// 当运动速度较小时，减小振幅
wiggle(2, 10);}
else {
wiggle(5, 20);}

speedAtTime(t)

获取属性在指定时间点的速度标量（正数），仅适用于空间属性（如位置）。

参数 ：

t ：Number，要采样的时间，以秒为单位。

返回值：Number，表示指定时间点的属性变化速率。

应用：

// 示例 1：统计过去某时刻的运动速度
var spd = speedAtTime(time - 0.2);
// 根据过去的速度决定当前操作
spd > 10 ? 100 : 50;

// 示例 2：将属性按照过去速度的2倍进行延后动画效果，适用于惯性或拖尾动画
speedAtTime(time - 0.1) * 2;

wiggle(freq, amp, octaves=1, amp_mult=0.5, t=time)

让属性值随时间按指定的频率和幅度进行随机变化。

参数 ：

freq ：Number，频率，即，每秒抖动的次数。

amp ：Number，振幅，即，每次抖动的最大偏移量。

基于原属性值进行正、负摆动。比如，旋转属性值为 100，当 amp 设为 50 时，旋转属性值将在 50 ~ 150 之间随机摆动。

octaves ：可选，Number，叠加噪声的层数，默认值 1。

用于控制抖动的复杂程度。每增加一个 octave，都会在 freq 上叠加更高频率的细节噪声，使得 wiggle 看起来更不规则。

amp_mult ：可选，Number，叠加噪声衰减，默认值 0.5。

指的是每增加一层 octave，振幅递减的倍数。范围在 0 ~ 1 之间。接近 1 时，细节越多，变化更突兀。接近 0 时则细节越少，抖动更平滑。

t ：可选，Number，计算起点的时间，默认为 time，表示随时间变化。

如果希望输出成为在不同时间采样的属性值的摆动，请使用此参数。比如设为 5 时，将仅使用第 5 秒的属性值来摆动。

返回值： 与属性的类型一致，可为 Number 或 Array。

应用：

 //示例 1：每秒5次抖动，抖动幅度约20单位，可用于位置等二维或三维属性 
 wiggle(5, 20); 
 
 //示例 2：按相同值摆动两个维度
 v = wiggle(5, 10);   
 [v[0], v[0]] 
 
 //示例 3：只在 Y 轴上摇摆
 w = wiggle(3,50);   
 [value[0],w[1]]; 
 
 //示例 4：每秒产生约 5 次摆动，平均大小约 20 像素。除了主要摆动之外，其他两个级别的详细摆动发生的频率为每秒 10 次和 20 次摆动，各自的大小为 5 和 10 像素
position.wiggle(5, 20, 3, .5)

temporalWiggle(freq, amp, octaves=1, amp_mult=0.5, t=time)

temporalWiggle 并非对属性的值进行抖动，而是对时间采样进行抖动。也就是说，属性本身必须已经动画化，否则无意义。

参数 ：

freq ：频率，即，每秒抖动的次数。

amp ：振幅，表示时间范围。

octaves ：附加噪声层数。

amp_mult ：每增加一层噪声，振幅的递减倍数。

t ：可选，时间起点，默认当前时间 time。

返回值 ： 与属性类型相同，可为 Number 或 Array 。 因为它采样了“随机化时间”的属性值。

应用：

//示例 1：只更改采样时间而不是值。
scale.temporalWiggle(5, .2)

//示例 2：在关键帧基础上随机化时间采样
scale.temporalWiggle(5, .2);

// 示例 3：让透明度在关键帧时间周围随机波动
opacity.temporalWiggle(2, 0.5);

smooth(width=.2, samples=5, t=time)

平滑属性在一定时间范围内的值，过滤掉短时尖峰。

参数 ：

width ：Number，以秒为单位的时间范围，默认为 0.2。

samples ：Number，取样次数，默认为 5。为更大的平滑度可使用更大的值，但性能会下降。

t ：Number，可选，表示时间起点，默认当前时间 time。

返回值 ： 与属性和类型一致，返回平滑后的值，可能是 Number 或 Array 。

应用：

//示例 1：在 0.1 秒的时间窗口内，取 5 次样本，对位置进行平均过滤，减少抖动
position.smooth(.1, 5)

//示例 2：对音频振幅进行平滑，防止过于尖锐的音频峰值影响动画
var amp = thisComp.layer("音频振幅").effect("两个通道")("滑块");
amp.smooth(0.2, 5);

loopIn(type="cycle", numKeyframes=0)

用于设置关键帧动画的入点循环。即，从图层的入点开始重复播放指定的动画段，直到第一个关键帧。

指定动画段的界定方法是：从第一个关键帧开始数，比如 loopIn("cycle", 1) 表示从第 1 个关键帧到第 2（ numKeyframes + 1 ）个关键帧之间为要重复播放的指定动画段。

参数 ：

type ：String，可选，指定循环方法，默认值为"cycle"。

-- "cycle" ： 重复播放指定动画段，类似于 4321 4321 的循环播放。

-- "pingpong" ：往返 播放指定动画段，类似于 1234 4321 的循环播放。

-- "offset" ：将第一个关键帧与 第二个关键帧的变化（偏移）值重复叠加到每次循环，从入点开始并从最后一次循环开始播放，类似于 (1+1.3n)(1+1.2n)(1+1.1n)(1)的递减循环。

-- "contiune" ：此方法下，无 numKeyframes 参数，动画会按照第一个动画段的速度和方向并以其变化量（前面两个关键帧）持续循环，从入点开始并从最后一次循环开始播放，类似于 (1+1.3)(1+1.2)(1+1.1)(1)。

numKeyframes ：Number，可选，指定要参与循环的动画段数，0（默认）表示从第 1 个关键帧到最后一个关键帧之间的动画段。1 表示从第 1 个关键帧到第 2 个关键帧之间的 1 段动画，2 表示从第 1 个关键帧到第 3 个关键帧之间的 2 段动画。

返回值：与属性类型一致，返回基于指定循环规则的属性值。

应用：

为确保入点循环动画结束后与第一个关键帧无缝衔接，loopIn 会根据参数的设置计算出入点时属性的值。

//示例 1：以下写法，意义一致。不断重复从第一个关键帧到最后一个关键帧的动画
loopIn(type="cycle", numKeyframes=0);
loopIn(type="cycle");
loopIn("cycle");
loopIn();

//示例 2：从图层入点开始，循环播放第1个关键键到第2个关键帧之间动画段落
loopIn("cycle", 1);

//示例 3：从图层入点开始，往返播放第1个关键键到第3个关键帧之间动画段落
loopIn("pingpong",2);

loopOut(type="cycle", numKeyframes=0)

用于设置关键帧动画的出点循环。即，从最后一个关键帧开始重复播放指定动画段，直到图层出点。

指定动画段的界定方法是：从最后一个关键帧往回数，比如 loopOut("cycle", 1) 表示从倒数第 2 （numKeyframes + 1）个关键帧到最后一个关键帧之间为要重复播放的指定动画段。

参数：

type ：指定循环方法，默认值为"cycle"。

-- "cycle" ：重复播放指定动画段，类似于 1234 1234 的循环。

-- "pingpong" ：往返播放指定动画段，类似于 4321234 的来回循环。

-- "contiune" ：此方法下，无 numKeyframes 参数。以最后一个动画段的速度和方向并以其变化量（最后两个关键帧）持续循环。即，类似于 1234 （4+4.1）（4+4.2）（4+4.3） ... 的重复。

-- "offset" ：第一次循环时会叠加从倒数第 2 个关键帧到最后一个关键帧的变化（偏移）值，第二次循环时再叠加，依次类推，循环动画遵循从倒数第 2 个关键帧到最后一个关键帧同样的速度与方向，类似于 1234（4+4.1n）（4+4.2n）（4+4.3n）...的递增循环。

numKeyframes ：Number，可选，指定要参与循环的动画段数，0（默认）表示从第 1 个关键帧到最后一个关键帧之间的动画段。1 表示从倒数第 2 个关键帧到最后一个关键帧之间的 1 段动画，2 表示从倒数第 3 个关键帧到最后一个关键帧之间的 2 段动画。

返回值：与属性类型一致，返回基于指定循环规则的属性值。

应用：

// 示例 1：循环倒数第2个关键帧到最后一个关键帧之间的动画段落
loopOut("cycle", 1);

// 示例 2：往返循环所有关键帧动画段
loopOut("pingpong");

// 示例 3：按最后一个动画段的方向和速度持续循环
loopOut("continue")

// 示例 3：按最后两个动画段递增循环
loopOut("offset",2)

loopInDuration(type="cycle", duration=0)

用于设置关键帧动画的入点循环。即，从图层的入点开始重复播放指定动画段，直到第一个关键帧。

指定动画段的界定方法是：从第1个关键帧开始计算，比如 loopInDuration("cycle",1)，表示从第 1 个关键帧到其后的 1 秒处的范围作为要重复播放的指定动画段。

参数：

type ：String，选项同 loopIn 方法。

duration ：Number，要循环的时间长度，以秒为单位。默认值为 0，意味着要重复的指定动画段是，从第 1 个关键帧到图层出点。为 2 时，表示第 1 个关键帧到它之后两秒的范围。

返回值：与属性类型一致，返回基于指定循环规则的属性值。

应用：

为确保入点循环动画结束后与第一个关键帧无缝衔接，loopInDuration 会根据参数的设置计算出入点时属性的值。

// 示例 1：重复播放从第一个关键帧开始的 1 秒范围内的动画段
loopInDuration("cycle", 1);

// 示例 2：将第一个关键帧开始的 2 秒范围内的动画段落进行 “乒乓” 循环
loopInDuration("pingpong", 2);

loopOutDuration(type, duration)

用于设置关键帧动画的出点循环。即，从最后一个关键帧开始重复播放指定动画段，直到图层出点。

指定动画段的界定方法是：从最后一个关键帧往回计时，比如 loopOutDuration("cycle", 2) 表示从最后一个关键帧开始倒数 2 秒处到最后一个关键帧之间作为要重复播放的指定动画段。

参数：

type ：String，选项同 loopOut 方法。

duration ：Number，要循环的时间长度，以秒为单位。默认值为 0，意味着要重复的指定动画段是，从图层入点到最后一个关键帧。为 1 时，表示从最后一个关键帧倒数 1 秒处到最后一个关键帧之间的范围。

返回值：与属性类型一致，返回基于指定循环规则的属性值。

应用：

// 示例 1：反复循环最后一个关键帧往前 1 秒区间的动画段
loopOutDuration("cycle", 1);

// 示例 2：将最后一个关键帧往前 2 秒区间的动画段按递增方式进行循环
loopOutDuration("offset", 2);

key(index)

获取属性在某个关键帧（或标记）的信息对象。

参数：

index ：Number，指定关键帧的序号（从 1 开始）。

返回值：Object。对于标记（Marker）属性，会返回 MarkerKey 对象；对于数值属性，会返回 Key 对象。

应用：

//示例 1：返回位置属性的第一个关键帧的时间
transform.position.key(1).time;

//示例 2：返回位置属性的第一个关键帧的值
thisLayer.position.key(1).value

//示例 3：图层的第2个标记的时间
thisLayer.marker.key(2).time

key(markerName)

仅适用于标记属性，根据标记名来获取对应的 MarkerKey 对象。

参数：

markerName ：String，标记的名称。其实就是标记的注释内容。

返回值：返回一个 MarkerKey 对象，包含此标记的信息（如时间、注释等）。

应用：

//示例：获取名为 “图层标记1” 的时间
thisLayer.marker.key("图层标记1").time

nearestKey(t)

获取在指定时间点 t 附近的关键帧（或标记）对象。即找到最接近 t 时刻的关键帧或标记。

参数：

t ：Number，指定时间点，以秒为单位。

返回值：对于标记（Marker）属性，会返回 MarkerKey 对象；对于数值属性，会返回 Key 对象。

应用：

// 示例 1：获得最接近1秒时的关键帧的值
thisLayer.transform.position.nearestKey(1).value

// 示例 2：持续获得最接近的标记的注释
thisLayer.marker.nearestKey(time).comment

// 示例 3：检测是否接近某个关键帧，并作相应处理
var result = value; // 默认使用当前属性值
if (thisProperty.numKeys > 0) {
var nKey = thisProperty.nearestKey(time); // 获取最近的关键帧
if (Math.abs(nKey.time - time) < 0.1) {
result = wiggle(5, 50); // 只有接近关键帧时才应用 wiggle
}
}
result;  // 确保返回值

numKeys

返回某个属性的关键帧总数，或者对于标记属性则返回标记的总数。

返回值：Number，表示关键帧或标记数量。

应用：

// 示例 1：返回当前属性的关键帧数目
x = thisProperty.numKeys;

// 示例 2：循环读取所有关键帧的时间并把它们拼接为字符串
var n = transform.position.numKeys;
var times = "";
for (var i = 1; i <= n; i++) {
times += "Key " + i + ": " + transform.position.key(i).time + "\n";
}
times;

// 示例 3：根据关键帧是否存在决定是否执行后续动画逻辑
if (thisProperty.numKeys > 0) {
// 有关键帧时的处理
}
else {
// 没有关键帧时的处理
}

name

获取当前属性或属性组的名称字符串。

返回值：String，当前属性或属性组的名称。

应用：

// 示例 1：输出当前属性的名称
thisProperty.name;

// 示例 2：根据属性名称来执行不同的表达式逻辑
if(transform.rotation.name.trim() === "旋转")
{
// 如果名称是 "旋转"，执行某些操作
}

active

检查属性是否在当前上下文中处于激活状态。

返回值：Boolean。true 表示激活，false 表示未激活。

应用：

// 示例：
thisProperty.active

enabled

检查属性是否启用。

返回值：Boolean。true 表示启用，false 表示禁用。

应用：

// 示例：
thisComp.layer("形状图层 1").effect("高斯模糊")("重复边缘像素").enabled

propertyGroup(countUp=1)

获取相对于当前属性所在的父级（或更高层级）属性组对象。适用于在表达式中进行层级引用时使用。

参数：

countUp ：Number，表示向上查找多少级的属性组。默认值为 1，表示向上查找一层。为 2 时返回其上一级的属性组（上二级对象），以此类推。

返回值：返回一个 Group 对象，表示属性所处的父级属性组。

应用：

//示例 1：propertyGroup 的 numProperties 方法返回属性组中属性的数目。
var pGroup = thisProperty.propertyGroup(1);
pGroup.numProperties;

//示例 2：可用于在表达式中相对地引用到父级或更高层级的属性，适合在复杂图层层级里。
var pGroup = thisProperty.propertyGroup(2);
pGroup.transform.rotation

propertyIndex

返回当前属性在其父属性组中的索引值（以 1 为开始）。

返回值：Number，表示当前属性在父属性组中的位置索引。

应用：

//示例 1：旋转属性所在上级对象依次为：变换组（1），椭圆 1 （2），内容（3） 
r = thisComp.layer("形状图层 1").content("椭圆 1").transform.rotation
r.propertyGroup(2).propertyIndex; //椭圆 1 在“内容” 里的序号 

//提示 ：在图层对象（最高级别）里面的“内容” 序号总为 2，因为它前面还有一个隐藏的 Marker 属性组。

//示例 2：输出当前属性在同一级属性列表中的位置
var idx = thisComp.layer("形状图层 1").content("椭圆 1").transform.rotation.propertyIndex;
var gName =thisComp.layer("形状图层 1").content("椭圆 1").transform.rotation.propertyGroup(1).name;
"此属性是 No. " + idx + " 在" + gName + "属性组中";

“点赞行美意，赞赏是鼓励”