README

贡献指南

在开源软件开发精神中，jQuery 总是鼓励社区代码贡献。在您开始编写代码之前，请务必仔细阅读这些重要的贡献指南。

jQuery 可用环境

浏览器支持在主分支（2.x）和 1.x-master 分支之间有所不同。具体来说，2.x 不支持旧浏览器，如 IE6-8。jQuery 团队继续在 1.x-master 分支上为旧浏览器提供支持。如果需要支持这些浏览器，请使用最新的 1.x 版本。有关更多信息，请参阅浏览器支持。
要在 Node、浏览器扩展和其他非浏览器环境中使用 jQuery，请仅使用 2.x 版本。1.x 不支持这些环境。

构建您自己的 jQuery 所需的内容

为了构建 jQuery，您需要安装最新版本的 Node.js/npm 和 Git 1.7 或更高版本。（早期版本可能也能正常工作，但未经测试。）

对于 Windows 用户，您必须下载并安装 git 和 Node.js。

Mac OS 用户应安装 Homebrew。安装 Homebrew 后，运行 brew install git 以安装 git，并运行 brew install node 以安装 Node.js。

Linux/BSD 用户应使用适当的包管理器安装 git 和 Node.js，或者如果您愿意，也可以从源代码构建。简单易行。

如何构建您自己的 jQuery

通过运行以下命令克隆 jQuery 的主 git 仓库的副本：

git clone git://github.com/jquery/jquery.git

进入 jquery 目录并运行构建脚本

cd jquery && npm run build

构建的 jQuery 版本将放入 dist/ 子目录中，包括精简版和相关的映射文件。

如果您想创建自定义构建或帮助 jQuery 开发，最好安装 grunt 命令行界面作为全局包。

npm install -g grunt-cli

通过测试确保已安装 grunt：

grunt -v

现在，通过在 jquery 目录中运行 grunt 命令，您就可以构建 jQuery 的完整版本，就像使用 npm run build 命令一样。

grunt

jQuery 核心有许多其他可用的任务

grunt -help

模块

可以创建特殊构建来排除 jQuery 功能的子集。这允许在确定这些部分没有使用的情况下构建更小的自定义版本。例如，仅使用 JSONP 的 $.ajax() 且不需要计算元素偏移或位置的应用程序可以排除 offset 和 ajax/xhr 模块。

可以排除任何模块，除了 core 和 selector。要排除一个模块，请传递相对于 src 文件夹的路径（不包括 .js 扩展名）。

以下是可以排除的一些示例模块：

ajax：所有 AJAX 功能：$.ajax()、$.get()、$.post()、$.ajaxSetup()、.load()、传输以及如 .ajaxStart() 之类的 AJAX 事件简写。
ajax/xhr：仅支持XMLHTTPRequest AJAX传输。
ajax/script：仅支持<script> AJAX传输；用于检索脚本。
ajax/jsonp：仅支持JSONP AJAX传输；依赖于ajax/script传输。
css：.css()方法以及非动画的.show()、.hide()和.toggle()方法。同时移除所有依赖于css（包括效果、尺寸和偏移）的模块。
已废弃：已记录为废弃但尚未删除的方法；目前仅.andSelf()。
尺寸：.width()和.height()方法，包括inner-和outer-变体。
效果：.animate()方法及其缩写，如.slideUp()或.hide("slow")。
事件：.on()和.off()方法以及所有事件功能。同时移除event/alias。
事件/别名：所有事件绑定/触发缩写，如.click()或.mouseover()。
偏移：.offset()、.position()、.offsetParent()、.scrollLeft()和.scrollTop()方法。
包裹：.wrap()、.wrapAll()、.wrapInner()和.unwrap()方法。
core/ready：如果您将脚本放置在body的末尾，请排除ready模块。任何使用jQuery()绑定的ready回调将立即调用。但是，jQuery(document).ready()将不是一个函数，并且.on("ready", ...)或类似的将不会被触发。
deferred：排除jQuery.Deferred。这也移除了jQuery.Callbacks。注意，依赖于jQuery.Deferred（AJAX、效果、core/ready）的模块不会被移除，并且仍然期望jQuery.Deferred存在。包含您自己的jQuery.Deferred实现或同时排除这些模块（例如：grunt custom:-deferred,-ajax,-effects,-core/ready）。
exports/global：排除将全局jQuery变量（$和jQuery）附加到window。
exports/amd：排除AMD定义。

作为特殊情况，您还可以使用特殊标志grunt custom:-sizzle来替换Sizzle。

sizzle：Sizzle选择器引擎。当排除此模块时，它被一个基于浏览器querySelectorAll方法的简单选择器引擎所替代，该引擎不支持jQuery选择器扩展或增强语义。有关详细信息，请参阅selector-native.js文件。

注意：排除Sizzle也将排除所有jQuery选择器扩展（如effects/animatedSelector和css/hiddenVisibleSelectors）。

构建过程将为它排除或包含的每个依赖模块显示一条消息。

AMD名称

作为一个选项，您可以设置jQuery的AMD定义的模块名称。默认情况下，它设置为"jquery"，这可以很好地与插件和第三方库一起使用，但在某些情况下，您可能希望更改它。只需设置"amd"选项

