基础 JavaScript API：createPlayer() 和 load()

什么时候用 JS API

• 自动 polyfill 扫不到某个动态生成的 Flash 元素
• 你想把 Ruffle 嵌到一个自己新建的空 <div> 里，完全不依赖旧 Flash 标签
• 想做多 SWF 管理（一个页面上多个 Flash 组件，各自独立加载）
• 想监听加载成功 / 失败事件来做自定义 UI（比如加载动画、错误提示）

先检查 Ruffle 有没有加载好

在调用任何 API 之前先确认：

if (window.RufflePlayer && window.RufflePlayer.newest) {
  // Ruffle 加载好了
} else {
  console.error("Ruffle 脚本还没加载完！");
}

如果你的脚本在 <script src="ruffle.js"> 之前执行，Ruffle 肯定还没好——要么把 JS 代码移到后面，要么用 DOMContentLoaded / window.onload 包一下。

第一步：获取 Ruffle 构造器

const ruffle = window.RufflePlayer.newest();

newest() 返回当前页面里已加载的最新版本构造器——扩展和网站嵌入脚本可能同时存在，newest() 会选版本号更高那个。

如果你就是想看当前脚本自己的版本，也可以：

const ruffle = window.RufflePlayer.current();

第二步：创建 Player 实例

最简单的形式：

const player = ruffle.createPlayer();

创建出来的 player 只是一个空壳，还没放到 DOM 里。你需要：

const container = document.getElementById("my-flash-container");
container.appendChild(player);

这时候 <div id="my-flash-container"> 里就多了一个 Ruffle 播放器元素。

第三步：加载 SWF

player.load("https://example.org/game.swf");

load() 是异步的——立刻返回，加载在后台进行。你可以等事件：

player.addEventListener("loadedmetadata", () => {
  console.log("SWF 元数据加载好了，舞台尺寸：", player.stageWidth, "x", player.stageHeight);
});
player.addEventListener("play", () => {
  console.log("开始播放了");
});
player.addEventListener("error", (e) => {
  console.error("加载失败：", e.error);
});

完整最小示例

<div id="flash-container" style="width: 800px; height: 600px;"></div>

<script>
document.addEventListener("DOMContentLoaded", () => {
  if (!window.RufflePlayer) {
    console.error("Ruffle 脚本未加载");
    return;
  }
  const container = document.getElementById("flash-container");
  const player = window.RufflePlayer.newest().createPlayer();
  container.appendChild(player);
  player.addEventListener("error", (e) => console.error(e));
  player.load("https://example.org/game.swf");
});
</script>

<script src="https://unpkg.com/@ruffle-rs/ruffle"></script>

常用事件

常用 Player 方法