jQuery 学习十(文档处理)

    ●  append(content)

/**
 * 向每个匹配的元素内部追加内容。
 * 这个操作与对指定的元素执行 appendChild 方法，将它们添加到文档中的情况类似。
 *
 * @content(String, Element, jQuery) 要追加到目标中的内容
 * @return Object
 * @owner jQuery Object
 */
function append(content);

// 例子：向所有段落中追加一些HTML标记。
<p>I would like to say: </p>

$("p").append("<b>Hello</b>") -> [ <p>I would like to say: <b>Hello</b></p> ]

    ●  appendTo(content)

/**
 * 把所有匹配的元素追加到另一个、指定的元素元素集合中。
 * 实际上，使用这个方法是颠倒了常规的 $(A).append(B) 的操作，即不是把 B 追加到 A 中，而是把 A 
 * 追加到 B 中。
 *
 * @content(String) 用于被追加的内容
 * @return Object
 * @owner jQuery Object
 */
function appendTo(content);

// 例子：把所有段落追加到 ID 值为 "foo" 的元素中。
<p>I would like to say: </p>
<div id="foo"></div>

$("p").appendTo("#foo") -> <div id="foo"><p>I would like to say: </p></div>

    ●  prepend(content)

/**
 * 向每个匹配的元素内部前置内容。这是向所有匹配元素内部的开始处插入内容的最佳方式。
 *
 * @content(String, Element, jQuery) 要插入到目标元素内部前端的内容
 * @return Object
 * @owner jQuery Object
 */
function prepend(content);

// 例子一：向所有段落中前置一些 HTML 标记代码。
<p>I would like to say: </p>

$("p").prepend("<b>Hello</b>") -> [ <p><b>Hello</b>I would like to say: </p> ]

// 例子二：将一个 DOM 元素前置入所有段落
<p>I would like to say: </p>
<p>I would like to say: </p>
<b class="foo">Hello</b>
<b class="foo">Good Bye</b>

$("p").prepend( $(".foo")[0] ) -> 
    <p><b class="foo">Hello</b>I would like to say: </p>
    <p><b class="foo">Hello</b>I would like to say: </p>
    <b class="foo">Hello</b>
    <b class="foo">Good Bye</b> 
    
// 例子三：向所有段落中前置一个 jQuery 对象(类似于一个 DOM 元素数组)。
<p>I would like to say: </p><b>Hello</b>

$("p").prepend( $("b") ) -> <p><b>Hello</b>I would like to say: </p>

    ●  prependTo(content)

/**
 * 把所有匹配的元素前置到另一个、指定的元素元素集合中。
 * 实际上，使用这个方法是颠倒了常规的 $(A).prepend(B) 的操作，即不是把 B 前置到 A 中，而是把 
 * A 前置到 B 中。
 *
 * @content(String) 用于匹配元素的 jQuery 表达式
 * @return Object
 * @owner jQuery Object
 */
function prependTo(content);

// 例子一：把所有段落追加到 ID 值为 foo 的元素中。
<p>I would like to say: </p>
<div id="foo"></div>

$("p").prependTo("#foo") -> <div id="foo"><p>I would like to say: </p></div>

    ●  after(content)

/**
 * 在每个匹配的元素之后插入内容。
 *
 * @content(String, Element, jQuery) 插入到每个目标后的内容
 * @return Object
 * @owner jQuery Object
 */
function after(content);

// 例子一：在所有段落之后插入一些 HTML 标记代码。
<p>I would like to say: </p>

$("p").after("<b>Hello</b>") -> <p>I would like to say: </p><b>Hello</b>

// 例子二：在所有段落之后插入一个 DOM 元素。
<b id="foo">Hello</b><p>I would like to say: </p>

$("p").after( $("#foo")[0] ) -> <p>I would like to say: </p><b id="foo">Hello</b>

// 例子三：在所有段落中后插入一个 jQuery 对象(类似于一个DOM元素数组)。
<b>Hello</b><p>I would like to say: </p>

$("p").after( $("b") ) -> <p>I would like to say: </p><b>Hello</b>

    ●  before(content)

/**
 * 在每个匹配的元素之前插入内容。
 *
 * @content(String, Element, jQuery) 插入到每个目标前的内容
 * @return Object
 * @owner jQuery Object
 */
function before(content);

// 例子一：在所有段落之前插入一些 HTML 标记代码。
<p>I would like to say: </p>

$("p").before("<b>Hello</b>") -> [ <b>Hello</b><p>I would like to say: </p> ]

// 例子二：在所有段落之前插入一个元素。
<p>I would like to say: </p>
<b id="foo">Hello</b>

$("p").before( $("#foo")[0] ) -> <b id="foo">Hello</b><p>I would like to say: </p>

