496 lines
15 KiB
TypeScript
496 lines
15 KiB
TypeScript
/**
|
|
* Methods for modifying the DOM structure.
|
|
*
|
|
* @module cheerio/manipulation
|
|
*/
|
|
import { Node } from 'domhandler';
|
|
import type { Cheerio } from '../cheerio';
|
|
import type { BasicAcceptedElems, AcceptedElems } from '../types';
|
|
/**
|
|
* Create an array of nodes, recursing into arrays and parsing strings if necessary.
|
|
*
|
|
* @private
|
|
* @category Manipulation
|
|
* @param elem - Elements to make an array of.
|
|
* @param clone - Optionally clone nodes.
|
|
* @returns The array of nodes.
|
|
*/
|
|
export declare function _makeDomArray<T extends Node>(this: Cheerio<T>, elem?: BasicAcceptedElems<Node>, clone?: boolean): Node[];
|
|
/**
|
|
* Insert every element in the set of matched elements to the end of the target.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* $('<li class="plum">Plum</li>').appendTo('#fruits');
|
|
* $.html();
|
|
* //=> <ul id="fruits">
|
|
* // <li class="apple">Apple</li>
|
|
* // <li class="orange">Orange</li>
|
|
* // <li class="pear">Pear</li>
|
|
* // <li class="plum">Plum</li>
|
|
* // </ul>
|
|
* ```
|
|
*
|
|
* @param target - Element to append elements to.
|
|
* @returns The instance itself.
|
|
* @see {@link https://api.jquery.com/appendTo/}
|
|
*/
|
|
export declare function appendTo<T extends Node>(this: Cheerio<T>, target: BasicAcceptedElems<Node>): Cheerio<T>;
|
|
/**
|
|
* Insert every element in the set of matched elements to the beginning of the target.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* $('<li class="plum">Plum</li>').prependTo('#fruits');
|
|
* $.html();
|
|
* //=> <ul id="fruits">
|
|
* // <li class="plum">Plum</li>
|
|
* // <li class="apple">Apple</li>
|
|
* // <li class="orange">Orange</li>
|
|
* // <li class="pear">Pear</li>
|
|
* // </ul>
|
|
* ```
|
|
*
|
|
* @param target - Element to prepend elements to.
|
|
* @returns The instance itself.
|
|
* @see {@link https://api.jquery.com/prependTo/}
|
|
*/
|
|
export declare function prependTo<T extends Node>(this: Cheerio<T>, target: BasicAcceptedElems<Node>): Cheerio<T>;
|
|
/**
|
|
* Inserts content as the *last* child of each of the selected elements.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* $('ul').append('<li class="plum">Plum</li>');
|
|
* $.html();
|
|
* //=> <ul id="fruits">
|
|
* // <li class="apple">Apple</li>
|
|
* // <li class="orange">Orange</li>
|
|
* // <li class="pear">Pear</li>
|
|
* // <li class="plum">Plum</li>
|
|
* // </ul>
|
|
* ```
|
|
*
|
|
* @see {@link https://api.jquery.com/append/}
|
|
*/
|
|
export declare const append: <T extends Node>(this: Cheerio<T>, ...elems: [(this: Node, i: number, html: string) => BasicAcceptedElems<Node>] | BasicAcceptedElems<Node>[]) => Cheerio<T>;
|
|
/**
|
|
* Inserts content as the *first* child of each of the selected elements.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* $('ul').prepend('<li class="plum">Plum</li>');
|
|
* $.html();
|
|
* //=> <ul id="fruits">
|
|
* // <li class="plum">Plum</li>
|
|
* // <li class="apple">Apple</li>
|
|
* // <li class="orange">Orange</li>
|
|
* // <li class="pear">Pear</li>
|
|
* // </ul>
|
|
* ```
|
|
*
|
|
* @see {@link https://api.jquery.com/prepend/}
|
|
*/
|
|
export declare const prepend: <T extends Node>(this: Cheerio<T>, ...elems: [(this: Node, i: number, html: string) => BasicAcceptedElems<Node>] | BasicAcceptedElems<Node>[]) => Cheerio<T>;
|
|
/**
|
|
* The .wrap() function can take any string or object that could be passed to
|
|
* the $() factory function to specify a DOM structure. This structure may be
|
|
* nested several levels deep, but should contain only one inmost element. A
|
|
* copy of this structure will be wrapped around each of the elements in the set
|
|
* of matched elements. This method returns the original set of elements for
|
|
* chaining purposes.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* const redFruit = $('<div class="red-fruit"></div>');
|
|
* $('.apple').wrap(redFruit);
|
|
*
|
|
* //=> <ul id="fruits">
|
|
* // <div class="red-fruit">
|
|
* // <li class="apple">Apple</li>
|
|
* // </div>
|
|
* // <li class="orange">Orange</li>
|
|
* // <li class="plum">Plum</li>
|
|
* // </ul>
|
|
*
|
|
* const healthy = $('<div class="healthy"></div>');
|
|
* $('li').wrap(healthy);
|
|
*
|
|
* //=> <ul id="fruits">
|
|
* // <div class="healthy">
|
|
* // <li class="apple">Apple</li>
|
|
* // </div>
|
|
* // <div class="healthy">
|
|
* // <li class="orange">Orange</li>
|
|
* // </div>
|
|
* // <div class="healthy">
|
|
* // <li class="plum">Plum</li>
|
|
* // </div>
|
|
* // </ul>
|
|
* ```
|
|
*
|
|
* @param wrapper - The DOM structure to wrap around each element in the selection.
|
|
* @see {@link https://api.jquery.com/wrap/}
|
|
*/
|
|
export declare const wrap: <T extends Node>(this: Cheerio<T>, wrapper: AcceptedElems<Node>) => Cheerio<T>;
|
|
/**
|
|
* The .wrapInner() function can take any string or object that could be passed
|
|
* to the $() factory function to specify a DOM structure. This structure may be
|
|
* nested several levels deep, but should contain only one inmost element. The
|
|
* structure will be wrapped around the content of each of the elements in the
|
|
* set of matched elements.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* const redFruit = $('<div class="red-fruit"></div>');
|
|
* $('.apple').wrapInner(redFruit);
|
|
*
|
|
* //=> <ul id="fruits">
|
|
* // <li class="apple">
|
|
* // <div class="red-fruit">Apple</div>
|
|
* // </li>
|
|
* // <li class="orange">Orange</li>
|
|
* // <li class="pear">Pear</li>
|
|
* // </ul>
|
|
*
|
|
* const healthy = $('<div class="healthy"></div>');
|
|
* $('li').wrapInner(healthy);
|
|
*
|
|
* //=> <ul id="fruits">
|
|
* // <li class="apple">
|
|
* // <div class="healthy">Apple</div>
|
|
* // </li>
|
|
* // <li class="orange">
|
|
* // <div class="healthy">Orange</div>
|
|
* // </li>
|
|
* // <li class="pear">
|
|
* // <div class="healthy">Pear</div>
|
|
* // </li>
|
|
* // </ul>
|
|
* ```
|
|
*
|
|
* @param wrapper - The DOM structure to wrap around the content of each element
|
|
* in the selection.
|
|
* @returns The instance itself, for chaining.
|
|
* @see {@link https://api.jquery.com/wrapInner/}
|
|
*/
|
|
export declare const wrapInner: <T extends Node>(this: Cheerio<T>, wrapper: AcceptedElems<Node>) => Cheerio<T>;
|
|
/**
|
|
* The .unwrap() function, removes the parents of the set of matched elements
|
|
* from the DOM, leaving the matched elements in their place.
|
|
*
|
|
* @category Manipulation
|
|
* @example <caption>without selector</caption>
|
|
*
|
|
* ```js
|
|
* const $ = cheerio.load(
|
|
* '<div id=test>\n <div><p>Hello</p></div>\n <div><p>World</p></div>\n</div>'
|
|
* );
|
|
* $('#test p').unwrap();
|
|
*
|
|
* //=> <div id=test>
|
|
* // <p>Hello</p>
|
|
* // <p>World</p>
|
|
* // </div>
|
|
* ```
|
|
*
|
|
* @example <caption>with selector</caption>
|
|
*
|
|
* ```js
|
|
* const $ = cheerio.load(
|
|
* '<div id=test>\n <p>Hello</p>\n <b><p>World</p></b>\n</div>'
|
|
* );
|
|
* $('#test p').unwrap('b');
|
|
*
|
|
* //=> <div id=test>
|
|
* // <p>Hello</p>
|
|
* // <p>World</p>
|
|
* // </div>
|
|
* ```
|
|
*
|
|
* @param selector - A selector to check the parent element against. If an
|
|
* element's parent does not match the selector, the element won't be unwrapped.
|
|
* @returns The instance itself, for chaining.
|
|
* @see {@link https://api.jquery.com/unwrap/}
|
|
*/
|
|
export declare function unwrap<T extends Node>(this: Cheerio<T>, selector?: string): Cheerio<T>;
|
|
/**
|
|
* The .wrapAll() function can take any string or object that could be passed to
|
|
* the $() function to specify a DOM structure. This structure may be nested
|
|
* several levels deep, but should contain only one inmost element. The
|
|
* structure will be wrapped around all of the elements in the set of matched
|
|
* elements, as a single group.
|
|
*
|
|
* @category Manipulation
|
|
* @example <caption>With markup passed to `wrapAll`</caption>
|
|
*
|
|
* ```js
|
|
* const $ = cheerio.load(
|
|
* '<div class="container"><div class="inner">First</div><div class="inner">Second</div></div>'
|
|
* );
|
|
* $('.inner').wrapAll("<div class='new'></div>");
|
|
*
|
|
* //=> <div class="container">
|
|
* // <div class='new'>
|
|
* // <div class="inner">First</div>
|
|
* // <div class="inner">Second</div>
|
|
* // </div>
|
|
* // </div>
|
|
* ```
|
|
*
|
|
* @example <caption>With an existing cheerio instance</caption>
|
|
*
|
|
* ```js
|
|
* const $ = cheerio.load(
|
|
* '<span>Span 1</span><strong>Strong</strong><span>Span 2</span>'
|
|
* );
|
|
* const wrap = $('<div><p><em><b></b></em></p></div>');
|
|
* $('span').wrapAll(wrap);
|
|
*
|
|
* //=> <div>
|
|
* // <p>
|
|
* // <em>
|
|
* // <b>
|
|
* // <span>Span 1</span>
|
|
* // <span>Span 2</span>
|
|
* // </b>
|
|
* // </em>
|
|
* // </p>
|
|
* // </div>
|
|
* // <strong>Strong</strong>
|
|
* ```
|
|
*
|
|
* @param wrapper - The DOM structure to wrap around all matched elements in the
|
|
* selection.
|
|
* @returns The instance itself.
|
|
* @see {@link https://api.jquery.com/wrapAll/}
|
|
*/
|
|
export declare function wrapAll<T extends Node>(this: Cheerio<T>, wrapper: AcceptedElems<T>): Cheerio<T>;
|
|
/**
|
|
* Insert content next to each element in the set of matched elements.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* $('.apple').after('<li class="plum">Plum</li>');
|
|
* $.html();
|
|
* //=> <ul id="fruits">
|
|
* // <li class="apple">Apple</li>
|
|
* // <li class="plum">Plum</li>
|
|
* // <li class="orange">Orange</li>
|
|
* // <li class="pear">Pear</li>
|
|
* // </ul>
|
|
* ```
|
|
*
|
|
* @param content - HTML string, DOM element, array of DOM elements or Cheerio
|
|
* to insert after each element in the set of matched elements.
|
|
* @returns The instance itself.
|
|
* @see {@link https://api.jquery.com/after/}
|
|
*/
|
|
export declare function after<T extends Node>(this: Cheerio<T>, ...elems: [(this: Node, i: number, html: string) => BasicAcceptedElems<Node>] | BasicAcceptedElems<Node>[]): Cheerio<T>;
|
|
/**
|
|
* Insert every element in the set of matched elements after the target.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* $('<li class="plum">Plum</li>').insertAfter('.apple');
|
|
* $.html();
|
|
* //=> <ul id="fruits">
|
|
* // <li class="apple">Apple</li>
|
|
* // <li class="plum">Plum</li>
|
|
* // <li class="orange">Orange</li>
|
|
* // <li class="pear">Pear</li>
|
|
* // </ul>
|
|
* ```
|
|
*
|
|
* @param target - Element to insert elements after.
|
|
* @returns The set of newly inserted elements.
|
|
* @see {@link https://api.jquery.com/insertAfter/}
|
|
*/
|
|
export declare function insertAfter<T extends Node>(this: Cheerio<T>, target: BasicAcceptedElems<Node>): Cheerio<T>;
|
|
/**
|
|
* Insert content previous to each element in the set of matched elements.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* $('.apple').before('<li class="plum">Plum</li>');
|
|
* $.html();
|
|
* //=> <ul id="fruits">
|
|
* // <li class="plum">Plum</li>
|
|
* // <li class="apple">Apple</li>
|
|
* // <li class="orange">Orange</li>
|
|
* // <li class="pear">Pear</li>
|
|
* // </ul>
|
|
* ```
|
|
*
|
|
* @param content - HTML string, DOM element, array of DOM elements or Cheerio
|
|
* to insert before each element in the set of matched elements.
|
|
* @returns The instance itself.
|
|
* @see {@link https://api.jquery.com/before/}
|
|
*/
|
|
export declare function before<T extends Node>(this: Cheerio<T>, ...elems: [(this: Node, i: number, html: string) => BasicAcceptedElems<Node>] | BasicAcceptedElems<Node>[]): Cheerio<T>;
|
|
/**
|
|
* Insert every element in the set of matched elements before the target.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* $('<li class="plum">Plum</li>').insertBefore('.apple');
|
|
* $.html();
|
|
* //=> <ul id="fruits">
|
|
* // <li class="plum">Plum</li>
|
|
* // <li class="apple">Apple</li>
|
|
* // <li class="orange">Orange</li>
|
|
* // <li class="pear">Pear</li>
|
|
* // </ul>
|
|
* ```
|
|
*
|
|
* @param target - Element to insert elements before.
|
|
* @returns The set of newly inserted elements.
|
|
* @see {@link https://api.jquery.com/insertBefore/}
|
|
*/
|
|
export declare function insertBefore<T extends Node>(this: Cheerio<T>, target: BasicAcceptedElems<Node>): Cheerio<T>;
|
|
/**
|
|
* Removes the set of matched elements from the DOM and all their children.
|
|
* `selector` filters the set of matched elements to be removed.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* $('.pear').remove();
|
|
* $.html();
|
|
* //=> <ul id="fruits">
|
|
* // <li class="apple">Apple</li>
|
|
* // <li class="orange">Orange</li>
|
|
* // </ul>
|
|
* ```
|
|
*
|
|
* @param selector - Optional selector for elements to remove.
|
|
* @returns The instance itself.
|
|
* @see {@link https://api.jquery.com/remove/}
|
|
*/
|
|
export declare function remove<T extends Node>(this: Cheerio<T>, selector?: string): Cheerio<T>;
|
|
/**
|
|
* Replaces matched elements with `content`.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* const plum = $('<li class="plum">Plum</li>');
|
|
* $('.pear').replaceWith(plum);
|
|
* $.html();
|
|
* //=> <ul id="fruits">
|
|
* // <li class="apple">Apple</li>
|
|
* // <li class="orange">Orange</li>
|
|
* // <li class="plum">Plum</li>
|
|
* // </ul>
|
|
* ```
|
|
*
|
|
* @param content - Replacement for matched elements.
|
|
* @returns The instance itself.
|
|
* @see {@link https://api.jquery.com/replaceWith/}
|
|
*/
|
|
export declare function replaceWith<T extends Node>(this: Cheerio<T>, content: AcceptedElems<Node>): Cheerio<T>;
|
|
/**
|
|
* Empties an element, removing all its children.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* $('ul').empty();
|
|
* $.html();
|
|
* //=> <ul id="fruits"></ul>
|
|
* ```
|
|
*
|
|
* @returns The instance itself.
|
|
* @see {@link https://api.jquery.com/empty/}
|
|
*/
|
|
export declare function empty<T extends Node>(this: Cheerio<T>): Cheerio<T>;
|
|
/**
|
|
* Gets an HTML content string from the first selected element. If `htmlString`
|
|
* is specified, each selected element's content is replaced by the new content.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* $('.orange').html();
|
|
* //=> Orange
|
|
*
|
|
* $('#fruits').html('<li class="mango">Mango</li>').html();
|
|
* //=> <li class="mango">Mango</li>
|
|
* ```
|
|
*
|
|
* @param str - If specified used to replace selection's contents.
|
|
* @returns The instance itself.
|
|
* @see {@link https://api.jquery.com/html/}
|
|
*/
|
|
export declare function html<T extends Node>(this: Cheerio<T>): string | null;
|
|
export declare function html<T extends Node>(this: Cheerio<T>, str: string | Cheerio<T>): Cheerio<T>;
|
|
/**
|
|
* Turns the collection to a string. Alias for `.html()`.
|
|
*
|
|
* @category Manipulation
|
|
* @returns The rendered document.
|
|
*/
|
|
export declare function toString<T extends Node>(this: Cheerio<T>): string;
|
|
/**
|
|
* Get the combined text contents of each element in the set of matched
|
|
* elements, including their descendants. If `textString` is specified, each
|
|
* selected element's content is replaced by the new text content.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* $('.orange').text();
|
|
* //=> Orange
|
|
*
|
|
* $('ul').text();
|
|
* //=> Apple
|
|
* // Orange
|
|
* // Pear
|
|
* ```
|
|
*
|
|
* @param str - If specified replacement for the selected element's contents.
|
|
* @returns The instance itself when setting text, otherwise the rendered document.
|
|
* @see {@link https://api.jquery.com/text/}
|
|
*/
|
|
export declare function text<T extends Node>(this: Cheerio<T>): string;
|
|
export declare function text<T extends Node>(this: Cheerio<T>, str: string | ((this: Node, i: number, text: string) => string)): Cheerio<T>;
|
|
/**
|
|
* Clone the cheerio object.
|
|
*
|
|
* @category Manipulation
|
|
* @example
|
|
*
|
|
* ```js
|
|
* const moreFruit = $('#fruits').clone();
|
|
* ```
|
|
*
|
|
* @returns The cloned object.
|
|
* @see {@link https://api.jquery.com/clone/}
|
|
*/
|
|
export declare function clone<T extends Node>(this: Cheerio<T>): Cheerio<T>;
|
|
//# sourceMappingURL=manipulation.d.ts.map
|