turn.js 依赖 jQuery 引入与基础翻书效果配置

一、底层依赖机制与脚本引入时序

turn.js 并非一个独立封装的无依赖类库，它通过直接向 jQuery.fn（即 jQuery 的实例原型对象 jQuery.prototype）挂载 turn 方法来实现对 DOM 节点的操作。同时，turn.js 内部依赖 jQuery 抹平的跨浏览器事件绑定（如 mousedown、mousemove、mouseup 及移动端触控事件）和缓动动画计时器。

因此，在浏览器环境加载并执行脚本时，必须严格遵守依赖先后的物理执行顺序。如果颠倒了引用顺序，当浏览器解析 turn.min.js 时，由于全局上下文中尚未声明 window.jQuery 与 window.$，代码会直接抛出不可恢复的运行时错误：Uncaught ReferenceError: jQuery is not defined；若后续代码继续调用 $('#flipbook').turn(...)，则会进一步触发 $(...).turn is not a function 异常。

1.1 依赖库版本选型建议

turn.js 核心版本（turn.js 4th release）开发于 jQuery 1.7+ 黄金时期。在选型配套的 jQuery 版本时需注意：

• 推荐版本（高稳定性）：jQuery 1.8.x 至 1.12.4，或 jQuery 2.x 系列。这一区间的 jQuery 原生包含完整的选择器支持且未移除部分旧版事件机制，与 turn.js 4 完全兼容，无需任何补丁。
• 现代项目（jQuery 3.x）：若由于项目整体依赖必须使用 jQuery 3.x，需注意 turn.js 在部分老版本实现中可能访问了已被 3.x 弃用的内部属性（如 $.browser 或旧版 load 事件别名）。通常建议搭配 jquery-migrate 插件，或者采用社区维护的修复版 turn.js 资源。

1.2 标准 HTML 脚本引入示例

在页面底部（</body> 闭合标签之前）按序载入脚本，或在 <head> 中通过常规同步标签引入：

<!-- 1. 优先加载核心基础库 jQuery -->
<script src="https://cdn.jsdelivr.net/npm/jquery@1.12.4/dist/jquery.min.js"></script>

<!-- 2. 加载依赖 jQuery 原型的翻书插件 turn.js -->
<script src="https://cdn.jsdelivr.net/npm/turn.js@4.1.0/turn.min.js"></script>

<!-- 3. 编写业务初始化脚本 -->
<script>
  $(document).ready(function() {
    // 确保 DOM 树完全构建后再执行初始化
  });
</script>

二、HTML 结构设计与页面划分规则

turn.js 在初始化时会将指定的容器元素识别为翻书视口，并将其直接子级元素（Direct Children）依次抽取映射为翻书页码。理解这种页面划分机制对于避免排版混乱至关重要。

2.1 容器与单页的组织原则

1. 扁平化直系结构：容器内的每一个直接子 <div> 即代表一页（Page 1, Page 2, Page 3...）。子页内部可以自由嵌套复杂的文本、图片与排版元素，但子页本身绝不能被额外的列表标签（如 <ul> 或其他包装 <div>）所隔离。
2. 硬质封面标记（Hard Cover）：为代表封面或封底的子页添加 class="hard"。turn.js 会在内部赋予硬纸板属性，使其翻动时不会出现软纸张的弯曲形变，而是以整块刚体平面进行 3D 旋转。
3. 页数偶数对齐原则：在经典的双页画册模式（display: 'double'）下，除首页（独占右侧封面）和末页（独占左侧封底）外，中间所有内页均为两两并排展示。因此，整个容器的子元素总数量最好保持为偶数。如果内容为奇数，应在尾部手动补齐一个空的 <div>，避免末尾封底被错误识别为右侧内页而造成布局坍塌。