grunt custom --amd="custom-name"

或者，为了匿名定义，将名称设置为空字符串。

grunt custom --amd=""

自定义构建示例

要创建最新稳定版本的自定义构建，首先检出该版本

git pull; git checkout $(git describe --abbrev=0 --tags)

然后，确保所有Node依赖都已安装

npm install

使用grunt custom选项创建自定义构建，列出要排除的模块。

排除所有ajax功能

grunt custom:-ajax

排除css将移除依赖于CSS的模块：效果、偏移、尺寸。

grunt custom:-css

排除多个模块

grunt custom:-ajax,-css,-deprecated,-dimensions,-effects,-event/alias,-offset,-wrap

有关自定义构建的疑问或请求，请从论坛的开发jQuery核心部分开始一个线程。由于这些构建的组合和定制性质，它们不在jQuery的单元测试过程中定期测试。当前的非Sizzle选择器引擎无法通过单元测试，因为它缺少太多的基本功能。

运行单元测试

确保您有必要的依赖项

npm install

开始grunt watch或npm start，以在您工作时自动构建jQuery

cd jquery && grunt watch

使用支持PHP的本地服务器运行单元测试。请确保您从根目录而不是“test”目录运行网站。不需要数据库。Windows和Mac都提供了预配置的PHP本地服务器。以下是一些选项：

构建到不同的目录

要将构建的jQuery文件从/dist复制到另一个目录

grunt && grunt dist:/path/to/special/location/

在这个例子中，输出文件将是

/path/to/special/location/jquery.js
/path/to/special/location/jquery.min.js

要添加永久复制目标，在dist/中创建一个名为".destination.json"的文件。在文件中，粘贴并自定义以下内容

{
  "/Absolute/path/to/other/destination": true
}

此外，这两种方法可以结合使用。

Git基础

由于源代码由Git版本控制系统处理，了解一些使用的功能是有用的。

清理

如果您想将工作目录恢复到上游的状态，可以使用以下命令（请记住，在执行这些命令后，您所做的所有工作都将消失）

git reset --hard upstream/master
git clean -fdx

变基

对于功能/主题分支，您应该始终使用--rebase标志来执行git pull，或者如果您通常处理许多临时的“要进入github pull request”分支，请运行以下命令来自动化此操作

git config branch.autosetuprebase local

（有关更多信息，请参阅man git-config）

处理合并冲突

当合并时遇到合并冲突时，您可以使用git mergetool功能，而不是手动编辑冲突文件。尽管默认工具xxdiff看起来很糟糕/过时，但它非常有用。

以下是一些可以在那里使用的命令

Ctrl + Alt + M - 尽可能自动合并
b - 跳转到下一个合并冲突
s - 改变冲突行的顺序
u - 撤销合并
左鼠标按钮 - 标记一个块为获胜者
中鼠标按钮 - 标记一行为获胜者
Ctrl + S - 保存
Ctrl + Q - 退出

QUnit参考

测试方法

expect( numAssertions );
stop();
start();

注意：QUnit最终添加的参数以停止/启动是忽略在这个测试套件中，这样就可以将启动和停止作为回调传递，而不必担心它们的参数

测试断言

ok( value, [message] );
equal( actual, expected, [message] );
notEqual( actual, expected, [message] );
deepEqual( actual, expected, [message] );
notDeepEqual( actual, expected, [message] );
strictEqual( actual, expected, [message] );
notStrictEqual( actual, expected, [message] );
throws( block, [expected], [message] );

测试套件便捷方法参考（见test/data/testinit.js）

返回具有给定ID的元素数组

q( ... );

示例

q("main", "foo", "bar");

=> [ div#main, span#foo, input#bar ]

断言选择匹配给定的ID

t( testName, selector, [ "array", "of", "ids" ] );

示例

t("Check for something", "//[a]", ["foo", "baar"]);

触发一个不通过jQuery的本地DOM事件

fireNative( node, eventType )

示例

fireNative( jQuery("#elem")[0], "click" );

向url添加随机数以停止缓存

url( "some/url.php" );

示例

url("data/test.html");

=> "data/test.html?10538358428943"


url("data/test.php?foo=bar");

=> "data/test.php?foo=bar&10538358345554"

在iframe中加载测试

使用fileName: "./data/" + fileName + ".html"构建给定的页面，并在jQuery ready时调用给定的回调（使用从该页面加载的jQuery）并将iframe的jQuery传递给回调

testIframe( fileName, testName, callback );

回调参数

callback( jQueryFromIFrame, iFrameWindow, iFrameDocument );

在iframe中加载测试（window.iframeCallback）

使用fileName: "./data/" + fileName + ".html"构建给定的页面。当页面调用window.iframeCallback时，将触发给定的回调。传递给回调的参数与传递给window.iframeCallback的参数相同

testIframeWithCallback( testName, fileName, callback );

有问题吗？

如果您有任何疑问，请随时在 jQuery 核心开发论坛或在 irc.freenode.net 的 #jquery 频道提问。

rockerox / jquery

维护者

详细信息