// 例子三：在所有段落中前插入一个 jQuery 对象(类似于一个DOM元素数组)。
<p>I would like to say: </p><b>Hello</b>

$("p").before( $("b") ) -> <b>Hello</b><p>I would like to say: </p>

    ●  insertAfter(content)

/**
 * 把所有匹配的元素插入到另一个，指定的元素元素集合的后面。
 * 实际上，使用这个方法是颠倒了常规的 $(A).after(B) 的操作，即不是把 B 插入到 A 后面，而是把 A 
 * 插入到 B 后面。
 *
 * @content(String) 用于匹配元素的 jQuery 表达式
 * @return Object
 * @owner jQuery Object
 */
function insertAfter(content);

// 例子一：把所有段落插入到一个元素之后。与 $("#foo").after("p") 相同。
<p>I would like to say: </p>
<div id="foo">Hello</div>

$("p").insertAfter("#foo") -> <div id="foo">Hello</div><p>I would like to say: </p>

    ●  insertBefore(content)

/**
 * 把所有匹配的元素插入到另一个、指定的元素元素集合的前面。
 * 实际上，使用这个方法是颠倒了常规的 $(A).before(B) 的操作，即不是把 B 插入到 A 前面，而是把 A 
 * 插入到 B 前面。
 *
 * @content(String) 用于匹配元素的 jQuery 表达式
 * @return Object
 * @owner jQuery Object
 */
function insertBefore(content);

// 例子：把所有段落插入到一个元素之前。与 $("#foo").before("p") 相同。
<div id="foo">Hello</div>
<p>I would like to say: </p>

$("p").insertBefore("#foo") -> <p>I would like to say: </p><div id="foo">Hello</div>

    ●  wrap(elem)

/**
 * 把所有匹配的元素用其他元素的结构化标记包装起来。
 *
 * @elem(Element) 用于包装目标元素的 DOM 元素
 * @return Object
 * @owner jQuery Object
 */
function wrap(elem);

// 例子：用 ID 是 "content" 的 div 将每一个段落包裹起来。
<p>Test Paragraph.</p>
<div id="content"></div>

$("p").wrap(document.getElementById('content')) -> 
    <div id="content"><p>Test Paragraph.</p></div><div id="content"></div>

    ●  wrapAll(elem)

/**
 * 将所有匹配的元素用单个元素包裹起来。这于 wrap(elem) 是不同的，wrap(elem) 为每一个匹配的元素都
 * 包裹一次。
 *
 * @elem(Element) 用于包装目标元素的 DOM 元素
 * @return Object
 * @owner jQuery Object
 */
function wrapAll(elem);

// 例子：用一个生成的 div 将所有段落包裹起来。
<p>Hello</p>
<p>cruel</p>
<p>World</p>

$("p").wrapAll(document.createElement("div")) -> <div><p>Hello</p><p>cruel</p><p>World</p></div>

    ●  wrapInner(elem)

/**
 * 将每一个匹配的元素的子内容(包括文本节点)用 DOM 元素包裹起来。
 *
 * @elem(Element) 用于包装目标元素的 DOM 元素
 * @return Object
 * @owner jQuery Object
 */
function wrapInner(elem);

// 例子：把所有段落内的每个子内容加粗。
<p>Hello</p>
<p>cruel</p>
<p>World</p>

$("p").wrapInner(document.createElement("b")) -> 
    <p><b>Hello</b></p><p><b>cruel</b></p><p><b>World</b></p> 

    ●  wrap(html)

/**
 * 把所有匹配的元素用其他元素的结构化标记包裹起来。
 * 这种包装对于在文档中插入额外的结构化标记最有用，而且它不会破坏原始文档的语义品质。
 * 
 * 这个函数的原理是检查提供的 html(它是由所提供的 HTML 标记代码动态生成的)，并在它的代码结构中
 * 找到最上层的祖先元素 － 这个祖先元素就是包裹元素。
 * 
 * 当 HTML 标记代码中的元素包含文本时无法使用这个函数。因此，如果要添加文本应该在包裹完成之后再行添加。
 *
 * @html(String) HTML 标记代码字符串，用于动态生成元素并包裹目标元素
 * @return Object
 * @owner jQuery Object
 */
function wrap(html);

// 例子：把所有的段落用一个新创建的 div 包裹起来。
<p>Test Paragraph.</p>

$("p").wrap("<div class='wrap'></div>") -> <div class="wrap"><p>Test Paragraph.</p></div>

    ●  wrapAll(html)