<div id="flipbook">
  <!-- 第 1 页：硬质封面（初始位于视口右半区） -->
  <div class="hard">
    <h1>画册封面</h1>
    <p>企业年刊 / 交互画报</p>
  </div>

  <!-- 第 2 页：内页 1（翻开后展示在左侧） -->
  <div>
    <h2>卷首寄语</h2>
    <p>这里是左侧内页的正文内容...</p>
  </div>

  <!-- 第 3 页：内页 2（翻开后展示在右侧） -->
  <div>
    <h2>目录总览</h2>
    <p>这里是右侧内页的正文内容...</p>
  </div>

  <!-- 第 4 页：硬质封底 -->
  <div class="hard">
    <h3>封底版权信息</h3>
  </div>
</div>

三、关键 CSS 样式配置与版面约束

turn.js 会在初始化瞬间通过 JavaScript 动态计算各页面的绝对坐标并注入 position: absolute，同时建立专门的 .turn-page-wrapper 视口包裹层。为了避免布局计算前页面出现样式闪烁（FOUC）或翻页透光，必须预先配置以下基础 CSS：

/* 翻书总容器必须预先声明确定尺寸与溢出裁剪 */
#flipbook {
  width: 800px;
  height: 500px;
  margin: 40px auto;
  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.15);
  background-color: #FAFAF7;
}

/* 每一个子页必须设置不透明背景，防止翻动时背面文字镜像穿透 */
#flipbook > div {
  background-color: #FFFFFF;
  color: #334155;
  box-sizing: border-box;
  padding: 30px;
  overflow: hidden;
  box-shadow: inset 0 0 15px rgba(0, 0, 0, 0.05);
}

/* 硬封面专属质感 */
#flipbook .hard {
  background-color: #6487A5;
  color: #FFFFFF;
  font-weight: bold;
}

四、JavaScript 基础初始化与核心参数详解

当 DOM 树加载完成且外部资源就绪后，通过 jQuery 选择器获取容器并调用 .turn(options) 方法完成初始化。turn.js 提供了丰富的几何配置项，用于控制画册的物理尺寸、呈现模式和动画触感。

4.1 核心配置参数说明

4.2 标准初始化脚本

$(document).ready(function() {
  $('#flipbook').turn({
    width: 800,              // 双页全展开宽度（单页 400px）
    height: 500,             // 页面高度
    autoCenter: true,        // 封面与封底自动居中
    display: 'double',       // 启用双页跨页模式
    elevation: 50,           // 翻页抬起高度
    gradients: true,         // 呈现光影过渡
    duration: 1000,          // 翻页动画时长（毫秒）
    acceleration: true       // 启用硬件加速
  });
});

五、翻页控制、事件监听与进阶 API 交互

除了让读者直接使用鼠标按住书角拖拽翻页外，在实际项目中通常需要外挂“上一页”、“下一页”、跳转输入框及当前页码指示器。turn.js 将这些功能统一抽象为方法调用与生命周期事件。

5.1 常用操作 API

// 翻到下一页（向前翻动）
$('#flipbook').turn('next');

// 翻到上一页（向后翻动）
$('#flipbook').turn('previous');

// 直接跳转到指定页码（例如跳至第 3 页）
$('#flipbook').turn('page', 3);

// 读取当前正在展示的页码
var currentPage = $('#flipbook').turn('page');

// 获取整本书的总页数
var totalPages = $('#flipbook').turn('pages');

// 缩放书本比例（用于适配移动端响应式，1.0 为原始比例）
$('#flipbook').turn('zoom', 0.8);

5.2 监听翻页事件与更新外部页码

turn.js 提供了 turning（即将翻页）和 turned（翻页动画完成）等核心事件。利用这些事件可以实时同步界面底部状态，甚至在满足特定条件时阻止翻页：

// 监听即将翻页事件
$('#flipbook').bind('turning', function(event, page, view) {
  console.log('即将翻动至第 ' + page + ' 页');
  // 若需限制读者翻阅未解锁内容，可调用：
  // event.preventDefault();
});

// 监听翻页动画落定事件
$('#flipbook').bind('turned', function(event, page, view) {
  // view 数组包含当前视野中可见的页码，例如双页展开时 view 为 [2, 3]
  $('#page-indicator').text('当前页: ' + page + ' / ' + $('#flipbook').turn('pages'));
});

