MotionStream

以穩定節奏顯示串流文字，內容一次湧入時也能追上。

WebReact Native數字與文字

動手試試

正在準備範例…

JavaScript 已關閉。下方的程式碼就是完整的範例。

App.jsx

import { useEffect, useRef, useState } from 'react';
import { MotionStream } from '@kkwaenggwari/animated-chorus';
import './styles.css';

const answer =
  'Motion helps people follow change. When a total updates, a rolling number shows which way it moved. ' +
  'When a panel opens, the height that follows its content keeps the reader in place. ' +
  'When an answer arrives in bursts, a steady reveal turns the bursts into reading: nothing waits for the ' +
  'next packet, and nothing is dumped at once. The pace speeds up only when a backlog builds, so the text ' +
  'never falls far behind what the server has already sent.';

// Network-like bursts: long pauses, then a lot of text at once.
const pauses = [300, 1100, 250, 1500, 400, 900];

export default function App({ speed = 90, catchUp = 900, chunk = 160, effect = 'fade' }) {
  const [received, setReceived] = useState(0);
  const [chunks, setChunks] = useState(0);
  const renders = useRef(0);
  renders.current += 1;

  useEffect(() => {
    if (received >= answer.length) return;
    const timer = setTimeout(
      () => {
        setReceived((current) => Math.min(answer.length, current + chunk));
        setChunks((count) => count + 1);
      },
      pauses[chunks % pauses.length],
    );
    return () => clearTimeout(timer);
  }, [received, chunks, chunk]);

  const askAgain = () => {
    setReceived(0);
    setChunks(0);
  };

  return (
    <div className="chat">
      <p className="question">Why does motion help an interface?</p>
      <p className="answer">
        <MotionStream
          text={answer.slice(0, received)}
          speed={speed}
          catchUp={catchUp}
          effect={effect}
        />
      </p>
      <footer>
        <output>
          {chunks} chunks · App rendered {renders.current} times
        </output>
        <button onClick={askAgain}>Ask again</button>
      </footer>
    </div>
  );
}

styles.css

.chat {
  display: grid;
  gap: 16px;
  max-width: 620px;
  margin: 0 auto;
  padding: 24px 20px;
}

.question {
  justify-self: end;
  max-width: 80%;
  margin: 0;
  padding: 10px 16px;
  border-radius: 18px 18px 4px 18px;
  background: #176b52;
  color: #fff;
}

.answer {
  min-height: 180px;
  margin: 0;
  padding: 16px 18px;
  border: 1px solid #cfe8dc;
  border-radius: 18px 18px 18px 4px;
  background: #fff;
  color: #16181d;
  line-height: 1.65;
}

footer {
  display: flex;
  flex-wrap: wrap;
  align-items: center;
  justify-content: space-between;
  gap: 10px;
}

output {
  font:
    600 13px ui-monospace,
    Consolas,
    monospace;
  color: #176b52;
}

footer button {
  min-height: 40px;
  padding: 0 16px;
  border: 1px solid #cfe8dc;
  border-radius: 999px;
  background: #fff;
  font:
    600 14px system-ui,
    sans-serif;
  cursor: pointer;
}

最簡用法

Answer.jsx

<MotionStream text={answerSoFar} initial />

<MotionStream text={answerSoFar}>
  {visible => <Markdown>{visible}</Markdown>}
</MotionStream>

它替你處理的事

一次湧入也能順暢閱讀：文字以每秒 speed 個字元的速度顯示，而不是一塊一塊地跳出來。
積壓的內容會加速顯示，在大約 catchUp 毫秒內全部呈現。
表情符號、旗幟與組合字元絕不會被拆開，只收到一半的表情符號會等待其餘部分。
回答被改寫時，會從共同的開頭繼續，而不是從頭再來。
顯示的字元直接寫入頁面；React 每秒只渲染幾次。

適用情境

聊天中助理的回答。
建置或部署紀錄。
即時字幕。

Props

Prop	型別	預設值	說明
`text`	`string`	`—`必填	目前為止的文字。增加的文字以穩定節奏顯示；被改寫時從共同的開頭繼續。
`speed`	`number`	`90`	基本顯示速度，單位為每秒字元數。
`catchUp`	`number`	`900`	積壓的內容會加速顯示，在大約這麼多毫秒內全部呈現。
`initial`	`boolean`	`false`	掛載時已有的文字也逐步顯示（否則立即顯示）。
`effect`	`'fade' \| 'none'`	`'fade'`	`fade` 讓新字元淡入；`none` 直接顯示。
`children`	`(visible: string) => ReactNode`		接收依節奏輸出之文字的函式，例如用來渲染 Markdown。
`as`	`element`	`'span'`	要渲染的元素。
`onMotionComplete`	`(text) => void`		每當顯示進度追上 `text` 時執行。

其他 props 會傳給渲染的元素，所以 className、style 與事件處理函式照常可用。

Web 與 React Native

在 Web 上，新字元會淡入（effect="fade"），再併入一般的可選取文字。函式形式的子元素會收到依節奏輸出的字串，可用來渲染 Markdown，最多每兩格更新一次。在隱藏的分頁中，所有內容會一次顯示。

在 React Native 上，文字是真正的 Text，不淡入直接顯示。

用到它的範例

聊天回答會收起的建議、以穩定節奏串流的回答，以及會切換的狀態列。MotionStreamMotionListMotionSwapMotionHeight