impress.js 中文注释
impress.js 中文注释
/**
* impress.js
*（本翻译并未完全遵照原作者的注释翻译）
* Impress.js 是受 Prezi启发，基于现代浏览器的 CSS3 与 JavaScript
*语言完成的一个可供开发者使用的表现层框架.
*
*
* Copyright 2011-2012 Bartek Szopka (@bartaz)
*
* Released under the MIT and GPL Licenses.
*
* ------------------------------------------------
* 作者: Bartek Szopka
* 版本: 0.5.3
* url: http://bartaz.github.com/impress.js/
* 源码: http://github.com/bartaz/impress.js/
*/
/*jshint bitwise:true, curly:true, eqeqeq:true, forin:true, latedef:true, newcap:true,
noarg:true, noempty:true, undef:true, strict:true, browser:true */
// 想知道impress.js内部工作原理吗?
// 现在从使impress.js开始运转的齿轮开始为您介绍...
(function (document, window) {
'use strict';
// 辅助函数
// `pfx` 是一个采用标准的CSS3属性为参数，返回其在当前浏览器是否被支持的信息。
// 代码参考了Modernizr http://www.modernizr.com/
var pfx = (function () {
var style = document.createElement('dummy').style,
prefixes = 'Webkit Moz O ms Khtml'.split(' '),
memory = {};
returnfunction (prop) {
if (typeof memory[prop] === "undefined") {
var ucProp = prop.charAt(0).toUpperCase() + prop.substr(1),
props = (prop + ' ' + prefixes.join(ucProp + ' ') + ucProp).split(' ');
memory[prop] = null;
for (var i in props) {
if (style[props[i]] !== undefined) {
memory[prop] = props[i];
break;
}
}
}
return memory[prop];
};
})();
// `arraify` 接收一个类似数组的参数，然后将它放入真正的数组，
// 以使所有的数组属性完整有效。
var arrayify = function (a) {
return [].slice.call(a);
};
// `css` 函数提供以下功能：
//将 `props` 对象中的样式添加到元素‘el’中。
// 通过 `pfx` 函数确保样式的每一个属性可用。
// sure proper prefixed version of the property is used.
var css = function (el, props) {
var key, pkey;
for (key in props) {
if (props.hasOwnProperty(key)) {
pkey = pfx(key);
if (pkey !== null) {
el.style[pkey] = props[key];
}
}
}
return el;
};
// `toNumber` 函数提供类型强制转换功能，将传入参数转换为数值类型。
// 如果转换失败，返回0 (或者自定义的
// `fallback`回调函数).
var toNumber = function (numeric, fallback) {
return isNaN(numeric) ? (fallback || 0) : Number(numeric);
};
// `byId` 返回给定`id`的元素 - 你懂得 ;)
var byId = function (id) {
return document.getElementById(id);
};
// `$` 通过给定的 CSS选择器（`selector`）返回在
//上下文（`context`，指定元素或者整个文档）中
//第一个匹配的元素
var $ = function (selector, context) {
context = context || document;
return context.querySelector(selector);
};
// `$$`通过给定的 CSS选择器（`selector`）返回在
//上下文（`context`，指定元素或者整个文档）中
//匹配的元素数组
var $$ = function (selector, context) {
context = context || document;
return arrayify(context.querySelectorAll(selector));
};
// `triggerEvent` 为指定元素构建事件
// 该函数有三个参数：
// el:目标元素
// eventName:事件名称
//detail:传入数据
var triggerEvent = function (el, eventName, detail) {
var event = document.createEvent("CustomEvent");
event.initCustomEvent(eventName, true, true, detail);
el.dispatchEvent(event);
};
// `translate` 根据给定参数构建平移变换调用字符串.
var translate = function (t) {
return" translate3d(" + t.x + "px," + t.y + "px," + t.z + "px) ";
};
// `rotate` 根据给定参数构建旋转变换调用字符串..
// 默认情况下，旋转按照x，y，z轴顺序进行，
// 可以通过设置第二个参数‘revert’来改变旋转顺序
var rotate = function (r, revert) {
var rX = " rotateX(" + r.x + "deg) ",
rY = " rotateY(" + r.y + "deg) ",
rZ = " rotateZ(" + r.z + "deg) ";
return revert ? rZ + rY + rX : rX + rY + rZ;
};
// `scale` 根据给定参数构建缩放变换调用字符串
var scale = function (s) {
return" scale(" + s + ") ";
};
// `perspective` 根据给定参数构建透视变换调用字符串.
var perspective = function (p) {
return" perspective(" + p + "px) ";
};
// `getElementFromHash`
// 以ID为key，从window location中取得数据
var getElementFromHash = function () {
// 从url中取得id，通过删除开头的 `#` 或者 `#/`
// 所以 "fallback" `#slide-id` 和 "enhanced" `#/slide-id` 都合乎规范
return byId(window.location.hash.replace(/^#\/?/, ""));
};
// `computeWindowScale` 通过定义在config文件中的 window size 和 size，
//计算实际的缩放效果，
var computeWindowScale = function (config) {
var hScale = window.innerHeight / config.height,
wScale = window.innerWidth / config.width,
scale = hScale > wScale ? wScale : hScale;
if (config.maxScale && scale > config.maxScale) {
scale = config.maxScale;
}
if (config.minScale && scale < config.minScale) {
scale = config.minScale;
}
return scale;
};
// 校验支持性
var body = document.body;
var ua = navigator.userAgent.toLowerCase();
var impressSupported =
// 浏览器应该支持 CSS 3D 变换、classList和 dataset APIs
(pfx("perspective") !== null) &&
(body.classList) &&
(body.dataset) &&
// 但是一些移动设备得上黑名单了,
// 因为他们对CSS 3D的支持和硬件特性不足以运行impress.js
// sorry...
(ua.search(/(iphone)|(ipod)|(android)/) === -1);
if (!impressSupported) {
// 无法确定 `classList` 是否被支持
body.className += " impress-not-supported ";
} else {
body.classList.remove("impress-not-supported");
body.classList.add("impress-supported");
}
// 全局变量和默认值
// root元素，所有impress.js实例都必须保持并维护.
// 是的！在一个页面里我们可以拥有多个实例，但是
// 我不知道多个实例的意义在哪里;)
var roots = {};
// 默认配置.
var defaults = {
width: 1024,
height: 768,
maxScale: 1,
minScale: 0,
perspective: 1000,
transitionDuration: 1000
};
// 仅仅是一个空方法 ... 好吧，这个注释也很无聊^_^.
var empty = function () { returnfalse; };
// IMPRESS.JS API
// 你感兴趣的地方，才刚刚开始.
// `impress` function 是整个impress组件的核心，它返回一个指定id的对象，默认为
//该对象包含所有impress API 接口。
//
var impress = window.impress = function (rootId) {
// 如果impress.js不被浏览器看支持，它返回一个假的对象
// 这可能不是一个好的解决方案，但是这可以避免程序继续运行而出错
if (!impressSupported) {
return {
init: empty,
goto: empty,
prev: empty,
next: empty
};
}
rootId = rootId || "impress";
// 如果root已经初始化，返回该api
if (roots["impress-root-" + rootId]) {
return roots["impress-root-" + rootId];
}
// 所有演示步骤（step）的数据
var stepsData = {};
// 当前正在播放的step所在的html元素
var activeStep = null;
// 当前演示的状态数据 (position（位置）,
//rotation（旋转）和 scale（缩放）)
var currentState = null;
// step 元素数组
var steps = null;
// 配置项
var config = null;
// 浏览器缩放效果配置参数
var windowScale = null;
// 根对象
var root = byId(rootId);
var canvas = document.createElement("div");
var initialized = false;
// step 事件
//
// 在 impress.js中，有两个事件会被触发
// 当step在屏幕中被展现时将触发 `impress:stepenter`事件
// (上一个step展现结束) ；
// `impress:stepleave` 当前step展现结束，下一个step即将开始时将触发
//`impress:stepleave`事件
// 上一个step的引用
var lastEntered = null;
// step刚被展现的时候，onStepEnter会被调用
// 前提是当前step必须和上一step不同
//
var onStepEnter = function (step) {
if (lastEntered !== step) {
triggerEvent(step, "impress:stepenter");
lastEntered = step;
}
};
// step结束的时候，onStepLeave会被调用
// 前提是当前step必须和上一step相同
//
var onStepLeave = function (step) {
if (lastEntered === step) {
triggerEvent(step, "impress:stepleave");
lastEntered = null;
}
};
// `initStep` 使用data属性中的数据初始化指定的step元素，
//并设置正确的样式
var initStep = function (el, idx) {
var data = el.dataset,
step = {
translate: {
x: toNumber(data.x),
y: toNumber(data.y),
z: toNumber(data.z)
},
rotate: {
x: toNumber(data.rotateX),
y: toNumber(data.rotateY),
z: toNumber(data.rotateZ || data.rotate)
},
scale: toNumber(data.scale, 1),
el: el
};
if (!el.id) {
el.id = "step-" + (idx + 1);
}
stepsData["impress-" + el.id] = step;
css(el, {
position: "absolute",
transform: "translate(-50%,-50%)" +
translate(step.translate) +
rotate(step.rotate) +
scale(step.scale),
transformStyle: "preserve-3d"
});
};
// `init` API：初始化并运行当前演示文档.
var init = function () {
if (initialized) { return; }
// 首先，为移动设备设置视角.
// 由于某些原因，ipad会卡死.
var meta = $("meta[name='viewport']") || document.createElement("meta");
meta.content = "width=device-width, minimum-scale=1, maximum-scale=1, user-scalable=no";
if (meta.parentNode !== document.head) {
meta.name = 'viewport';
document.head.appendChild(meta);
}
// 初始化配置对象
var rootData = root.dataset;
config = {
width: toNumber(rootData.width, defaults.width),
height: toNumber(rootData.height, defaults.height),
maxScale: toNumber(rootData.maxScale, defaults.maxScale),
minScale: toNumber(rootData.minScale, defaults.minScale),
perspective: toNumber(rootData.perspective, defaults.perspective),
transitionDuration: toNumber(rootData.transitionDuration, defaults.transitionDuration)
};
windowScale = computeWindowScale(config);
// 将 step元素封装到canvas对象中
arrayify(root.childNodes).forEach(function (el) {
canvas.appendChild(el);
});
root.appendChild(canvas);
// 初始化默认样式
document.documentElement.style.height = "100%";
css(body, {
height: "100%",
overflow: "hidden"
});
var rootStyles = {
position: "absolute",
transformOrigin: "top left",
transition: "all 0s ease-in-out",
transformStyle: "preserve-3d"
};
css(root, rootStyles);
css(root, {
top: "50%",
left: "50%",
transform: perspective(config.perspective / windowScale) + scale(windowScale)
});
css(canvas, rootStyles);
body.classList.remove("impress-disabled");
body.classList.add("impress-enabled");
// 获取并设置step
steps = $$(".step", root);
steps.forEach(initStep);
// 为canvas初始化默认属性值
currentState = {
translate: { x: 0, y: 0, z: 0 },
rotate: { x: 0, y: 0, z: 0 },
scale: 1
};
initialized = true;
triggerEvent(root, "impress:init", { api: roots["impress-root-" + rootId] });
};
// `getStep` 是一个辅助函数，根据参数返回指定的step.
// 如果参数是数字，返回‘step-n’对象,
// 如果参数是字符串，返回id和该字符串相同的step元素,
// 如果参数为DOM元素，返回该step对象（只要对象存在）.
var getStep = function (step) {
if (typeof step === "number") {
step = step < 0 ? steps[steps.length + step] : steps[step];
} elseif (typeof step === "string") {
step = byId(step);
}
return (step && step.id && stepsData["impress-" + step.id]) ? step : null;
};
// 为 `impress:stepenter` 事件设置timeout值
var stepEnterTimeout = null;
// `goto` API 函数，根据传入的‘el’，跳转至指定的step (索引值，id或者元素),
// `duration` 可选，单位为秒.
var goto = function (el, duration) {
if (!initialized || !(el = getStep(el))) {
// presentation not initialized or given element is not a step
returnfalse;
}
// 有时候通过键盘操作来使第一个链接获得焦点是有必要的.
// 浏览器此时可能会滚动页面显示这个元素
// (甚至直接将body的overflow属性设置为hidden都不行) 这将影响我们的布局效果.
//
// 最简单的，在任何一个step显示的时候，我们都将页面滚动到顶端
//
// 如果你有更好的解决方案，请联系我，洗耳恭听！
window.scrollTo(0, 0);
var step = stepsData["impress-" + el.id];
if (activeStep) {
activeStep.classList.remove("active");
body.classList.remove("impress-on-" + activeStep.id);
}
el.classList.add("active");
body.classList.add("impress-on-" + el.id);
// 基于给定的step，计算其在canvas上的显示状态
var target = {
rotate: {
x: -step.rotate.x,
y: -step.rotate.y,
z: -step.rotate.z
},
translate: {
x: -step.translate.x,
y: -step.translate.y,
z: -step.translate.z
},
scale: 1 / step.scale
};
// 确定变换是否缩放（zooming in）（逐渐放大过程）.
//
// 下面的信息用于修改变换时的样式:
// 当元素逐渐放大的时候 - 首先进行平移和旋转
// 之后才进行缩放, 当逐步缩小（zooming out）时，
// 先进行向内缩放，然后做平移和旋转.
var zoomin = target.scale >= currentState.scale;
duration = toNumber(duration, config.transitionDuration);
var delay = (duration / 2);
// 如果相同的step被重复选中，强制计算窗口缩放值,
// 因为这有可能是窗口大小改变引起的
if (el === activeStep) {
windowScale = computeWindowScale(config);
}
var targetScale = target.scale * windowScale;
//触发当前step的离开（leave）事件 (只有不是重复选择的step才触发该事件)
if (activeStep && activeStep !== el) {
onStepLeave(activeStep);
}
// 现在我们修改 `root` 和 `canvas` 的变换属性，触发变换.
//
// 存在root和canvas这两个对象原因---
// 它们独立进行动画:
// `root`用于缩放而 `canvas` 用于平移和旋转.
// 二者开始变换的延时时间也不相同
// (为了变换过程在视觉效果上看起来自然、美观),
// 所以我们需要知道二者的行为是否都结束了.
css(root, {
// 为了保证在不同的缩放时使透视效果看起来是一样的
// 我们同时需要缩放透视（perspective）
transform: perspective(config.perspective / targetScale) + scale(targetScale),
transitionDuration: duration + "ms",
transitionDelay: (zoomin ? delay : 0) + "ms"
});
css(canvas, {
transform: rotate(target.rotate, true) + translate(target.translate),
transitionDuration: duration + "ms",
transitionDelay: (zoomin ? 0 : delay) + "ms"
});
// 最复杂的部分到了...
//
// 如果在缩放、平移、旋转属性上无任何变化, 就意味着没有延迟
// - 因为在 `root` 或者`canvas`元素上没有任何变换.
// 我们需要在恰当的时刻触发 `impress:stepenter` 事件,
// 所以我们比较当前和目标值从而确定是否需要计算延迟.
//
// 我只懂这个‘if’听起来很可怕, 但是当你知道即将要发生什么，这一切都变得很简单，
// - 简单到只需要比较下面这些值.
if (currentState.scale === target.scale ||
(currentState.rotate.x === target.rotate.x && currentState.rotate.y === target.rotate.y &&
currentState.rotate.z === target.rotate.z && currentState.translate.x === target.translate.x &&
currentState.translate.y === target.translate.y && currentState.translate.z === target.translate.z)) {
delay = 0;
}
// 存储当前状态
currentState = target;
activeStep = el;
// 这是触发 `impress:stepenter` 事件的地方.
//我们简单的使用定时器去解决变换延迟问题.
//
// 我确实想用更优雅的方式去解决这个问题.
//`transitionend` 事件看起来是最好的方式。
// 但是我是在两个独立的元素上应用变换，同时
// `transitionend`事件在只要有一个值发生变化就会被触发 (change in the values)
// 这引发了一些bug，并且使代码变得复杂, 因为我必须对所有场景都单独考虑.
// 而且当根本没有变换发生的时候，仍然需要一个 `setTimeout`延迟回调函数， .
// 所以我决定选择写更简单的代码而不是使用看起来更酷的 `transitionend`事件.
//
// 如果你想学习一些有意思的内容，
//去看impress.js 的0.5.2版本: http://github.com/bartaz/impress.js/blob/0.5.2/js/impress.js
window.clearTimeout(stepEnterTimeout);
stepEnterTimeout = window.setTimeout(function () {
onStepEnter(activeStep);
}, duration + delay);
return el;
};
// `prev` API function goes to previous step (in document order)
var prev = function () {
var prev = steps.indexOf(activeStep) - 1;
prev = prev >= 0 ? steps[prev] : steps[steps.length - 1];
return goto(prev);
};
// `next` API 函数，跳转到下一个step (在文档中的顺序)
var next = function () {
var next = steps.indexOf(activeStep) + 1;
next = next < steps.length ? steps[next] : steps[0];
return goto(next);
};
// 为step元素添加一些有用的类.
//
// 所有未被展示的step都被添加 `future` 类.
// 当step被播放时， `future`类被移除， `present`类被添加
//step结束时， `present` 类被‘past’类替换
//
// 所以每一个step都具有下面三种状态:
// `future`, `present` and `past`.
//
// 这三种类可以通过css，配置step在不同状态下的呈现样式.
// 例如 `present`类可以被用于当某个step展现的时候
// 触发一些自定义动画
root.addEventListener("impress:init", function () {
// STEP 的类
steps.forEach(function (step) {
step.classList.add("future");
});
root.addEventListener("impress:stepenter", function (event) {
event.target.classList.remove("past");
event.target.classList.remove("future");
event.target.classList.add("present");
}, false);
root.addEventListener("impress:stepleave", function (event) {
event.target.classList.remove("present");
event.target.classList.add("past");
}, false);
}, false);
// 添加hash变化支持.
root.addEventListener("impress:init", function () {
// 被探测到的上一个hash
var lastHash = "";
// 使用`#/step-id` 替代 `#step-id`
//以阻止浏览器滚动到该id的元素
// 必须在动画结束之后设置hash,
// 因为在google浏览器会导致变换的动画延迟.
// BUG: http://code.google.com/p/chromium/issues/detail?id=62820
root.addEventListener("impress:stepenter", function (event) {
window.location.hash = lastHash = "#/" + event.target.id;
}, false);
window.addEventListener("hashchange", function () {
// 当step开始展现， location 中的hash已经被更新，
// (就是上面几行代码),
//所以hashchange事件被触发，这导致同一step元素会被再次调用 `goto`
//
// 为了避免这一情况，我们存储上次的hash值然后做比较
if (window.location.hash !== lastHash) {
goto(getElementFromHash());
}
}, false);
//
// 通过url或者选择文档中的第一个step开始播放
goto(getElementFromHash() || steps[0], 0);
}, false);
body.classList.add("impress-disabled");
// 存储并返回root对象
return (roots["impress-root-" + rootId] = {
init: init,
goto: goto,
next: next,
prev: prev
});
};
// 浏览器是否支持impress.js的标记
impress.supported = impressSupported;
})(document, window);
// 导航事件
// 如你所见，这一部分代码和impress.js核心代码相分离.
// 这是因为这一部分代码仅仅需要impress.js提供的接口
//
//
// 在将来，我考虑将这部分代码放到独立的文件中
// 以插件的形式的存在.
(function (document, window) {
'use strict';
// throttling function calls, by Remy Sharp
// http://remysharp.com/2010/07/21/throttling-function-calls/
var throttle = function (fn, delay) {
var timer = null;
returnfunction () {
var context = this, args = arguments;
clearTimeout(timer);
timer = setTimeout(function () {
fn.apply(context, args);
}, delay);
};
};
// 等待 impress.js 初始化完毕
document.addEventListener("impress:init", function (event) {
// 从eventdata中获取api接口.
// 所以你不必在意impress.js的root元素的id或者其他属性是什么。
// `impress:init` event data给你所有想要的数据去控制播放
// .
var api = event.detail.api;
// 键盘导航处理函数
// 当被支持的按键按下时，阻止默认按键.
document.addEventListener("keydown", function (event) {
if (event.keyCode === 9 || (event.keyCode >= 32 && event.keyCode <= 34) || (event.keyCode >= 37 && event.keyCode <= 40)) {
event.preventDefault();
}
}, false);
// 当按键弹起事，触发按键事件 (← 或者 → )
// 支持的按键:
// [空格] - 跳到下一页
// [↑] [→] / [↓] [←] - 上，右，下，左,
// [下一页] / [下一页] - 通常被遥控器触发,
// [tab] -很有争议，理由就不讨论了
// 备忘录... 记得诡异的部分：
// 每一个step播放时，页面窗口都从（0,0）开始
//
// 嗯, [tab] 键在默认情况下导航至可定位焦点的元素,
// 所以频繁的点击此键，会破坏演示效果
// 我不想简单的禁用[tab], 所以我使用 [tab]
// 作为跳到下一个step的另一种方法... 当然, 为了保持一致性
// 我应该添加 [shift+tab] 作为回退操作...
document.addEventListener("keyup", function (event) {
if (event.keyCode === 9 || (event.keyCode >= 32 && event.keyCode <= 34) || (event.keyCode >= 37 && event.keyCode <= 40)) {
switch (event.keyCode) {
case 33: // pg up
case 37: // left
case 38: // up
api.prev();
break;
case 9: // tab
case 32: // space
case 34: // pg down
case 39: // right
case 40: // down
api.next();
break;
}
event.preventDefault();
}
}, false);
// 处理在当前演示step中产生的单击事件
document.addEventListener("click", function (event) {
// 处理事件冒泡（ "bubbling"）
// 是否是超链接
var target = event.target;
while ((target.tagName !== "A") &&
(target !== document.documentElement)) {
target = target.parentNode;
}
if (target.tagName === "A") {
var href = target.getAttribute("href");
//如果指向某一step，直接到该step
if (href && href[0] === '#') {
target = document.getElementById(href.slice(1));
}
}
if (api.goto(target)) {
event.stopImmediatePropagation();
event.preventDefault();
}
}, false);
// 处理在stepi上的点击
document.addEventListener("click", function (event) {
var target = event.target;
//查找最近的没有被激活的step
while (!(target.classList.contains("step") && !target.classList.contains("active")) &&
(target !== document.documentElement)) {
target = target.parentNode;
}
if (api.goto(target)) {
event.preventDefault();
}
}, false);
// 处理触摸屏上的轻敲屏幕左右边缘的事件
// 参考 @hakimel: https://github.com/hakimel/reveal.js
document.addEventListener("touchstart", function (event) {
if (event.touches.length === 1) {
var x = event.touches[0].clientX,
width = window.innerWidth * 0.3,
result = null;
if (x < width) {
result = api.prev();
} elseif (x > window.innerWidth - width) {
result = api.next();
}
if (result) {
event.preventDefault();
}
}
}, false);
// 浏览器窗口改变时，重新展示当前step
window.addEventListener("resize", throttle(function () {
// 强制再次激活当前step
api.goto(document.querySelector(".step.active"), 500);
}, 250), false);
}, false);
})(document, window);
// 到此为止！
//
// 谢谢你把它全部读完.
//即使你是直接滚到到此处，仍然感谢.
//
// 在编写impress.js时，我学到了很多。希望这些代码和注释能对你有所帮助。
欢迎访问玄魂的博客
ps：对此文章或者安全、安全编程感兴趣的读者，可以加qq群：Hacking:303242737;Hacking-2群：147098303；Hacking-3群：31371755；hacking-4群:201891680;Hacking-5群：316885176