六、常见问题排查与工程实践细节

在不同浏览器环境和网络条件下集成 turn.js 时，开发者常遇到白屏、图片错位或尺寸拉伸等问题。以下按出现频次整理了具体的排查路径与修复对策。

6.1 图片资源未预加载导致尺寸变形

表现：内页包含大图时，页面翻动瞬间内容发生猛烈抽搐，或者初次加载时书本高度被压扁为 0。

原因：$(document).ready 仅等待 HTML DOM 树构建完成，此时页面内的 <img> 资源尚未下载完毕，高度为 0。turn.js 基于空内容计算几何尺寸，后续图片加载完成将撑破预设容器。

解决方案：使用 $(window).on('load', ...) 确保全部静态图片加载完毕后再初始化 turn.js，或者为内页图片显式在 CSS 中锁定宽高比例（如 width: 100%; height: 100%; object-fit: cover;）。

6.2 移动端触控交互失灵或与原生滚动冲突

表现：在手机端或平板电脑触摸屏幕翻页时，整个浏览器视口随之上下晃动，翻页拖拽极易中断。

原因：移动端默认的纵向手势滚动事件（touchmove）捕获并打断了 turn.js 内部的水平拖拽计算。

解决方案：在翻书容器及其包裹区添加 CSS 属性 touch-action: pan-y; 或针对特定区域阻止默认滚动行为，并在小屏设备上将 display 模式动态切换为 'single'。

七、完整可运行综合实例

将上述所有模块整合，以下是一份开箱即用的完整单页示例代码。将其保存为本地 .html 文件并在浏览器中直接打开，即可体验完整的仿真翻书与外部按钮交互：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>turn.js 基础翻书效果完整实例</title>
  <style>
    body {
      background-color: #F1F5F9;
      display: flex;
      flex-direction: column;
      align-items: center;
      padding-top: 50px;
      font-family: sans-serif;
    }
    #flipbook {
      width: 800px;
      height: 500px;
      box-shadow: 0 12px 28px rgba(0,0,0,0.2);
    }
    #flipbook .page {
      background-color: #FFFFFF;
      padding: 30px;
      box-sizing: border-box;
      border: 1px solid #E2E8F0;
    }
    #flipbook .hard {
      background-color: #6487A5;
      color: #FFFFFF;
    }
    .controls {
      margin-top: 25px;
      display: flex;
      gap: 15px;
      align-items: center;
    }
    button {
      padding: 8px 16px;
      border: none;
      background-color: #6487A5;
      color: #fff;
      border-radius: 4px;
      cursor: pointer;
    }
    button:hover {
      background-color: #52728D;
    }
  </style>
</head>
<body>

  <div id="flipbook">
    <div class="hard page"><h2>翻书画册封面</h2></div>
    <div class="page"><h3>第 2 页：内页正文</h3><p>这是左侧展示页。</p></div>
    <div class="page"><h3>第 3 页：图表展示</h3><p>这是右侧展示页。</p></div>
    <div class="hard page"><h2>封底</h2></div>
  </div>

  <div class="controls">
    <button id="prev-btn">上一页</button>
    <span id="page-num">当前：1</span>
    <button id="next-btn">下一页</button>
  </div>

  <script src="https://cdn.jsdelivr.net/npm/jquery@1.12.4/dist/jquery.min.js"></script>
  <script src="https://cdn.jsdelivr.net/npm/turn.js@4.1.0/turn.min.js"></script>
  <script>
    $(document).ready(function() {
      var $book = $('#flipbook');

      $book.turn({
        width: 800,
        height: 500,
        autoCenter: true,
        display: 'double',
        elevation: 50,
        gradients: true
      });

      $('#prev-btn').on('click', function() {
        $book.turn('previous');
      });

      $('#next-btn').on('click', function() {
        $book.turn('next');
      });

      $book.bind('turned', function(event, page) {
        $('#page-num').text('当前：' + page + ' / ' + $book.turn('pages'));
      });
    });
  </script>
</body>
</html>