Ruffle ruffle-demo构建可嵌入网站的 Flash 播放器演示页与本地调试环境【免费下载链接】ruffleA Flash Player emulator written in Rust项目地址: https://gitcode.com/GitHub_Trending/ru/ruffleruffle-demo 是 Ruffle Web 端web/packages/demo内置的官方示例工程它演示了如何将 Ruffle 播放器嵌入一个 React 网站同时也是一套开箱即用的本地测试环境开发者构建完 ruffle-web 后一条npm run demo命令即可启动本地服务器验证 SWF 的播放效果。读完本文你将掌握演示页的完整运行流程、swfs.json示例片单的配置规范、字段在源码中的实际消费方式以及播放器封装层加载、防重入、拖拽、元数据的实现细节。1. 定位嵌入示例与本地测试场双重身份web/packages/demo/README.md 对 ruffle-demo 的定义有两条主线嵌入参考展示如何在自己的网站中引入 Ruffle 播放 SWF本地测试开发者在本地跑 Ruffle Web 构建产物时用它作为最顺手的前端容器。README 还提到一个托管版本ruffle.rs 上的 hosted demo其代码与本目录完全一致且每晚自动更新——这意味着你本地这份代码就是线上演示页的源头。工程元信息见 package.json包名ruffle-demo版本0.6.0依赖react、react-dom与ruffle-coreworkspace 内部包即 Ruffle 的 Web 前端封装构建工具为 Vite 8 TypeScript vitejs/plugin-react。顶层 web/package.json 以 npm workspaces 管理四个包packages/core、packages/demo、packages/extension、packages/selfhosted其中与 demo 直接相关的脚本是build: npm run build --workspaceruffle-core npm run build --workspaceruffle-demo --workspaceruffle-extension --workspaceruffle-selfhosted, demo: npm run preview --workspace ruffle-demo可以看出npm run demo的本质是对ruffle-demoworkspace 执行vite preview即预览vite build的静态产物。2. 目录结构与文件职责demo 包的结构很小每个文件职责明确web/packages/demo/ ├── index.html # 入口 HTML挂载 #root 并引入 /src/main.tsx ├── package.json # 依赖与 npm scriptsdev/build/preview ├── vite.config.ts # Vite 配置React 插件 相对 base ├── tsconfig.json ├── public/ # 静态资源logo-anim.swf、图标、字体等 └── src/ ├── main.tsx # 安装 Ruffle 并渲染 App传入基础播放配置 ├── App.tsx # 顶层组件导航栏 播放容器 元数据面板 ├── player.tsx # Player 封装组件创建播放器/加载/防重入 ├── navbar.tsx # 顶栏URL 输入、本地文件选择、元数据/重加载按钮 ├── navbar/ │ └── samples.tsx # 示例片单swfs.json的加载与下拉选择 ├── metadata.tsx # 电影元数据面板 ├── index.css / common.css / lato.css └── vite-env.d.ts其中 index.html 只是一个 14 行的标准 Vite 入口vite.config.ts 仅启用 React 插件并设置base: 相对部署路径便于放在任意子目录。3. 本地运行演示页README 给出的操作步骤是先按 web 端文档构建 ruffle-web即 web/README.md 的 Building from source 章节产物会生成 workspace 包ruffle-core在web目录下执行npm run demo命令会启动一个本地 web 服务器并在控制台打印地址浏览器访问即可通常是http://localhost:41734173 是vite preview的默认端口。从源码看这条链路的具体落点web根目录的demo脚本 →npm run preview --workspace ruffle-demodemo 包的preview脚本是vite preview见 package.json它需要先用tsc vite build产出静态文件页面入口 src/main.tsx 在渲染 React 树之前调用Setup.installRuffle(local)把 Ruffle 播放器脚本安装到全局window.RufflePlayerlocal参数表示使用本地相对路径加载 wasm 资源而非 CDN。4. 配置示例片单swfs.json 完整规范README Configuring the demo 一节是本文的核心。demo 支持提供一个示例 SWF 片单用户可以在页面顶部的下拉框中选择不同的 SWF 来播放。这在维护一批常用测试 SWF、或对外展示各种游戏/动画时非常有用Ruffle 官方团队自己就用它来展示。用法在 demo 目录即public/资源可访问的位置新增文件swfs.json内容结构如下完整示例继承自 README{ swfs: [ { location: logo-anim.swf, title: Ruffle Logo, author: Ruffle contributors, authorLink: https://ruffle.rs, config: { autoplay: on, backgroundColor: #31497D, letterbox: off, unmuteOverlay: hidden } }, { location: swfs/bitey1.swf, title: Bitey of Brackenwood, author: Adam Phillips, authorLink: https://bitey.com, type: Animation }, { location: swfs/alien_hominid.swf, title: Alien Hominid, author: Tom Fulp and Dan Paladin, authorLink: https://www.newgrounds.com, type: Game } ] }4.1 字段说明结合 src/navbar/samples.tsx 中定义的DemoSwf接口各字段含义如下字段类型必填说明locationstring是SWF 相对路径相对于部署根目录如swfs/xxx.swftitlestring否下拉框中显示的名称authorstring否作者名选中时显示在作者链接区authorLinkstring否作者主页链接target_blank打开typeAnimation \| Game否分类带type的条目会归入对应的optgroup不带type的条目作为顶层选项configConfig.BaseLoadOptions否该 SWF 专属的播放配置加载时与全局基础配置合并源码中的类型定义与 README 示例一一对应// web/packages/demo/src/navbar/samples.tsx export interface DemoSwf { location: string; title?: string; author?: string; authorLink?: string; config?: Config.BaseLoadOptions; type?: SampleCategory; // Animation | Game }4.2 config 字段的取值示例里出现的autoplay: on、letterbox: off、unmuteOverlay: hidden、backgroundColor: #31497D都是 ruffle-core 的BaseLoadOptions字段。可以从 src/main.tsx 的全局基础配置交叉印证这些字段的枚举风格ruffleBaseConfig{{ autoplay: Config.AutoPlay.On, unmuteOverlay: Config.UnmuteOverlay.Hidden, logLevel: Config.LogLevel.Warn, letterbox: Config.Letterbox.On, forceScale: true, forceAlign: true, }}即页面级默认letterbox: On上下加黑边保持原始宽高比而单个示例如logo-anim.swf可以在swfs.json里覆写为off。加载时两者的合并顺序见 5.2 节。4.3 片单的加载与深链swfs.json的消费逻辑在 samples.tsx 的useEffect中行为要点页面初始化时fetch(swfs.json)若请求失败或文件不存在片单下拉框整体隐藏容器加hiddenclassdemo 退化为纯拖拽/URL 加载模式——所以该文件是可选增强不是启动必需若存在 URL 参数?filelocation会按location匹配对应条目并自动播放匹配失败则回退到第 0 条选中某条时也会用window.history.replaceState把?file...写回地址栏实现可分享的深链渲染时按type生成optgroupAnimations / Games 两个分组见SampleCategories映射无type的条目直接平铺在分组之前选中条目后作者信息区显示author并链接到authorLink。5. 播放器封装player.tsx 与 App.tsx 的协作5.1 播放器的创建与销毁src/player.tsx 中的Player组件是嵌入 Ruffle 的核心对应如何在自己的网站中引入 Ruffle这一主线componentDidMount() { this.player (window.RufflePlayer as Setup.PublicAPI) .newest()! .createPlayer()!; this.player.id player; this.player.addEventListener(loadedmetadata, () { if (this.props.onLoadedMetadata) { this.props.onLoadedMetadata(this.player!.ruffle().metadata!); } }); this.container.current!.appendChild(this.player); }要点依赖main.tsx里Setup.installRuffle(local)安装好的全局window.RufflePlayernewest().createPlayer()创建播放器元素后挂载到容器 div监听loadedmetadata事件把元数据回传给App供元数据面板展示componentWillUnmount中调用this.player?.remove()完成清理。5.2 三种加载方式与防重入保护Player封装了三种入口覆盖示例片单 / 手动 URL / 本地文件三条路径loadUrl(url: string, options: Config.BaseLoadOptions) { if (!this.isLoading) { this.isLoading true; this.player?.ruffle() .load({ url, ...this.props.baseConfig, ...options }) .finally(() { this.isLoading false; }); } } loadFile(file: File) { // new Response(file).arrayBuffer() 读取文件内容 // 然后 load({ data, ...baseConfig }) } reload() { /* 同样带 isLoading 保护调用 ruffle().reload() */ }值得注意的两处设计配置合并顺序load({ url, ...baseConfig, ...options })——先展开全局baseConfig来自main.tsx的 props再展开options即swfs.json中该条目的config因此片单项配置优先于页面全局配置这正是 4.1 节单条覆写全局的底层依据防重入 hack源码注释明确写道Ruffle 在正在加载一个 SWF 时又加载另一个 SWF时会出问题而 React 的开发模式又会把组件重复挂载以暴露这类 bug因此封装层用isLoading标志把加载串行化finally中复位。reload/loadUrl/loadFile三者共用这一保护。5.3 拖拽上传与 URL 加载App.tsx 通过 props 把交互事件接到Player容器 div 上onDragEnter/onDragLeave/onDragOver/onDrop实现把 SWF 文件拖进窗口即播放——onFileDragDrop从event.dataTransfer.files[0]取文件并调用player.loadFile(...)。navbar.tsx 顶栏则提供URL 输入框allowUrlLoading控制显隐demo 的main.tsx中该项为false即本地 demo 默认不开放任意外网 URL只开示例片单本地文件选择accept.swf,.spl对 iOS 设备有一个特判因 iOS 文件选择器不支持 accept 过滤而省略该属性信息按钮切换元数据面板显隐MetadataPanel重载按钮confirm(Reload the current SWF?)确认后触发reload()。App组件的两个布尔开关allowUrlLoading/allowSampleSwfs决定页面形态这使同一套 demo 代码可以被裁剪成不同功能的嵌入示例。6. 构建、测试与贡献README 最后指出构建、测试或贡献流程统一遵循 web/README.md。可执行的最短路径是按 web 文档完成 ruffle-web 的 wasm 构建生成ruffle-core产物在web目录运行npm run demo启动预览服务器浏览器访问http://localhost:4173如需开发热更新也可以在web/packages/demo内直接跑npm run devVite dev server需要示例片单时按第 4 节规范新增swfs.json并按?filelocation验证深链。7. 小结ruffle-demo 用不到 20 个文件给出了网站嵌入 Ruffle的完整最小实现main.tsx负责安装播放器与全局配置player.tsx封装创建/加载/销毁与防重入navbar提供 URL、文件、示例片单三种来源swfs.json以声明式 JSON 扩展片单并支持按条目覆写播放配置。作为开发者你既可以把它当成本地验证 Ruffle Web 构建的手边测试台也可以把其中的createPlayer()、load({ url, ...config })与loadedmetadata事件监听直接移植到自己的项目里。【免费下载链接】ruffleA Flash Player emulator written in Rust项目地址: https://gitcode.com/GitHub_Trending/ru/ruffle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考