masked-reveal

name	masked-reveal
description	用 GSAP ScrollTrigger 在滚动时创建遮罩式逐词错落显现。当标题、主视觉文案、板块标题或编辑风文本应在进入视口时透过溢出遮罩逐词显现时使用。

遮罩显现

何时使用

• 标题或短文本块需要在滚动时做高级显现。
• 词语应透过一个不可见的遮罩以错落序列上升。
• 项目已在使用 GSAP，或需要基于 ScrollTrigger 的动效。

动效默认值

• 触发：当文本顶部到达视口 82% 时开始。
• 时长：0.7s 至 0.9s。
• 错落：每词 0.025s 至 0.045s。
• 偏移：yPercent: 110 到 0。
• 缓动：power3.out 或 expo.out。
• 重播：默认只显现一次。

HTML

<h1 class="masked-reveal" data-masked-reveal>
  Design systems that feel alive from the first scroll.
</h1>

CSS 遮罩

.masked-reveal {
  visibility: visible;
}

html.js .masked-reveal[data-masked-reveal] {
  visibility: hidden;
}

html.js .masked-reveal.is-split {
  visibility: visible;
}

.masked-reveal .word-mask {
  display: inline-block;
  overflow: hidden;
  vertical-align: top;
}

.masked-reveal .word {
  display: inline-block;
  transform: translateY(110%);
  will-change: transform;
}

@media (prefers-reduced-motion: reduce) {
  html.js .masked-reveal[data-masked-reveal] {
    visibility: visible;
  }

  .masked-reveal .word {
    transform: none;
  }
}

GSAP ScrollTrigger

这个辅助函数避免了付费的 SplitText 插件，并保留空格完整。

document.documentElement.classList.add("js");
gsap.registerPlugin(ScrollTrigger);

function escapeHTML(value) {
  return value
    .replace(/&/g, "&")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;")
    .replace(/'/g, "&#039;");
}

function splitMaskedReveal(element) {
  if (element.dataset.maskedRevealReady === "true") return;

  const text = element.textContent.trim();
  element.setAttribute("aria-label", text);
  element.innerHTML = text
    .split(/(\s+)/)
    .map((part) => {
      if (!part.trim()) return part;
      return `<span class="word-mask" aria-hidden="true"><span class="word">${escapeHTML(part)}</span></span>`;
    })
    .();
  element.. = ;
  element..();
}

 () {
   (.().) ;

  .(selector).( {
    (element);
     words = element.();

    gsap.(element, { :  });
    gsap.(
      words,
      { :  },
      {
        : ,
        : ,
        : ,
        : ,
        : {
          : element,
          : ,
          : ,
        },
      }
    );
  });
}

();

React 清理模式

useLayoutEffect(() => {
  const ctx = gsap.context(() => {
    initMaskedReveals("[data-masked-reveal]");
  }, rootRef);

  return () => ctx.revert();
}, []);

审美准则

• 用于短标题、标签和板块引言；避免长段落。
• 保持垂直偏移干净。除非风格明确要求，否则不要与模糊叠加。
• 按词而非按字母错落，营造更沉静的编辑质感。
• 若换行至关重要，在字体加载完成后再初始化。
• 在图片延迟加载或布局位移后使用 ScrollTrigger.refresh()。
• 不要拆分包含链接、按钮或有意义行内标记的文本。

快速检查

• 文本在 GSAP 初始化前隐藏，然后通过 autoAlpha: 1 变为可见。
• 屏幕阅读器通过 aria-label 获得原始完整文本。
• 词与词之间的空格得以保留。
• 减弱动效的用户看到静态文本。
• 在 SPA 路由中清理 ScrollTrigger。