/**
 * 将所有匹配的元素用单个元素包裹起来。这于 wrap(html)是不同的，wrap(html) 为每一个匹配的元素都
 * 包裹一次。
 *
 * 这种包装对于在文档中插入额外的结构化标记最有用，而且它不会破坏原始文档的语义品质。
 *
 * 这个函数的原理是检查提供的第一个元素并在它的代码结构中找到最上层的祖先元素 － 这个祖先元素就
 * 是包装元素。
 *
 * @html(String) HTML 标记代码字符串，用于动态生成元素并包装目标元素
 * @return Object
 * @owner jQuery Object
 */
function wrapAll(html);

// 例子：用一个生成的 div 将所有段落包裹起来。
<p>Hello</p>
<p>cruel</p>
<p>World</p>

$("p").wrapAll("<div></div>") -> <div><p>Hello</p><p>cruel</p><p>World</p></div>

    ●  wrapInner(html)

/**
 * 将每一个匹配的元素的子内容(包括文本节点)用一个 HTML 结构包裹起来。
 *
 * 这个函数的原理是检查提供的第一个元素(它是由所提供的 HTML 标记代码动态生成的)，并在它的代码结构中
 * 找到最上层的祖先元素 - 这个祖先元素就是包装元素。
 *
 * @html(String) HTML 标记代码字符串，用于动态生成元素并包装目标元素
 * @return Object
 * @owner jQuery Object
 */
function wrapInner(html);

// 例子：把所有段落内的每个子内容加粗。
<p>Hello</p>
<p>cruel</p>
<p>World</p>

$("p").wrapInner("<b></b>") -> <p><b>Hello</b></p><p><b>cruel</b></p><p><b>World</b></p>

    ●  replaceAll(selector)

/**
 * 用匹配的元素替换掉所有 selector 匹配到的元素。
 *
 * @selector(Selector) 用于查找所要被替换的元素
 * @return Object
 * @owner jQuery Object
 */
function replaceAll(selector);

// 例子：把所有的段落标记替换成加粗标记。
<p>Hello</p>
<p>cruel</p>
<p>World</p>

$("<b>Paragraph. </b>").replaceAll("p") -> 
    <b>Paragraph. </b><b>Paragraph. </b><b>Paragraph. </b>

    ●  replaceWith(content)

/**
 * 将所有匹配的元素替换成指定的 HTML 或 DOM 元素。
 *
 * @content(String, Element, jQuery) 用于将匹配元素替换掉的内容
 * @return Object
 * @owner jQuery Object
 */
function replaceWith(content);

// 例子：把所有的段落标记替换成加粗的标记。
<p>Hello</p>
<p>cruel</p>
<p>World</p>

$("p").replaceWith("<b>Paragraph. </b>") -> 
    <b>Paragraph. </b><b>Paragraph. </b><b>Paragraph. </b>

    ●  empty()

/**
 * 删除匹配的元素集合中所有的子节点。
 *
 * @return Object
 * @owner jQuery Object
 */
function empty();

// 例子：把所有段落的子元素(包括文本节点)删除。
<p>Hello, <span>Person</span> <a href="#">and person</a></p>

$("p").empty() -> <p></p>

    ●  remove([expr])

/**
 * 从 DOM 中删除所有匹配的元素。这个方法不会把匹配的元素从 jQuery 对象中删除，因而可以在将来再使用
 * 这些匹配的元素。
 *
 * @expr(String) (可选) 用于筛选元素的 jQuery 表达式
 * @return Object
 * @owner jQuery Object
 */
function remove([expr]);

// 例子一：从 DOM 中把所有段落删除。
<p>Hello</p> how are <p>you?</p>

$("p").remove() -> how are

// 例子二：从 DOM 中把带有 hello 类的段落删除。
<p class="hello">Hello</p> how are <p>you?</p>
$("p").remove(".hello") -> how are <p>you?</p>

    ●  clone()

/**
 * 克隆匹配的 DOM 元素并且选中这些克隆的副本。
 * 在想把 DOM 文档中元素的副本添加到其他位置时这个函数非常有用。
 *
 * @return Object
 * @owner jQuery Object
 */
function clone();

// 例子：克隆所有 b 元素(并选中这些克隆的副本)，然后将它们前置到所有段落中。
<b>Hello</b><p>, how are you?</p>

$("b").clone().prependTo("p") -> <b>Hello</b><p><b>Hello</b>, how are you?</p>

    ●  clone(true)

/**
 * 元素以及其所有的事件处理并且选中这些克隆的副本。
 * 在想把 DOM 文档中元素的副本添加到其他位置时这个函数非常有用。
 *
 * @true(Boolean) 设置为 true 以便复制元素的所有事件处理
 * @return Object
 * @owner jQuery Object
 */
function clone(true);

// 例子：创建一个按钮，它可以复制自己，并且它的副本也有同样功能。
<button>Clone Me!</button>

$("button").click(function() {
  $(this).clone(true).insertAfter(this);
});