INTEGRITY Dokumentace

← Cloudflare Workers / workers / runtime-apis

HTMLRewriter

Kontext

HTMLRewriter třída umožňuje vývojářům vytvářet komplexní a expresivní parsery HTML přímo v aplikaci Cloudflare Workers. Lze si ji představit jako obdobu jQuery přímo uvnitř vaší aplikace Workers. Díky výkonnému JavaScript API pro parsování a transformaci HTML HTMLRewriter umožňuje vývojářům vytvářet aplikace s bohatou funkčností.

HTMLRewriter třída by měla být ve vašem Workers skriptu instanciována jednou, s několika handlery připojenými pomocí on a onDocument funkce.

Konstruktor

new HTMLRewriter()
	.on("*", new ElementHandler())
	.onDocument(new DocumentHandler());

Globální typy

V celém HTMLRewriter API existuje několik jednotných typů, které používá řada vlastností a metod:

Obslužné rutiny

Existují dva typy handlerů, které lze použít s HTMLRewriter: obslužné rutiny prvků a obslužné rutiny dokumentů.

Element Handlers

Obslužná rutina elementu reaguje na jakýkoli příchozí element, pokud je připojena pomocí .on funkce objektu HTMLRewriter instance. Handler elementu by měl reagovat na element, comments, a text. Příklad zpracovává div elementů s ElementHandler třídu.

class ElementHandler {
	element(element) {
		// An incoming element, such as `div`
		console.log(`Incoming element: ${element.tagName}`);
	}

	comments(comment) {
		// An incoming comment
	}

	text(text) {
		// An incoming piece of text
	}
}

async function handleRequest(req) {
	const res = await fetch(req);

	return new HTMLRewriter().on("div", new ElementHandler()).transform(res);
}

Document Handlers

Document handler představuje příchozí HTML dokument. Na document handleru lze definovat řadu funkcí pro dotazování a úpravu doctype, comments, text, a end. Na rozdíl od element handleru má document handler doctype, comments, text, a end funkce nejsou omezeny konkrétním selektorem. Funkce handleru dokumentu se volají pro veškerý obsah na stránce, včetně obsahu mimo nejvyšší HTML značku:

class DocumentHandler {
	doctype(doctype) {
		// An incoming doctype, such as <!DOCTYPE html>
	}

	comments(comment) {
		// An incoming comment
	}

	text(text) {
		// An incoming piece of text
	}

	end(end) {
		// The end of the document
	}
}

Asynchronní handlery

Všechny funkce definované jak u element handlerů, tak u document handlerů mohou vracet buď void nebo Promise<void>. Když svou handler funkci učiníte async umožňuje přístup k externím zdrojům, jako je API přes fetch, Workers KV, Durable Objects nebo cache.

class UserElementHandler {
	async element(element) {
		let response = await fetch(new Request("/user"));

		// fill in user info using response
	}
}

async function handleRequest(req) {
	const res = await fetch(req);

	// run the user element handler via HTMLRewriter on a div with ID `user_info`
	return new HTMLRewriter()
		.on("div#user_info", new UserElementHandler())
		.transform(res);
}

Element

element argument, používaný pouze v handlerech elementů, je reprezentací DOM elementu. Element má k dispozici řadu metod pro jeho dotazování a úpravu:

Vlastnosti

Metody

EndTag

endTag argument, používaný pouze v handlerech registrovaných pomocí element.onEndTag, je omezenou reprezentací prvku DOM.

Vlastnosti

Metody

Textové části

Cloudflare provádí streamované parsování bez kopírování dat (zero-copy), takže textové bloky (chunks) nejsou totéž co textové uzly v lexikálním stromu. Jeden textový uzel lexikálního stromu může být tvořen více bloky, jak postupně přicházejí po síti z origin serveru.

Uvažujme následující značkování: <div>Hey. How are you?</div>. Je možné, že skript Workers nezíská celý textový uzel z originu najednou; místo toho text obslužná rutina elementu se vyvolá pro každou přijatou část textového uzlu. Obslužná rutina může být například vyvolána s "Hey. How ", poté "are you?". Jakmile dorazí poslední chunk, textu se lastInTextNode vlastnost bude nastavena na true. Vývojáři by měli zajistit, aby tyto části (chunky) spojili dohromady.

Vlastnosti

Metody

Komentáře

comments funkce na handleru elementu umožňuje vývojářům dotazovat a upravovat značky HTML komentářů.

class ElementHandler {
	comments(comment) {
		// An incoming comment element, such as <!-- My comment -->
	}
}

Vlastnosti

Metody

Doctype

doctype funkce na handleru dokumentu umožňuje vývojářům dotazovat se na doctype ↗.

class DocumentHandler {
	doctype(doctype) {
		// An incoming doctype element, such as
		// <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
	}
}

Vlastnosti

Konec

end funkce na handleru dokumentu umožňuje vývojářům připojit obsah na konec dokumentu.

class DocumentHandler {
	end(end) {
		// The end of the document
	}
}

Metody

Selektory

Toto jsou selektory a k tomuto účelu se používají.

Chyby

Pokud handler vyvolá výjimku, parsování se okamžitě zastaví, tělo transformované odpovědi skončí chybou s vyvolanou výjimkou a tělo netransformované odpovědi se zruší (uzavře). Pokud už bylo tělo transformované odpovědi částečně odesláno klientovi jako stream, klient uvidí zkrácenou odpověď.

async function handle(request) {
	let oldResponse = await fetch(request);
	let newResponse = new HTMLRewriter()
		.on("*", {
			element(element) {
				throw new Error("A really bad error.");
			},
		})
		.transform(oldResponse);

	// At this point, an expression like `await newResponse.text()`
	// will throw `new Error("A really bad error.")`.
	// Thereafter, any use of `newResponse.body` will throw the same error,
	// and `oldResponse.body` will be closed.

	// Alternatively, this will produce a truncated response to the client:
	return newResponse;
}