Analizador de entidades (entity-parser )
Convierte entidades de Telegram a HTML semántico.
¿Cuándo debo usar esto?
Probablemente ¡NUNCA!
Aunque este plugin puede generar HTML, generalmente es mejor enviar el texto y las entidades de vuelta a Telegram.
Convertirlos a HTML sólo es necesario en raros casos en los que necesites usar texto con formato de Telegram fuera de Telegram mismo, como mostrar mensajes de Telegram en un sitio web.
Mira la sección Casos en los que es mejor no usar este paquete para determinar si tienes un problema similar que resolver.
Si no estás seguro de si este plugin es el adecuado para tu caso de uso, no dudes en preguntar en nuestro grupo de Telegram. En la mayoría de los casos, la gente descubre que no necesita este complemento para resolver sus problemas.
Instalación
Ejecute el siguiente comando en su terminal en función de su tiempo de ejecución o gestor de paquetes:
deno add jsr:@qz/telegram-entities-parserbunx jsr add @qz/telegram-entities-parserpnpm dlx jsr add @qz/telegram-entities-parseryarn dlx jsr add @qz/telegram-entities-parsernpx jsr add @qz/telegram-entities-parserUso sencillo
El uso de este plugin es muy sencillo. He aquí un ejemplo rápido:
import { EntitiesParser } from "@qz/telegram-entities-parser";
import type { Message } from "@qz/telegram-entities-parser/types";
// Para un mejor rendimiento, cree la instancia fuera de la función.
const entitiesParser = new EntitiesParser();
const parse = (message: Message) => entitiesParser.parse({ message });
bot.on(":text", (ctx) => {
const html = parse(ctx.msg); // Convertir texto en cadena HTML
});
bot.on(":photo", (ctx) => {
const html = parse(ctx.msg); // Convertir pie de foto en cadena HTML
});2
3
4
5
6
7
8
9
10
11
12
13
14
Uso avanzado
Personalización de la etiqueta HTML de salida
Este paquete convierte entidades en HTML semántico, adhiriéndose lo más posible a las mejores prácticas y estándares. Sin embargo, la salida proporcionada puede no ser siempre la esperada.
Para solucionarlo, puede utilizar su propio renderer para personalizar los elementos HTML que rodean al texto de acuerdo con sus reglas. Puedes modificar reglas específicas extendiendo el Renderer por defecto o anular todas las reglas implementando el Renderer.
Para extender el renderer existente, haz lo siguiente:
import { EntitiesParser, RendererHtml } from "@qz/telegram-entities-parser";
import type {
CommonEntity,
RendererOutput,
} from "@qz/telegram-entities-parser/types";
// Cambiar la regla para la entidad de tipo negrita,
// pero deja el resto de los tipos como están definidos por `RendererHtml`.
class MyRenderer extends RendererHtml {
override bold(
options: { text: string; entity: CommonEntity },
): RendererOutput {
return {
prefix: '<strong class="tg-bold">',
suffix: "</strong>",
};
}
}
const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() });2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
El parámetro options acepta un objeto con text y entity.
text: El texto específico al que se refiere la entidad actual.entity: Puede estar representada por varias interfaces dependiendo del tipo de entidad, comoCommon,Entity Custom,Emoji Entity Pre,Entity Text, oLink Entity Text. Por ejemplo, el tipoMention Entity boldtiene una entidad con la interfazCommon, mientras que el tipoEntity textpuede tener una entidad con la interfaz_link Text, ya que incluye propiedades adicionales comoLink Entity url.
Aquí está la lista completa de interfaces y la salida para cada tipo de entidad:
| Entity Type | Interface | Result |
|---|---|---|
blockquote | Common | <blockquote class |
bold | Common | <b class |
bot | Common | <span class |
cashtag | Common | <span class |
code | Common | <code class |
custom | Custom | <span class |
email | Common | <a class |
expandable | Common | <blockquote class |
hashtag | Common | <span class |
italic | Common | <i class |
mention | Common | <a class |
phone | Common | <a class |
pre | Pre | <pre class o <pre class |
spoiler | Common | <span class |
strikethrough | Common | <del class |
text | Text | <a class |
text | Text | <a class o <a class |
underline | Common | <span class |
url | Common | <a class |
Si no está seguro de cuál es la interfaz correcta, consulte cómo se implementa Renderer o Renderer
Personalizar el sanitizador de texto
El texto de salida se desinfecta de forma predeterminada para garantizar la correcta representación del HTML y evitar vulnerabilidades XSS.
| Input | Output |
|---|---|
& | & |
< | & |
> | & |
" | & |
' | & |
Por ejemplo, el resultado <b>Negrita< se saneará a <b>Negrita<.
Puede anular este comportamiento especificando un text al crear una instancia de Entities:
- Si no especifica
text, se utilizará de manera predeterminadaSanitizer sanitizercomo sanitizador.Html - Si establece el valor en
false, se omitirá la sanitización y se mantendrá el texto de salida como el original. Esto no se recomienda, ya que puede generar una representación incorrecta y hacer que su aplicación sea vulnerable a ataques XSS. Asegúrese de manipularlo correctamente si elige esta opción. - Si proporciona una función, se utilizará en lugar del desinfectante predeterminado.
const myTextSanitizer: TextSanitizer = (options: TextSanitizerOption): string =>
// Sustituir carácter peligroso
options.text.replaceAll(/[&<>"']/, (match) => {
switch (match) {
case "&":
return "&";
case "<":
return "<";
case ">":
return ">";
case '"':
return """;
case "'":
return "'";
default:
return match;
}
});
// Aplique el desinfectante.
const entitiesParser = new EntitiesParser({ textSanitizer: myTextSanitizer });2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Casos en los que es mejor no utilizar este paquete
Si se enfrenta a problemas similares a los que se enumeran a continuación, es posible que pueda resolverlos sin utilizar este paquete.
Copiar y reenviar el mismo mensaje
Utiliza forward para reenviar mensajes de cualquier tipo.
También puedes utilizar la API copy, que realiza la misma acción pero no incluye un enlace al mensaje original. copy se comporta como copiar el mensaje y enviarlo de vuelta a Telegram, haciendo que aparezca como un mensaje normal en lugar de uno reenviado.
bot.on(":text", async (ctx) => {
// El identificador de chat de destino que se enviará.
const chatId = -946659600;
// Reenvía el mensaje actual sin un enlace al mensaje original.
await ctx.copyMessage(chatId);
// Reenvía el mensaje actual con un enlace al mensaje original.
await ctx.forwardMessage(chatId);
});2
3
4
5
6
7
8
Responder a mensajes con formato de texto modificado
Puede responder fácilmente a los mensajes entrantes utilizando HTML, Markdown o entidades.
bot.on(":text", async (ctx) => {
// Responder con HTML
await ctx.reply("<b>bold</b> <i>italic</i>", { parse_mode: "HTML" });
// Responder usando Telegram Markdown V2
await ctx.reply("*bold* _italic_", { parse_mode: "MarkdownV2" });
// Responder con entidades
await ctx.reply("bold italic", {
entities: [
{ offset: 0, length: 5, type: "bold" },
{ offset: 5, length: 6, type: "italic" },
],
});
});2
3
4
5
6
7
8
9
10
11
12
13
Use parse-mode para una mejor experiencia de formateo
Utiliza el plugin oficial parse para una mejor experiencia en la construcción de mensajes formateados. :::
Resumen del plugin
- Nombre:
entity-parser - Fuente
- Referencia