From 1c0f555eefa0ed992768da4b6643c585f54940ae Mon Sep 17 00:00:00 2001 From: qz Date: Mon, 9 Sep 2024 20:30:54 +0700 Subject: [PATCH 01/37] Add grammy-entity plugin --- site/docs/.vitepress/configs/locales/en.ts | 4 + site/docs/plugins/grammy-entity.md | 125 +++++++++++++++++++++ 2 files changed, 129 insertions(+) create mode 100644 site/docs/plugins/grammy-entity.md diff --git a/site/docs/.vitepress/configs/locales/en.ts b/site/docs/.vitepress/configs/locales/en.ts index b6c92ee9c9..fb04a61f26 100644 --- a/site/docs/.vitepress/configs/locales/en.ts +++ b/site/docs/.vitepress/configs/locales/en.ts @@ -261,6 +261,10 @@ const pluginThirdparty = { text: "Autoquote", link: "/plugins/autoquote", }, + { + text: "Convert Telegram Entities", + link: "/plugins/grammy-entity" + }, { text: "[Submit your PR!]", link: "/plugins/#create-your-own-plugins", diff --git a/site/docs/plugins/grammy-entity.md b/site/docs/plugins/grammy-entity.md new file mode 100644 index 0000000000..0a68d6140d --- /dev/null +++ b/site/docs/plugins/grammy-entity.md @@ -0,0 +1,125 @@ +--- +prev: false +next: false +--- + +# Convert Telegram Entities (grammy-entity) + +Converts [Telegram entities](https://core.telegram.org/bots/api#messageentity) to [HTML](https://core.telegram.org/bots/api#messageentity) or [Markdown](https://core.telegram.org/bots/api#markdownv2-style). + +## When Should I Use This? + +Probably NEVER! + +While this plugin can generate Telegram-compatible HTML or MarkdownV2, it’s usually best to just send the text and entities back to Telegram. + +Converting them to HTML or Markdown is only necessary in those rare cases when you need to use Telegram-formatted text **outside** of Telegram itself. + +If you’re still unsure whether this plugin is the right fit for your use case, please don’t hesitate to ask in our [Telegram group](https://t.me/grammyjs). +In most cases, people find they don’t actually need this plugin to solve their problems! + +## Installation + +Simply run this line of code in your terminal. + +::: code-group + +```sh:no-line-numbers [Deno] +deno add @qz/grammy-entity +``` + +```sh:no-line-numbers [Bun] +bunx jsr add @qz/grammy-entity +``` + +```sh:no-line-numbers [pnpm] +pnpm dlx jsr add @qz/grammy-entity +``` + +```sh:no-line-numbers [Yarn] +yarn dlx jsr add @qz/grammy-entity +``` + +```sh:no-line-numbers [npm] +npx jsr add @qz/grammy-entity +``` + +::: + +## Simple Usage + +Using this plugin is super straightforward! +Here’s a quick example. + +```ts +import { toHTML, toMarkdownV2 } from "@qz/grammy-entity"; + +bot.on(":text", async (ctx) => { + const html = toHTML(ctx.msg); // Convert text to HTML string + const md = toMarkdownV2(ctx.msg); // Convert text to MarkdownV2 string +}); +``` + +Both functions will also work with captioned messages, such as photos or videos. + +```ts +bot.on(":photo", async (ctx) => { + const html = toHTML(ctx.msg); // Convert caption to HTML string + const md = toMarkdownV2(ctx.msg); // Convert caption to MarkdownV2 string +}); +``` + +You can also pass a text and entities object directly: + +```ts +toHTML({ text: '...', entities: [...] }); // Get the HTML string +``` + +## Advanced Usage + +The `toHTML` and `toMarkdown` functions are designed to produce HTML or Markdown that’s compatible with Telegram, which is a sensible default for a Telegram library. + +However, if you want to serialize your data differently for another system, you can do that too! +Simply use the `serializeWith` function. + +To get started, you’ll need to create a serializer with the following type. + +```ts +import type { Serializer } from "@qz/grammy-entity"; + +const myHTMLSerializer: Serializer (match, node) { + // Your custom implementation here +} +``` + +Each matched node will be passed to your function, and you only need to wrap it however you like! + +If you’re looking for inspiration, check out the implementation of the [serializers](https://github.com/quadratz/grammy-entity/blob/main/src/serializers.ts). +You can easily copy, paste, and tweak it to fit your needs. + +We’ve also got some built-in escapers available for your convenience. + +```ts +import { escapeHtml, escapeMarkdownV2, type Escaper } from "@qz/grammy-entity"; + +escapeHtml(text); // Get HTML escaped text +escapeMarkdownV2(text); // Escape text for Telegram's MarkdownV2 + +// Or create your own escaper +const myEscaper: Escaper = (match) => {/* Your implementation here */}; +``` + +With these tools at your disposal, you can whip up your own HTML serializer like this: + +```ts +import { escapeHtml, serializeWith } from "@qz/grammy-entity"; + +const serialize = serializeWith(myHTMLSerializer, escapeHtml); +serialize(ctx.msg); +``` + +## Plugin Summary + +- Name: grammy-entity +- Package: +- Source: From e8abe7df66ada2db13ea5cbe8c776bfb8c82d00a Mon Sep 17 00:00:00 2001 From: qz Date: Mon, 9 Sep 2024 20:37:52 +0700 Subject: [PATCH 02/37] Fix fmt --- site/docs/.vitepress/configs/locales/en.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/.vitepress/configs/locales/en.ts b/site/docs/.vitepress/configs/locales/en.ts index fb04a61f26..cdbce35b7b 100644 --- a/site/docs/.vitepress/configs/locales/en.ts +++ b/site/docs/.vitepress/configs/locales/en.ts @@ -263,7 +263,7 @@ const pluginThirdparty = { }, { text: "Convert Telegram Entities", - link: "/plugins/grammy-entity" + link: "/plugins/grammy-entity", }, { text: "[Submit your PR!]", From 8a4628301bdbe82275f7d7bcda511521321c2c25 Mon Sep 17 00:00:00 2001 From: Qz Date: Mon, 9 Sep 2024 22:12:57 +0700 Subject: [PATCH 03/37] Fix typo --- site/docs/plugins/grammy-entity.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/site/docs/plugins/grammy-entity.md b/site/docs/plugins/grammy-entity.md index 0a68d6140d..760c5c045c 100644 --- a/site/docs/plugins/grammy-entity.md +++ b/site/docs/plugins/grammy-entity.md @@ -5,7 +5,7 @@ next: false # Convert Telegram Entities (grammy-entity) -Converts [Telegram entities](https://core.telegram.org/bots/api#messageentity) to [HTML](https://core.telegram.org/bots/api#messageentity) or [Markdown](https://core.telegram.org/bots/api#markdownv2-style). +Converts [Telegram entities](https://core.telegram.org/bots/api#messageentity) to [HTML](https://core.telegram.org/bots/api#html-style) or [Markdown](https://core.telegram.org/bots/api#markdownv2-style). ## When Should I Use This? @@ -54,7 +54,7 @@ Here’s a quick example. ```ts import { toHTML, toMarkdownV2 } from "@qz/grammy-entity"; -bot.on(":text", async (ctx) => { +bot.on(":text", (ctx) => { const html = toHTML(ctx.msg); // Convert text to HTML string const md = toMarkdownV2(ctx.msg); // Convert text to MarkdownV2 string }); @@ -63,7 +63,7 @@ bot.on(":text", async (ctx) => { Both functions will also work with captioned messages, such as photos or videos. ```ts -bot.on(":photo", async (ctx) => { +bot.on(":photo", (ctx) => { const html = toHTML(ctx.msg); // Convert caption to HTML string const md = toMarkdownV2(ctx.msg); // Convert caption to MarkdownV2 string }); From 97fb68b56e5ae0def2b289592cd90ee7535e3195 Mon Sep 17 00:00:00 2001 From: qz Date: Wed, 18 Sep 2024 06:55:57 +0700 Subject: [PATCH 04/37] update docs --- site/docs/plugins/telegram-entities-parser.md | 247 ++++++++++++++++++ 1 file changed, 247 insertions(+) create mode 100644 site/docs/plugins/telegram-entities-parser.md diff --git a/site/docs/plugins/telegram-entities-parser.md b/site/docs/plugins/telegram-entities-parser.md new file mode 100644 index 0000000000..3de12bd515 --- /dev/null +++ b/site/docs/plugins/telegram-entities-parser.md @@ -0,0 +1,247 @@ +--- +prev: false +next: false +--- + +# Convert Telegram Entities (telegram-entities-parser) + +Converts [Telegram entities](https://core.telegram.org/bots/api#messageentity) +to semantic HTML. +Specially designed for [grammY](https://grammy.dev/plugins/telegram-entities-parser), but should also compatible with other framework. + +## When Should I Use This? + +Probably NEVER! + +While this plugin can generate HTML, it's generally best to send the text and entities back to Telegram. + +Converting them to HTML is only necessary in rare cases where you need to use Telegram-formatted text **outside** of Telegram itself, such as displaying Telegram messages on a website. + +See the [_Cases When It's Better to Not Use This Package_](#cases-when-its-better-to-not-use-this-package) section to determine if you have a similar problem to solve. + +If you're unsure whether this plugin is the right fit for your use case, please don't hesitate to ask in our [Telegram group](https://t.me/grammyjs). +In most cases, people find they don't actually need this plugin to solve their problems! + +## Installation + +Run the following command in your terminal based on your runtime or package manager: + +::: code-group + +```sh:no-line-numbers [Deno] +deno add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [Bun] +bunx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [pnpm] +pnpm dlx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [Yarn] +yarn dlx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [npm] +npx jsr add @qz/telegram-entities-parser +``` + +::: + +## Simple Usage + +Using this plugin is straightforward. +Here's a quick example: + +```ts +import { EntitiesParser } from "@qz/telegram-entities-parser"; +import type { Message } from "@qz/telegram-entities-parser/types"; + +// For better performance, create the instance outside the function. +const entitiesParser = new EntitiesParser(); +const parse = (message: Message) => entitiesParser.parse({ message }); + +bot.on(":text", (ctx) => { + const html = parse(ctx.msg); // Convert text to HTML string +}); + +bot.on(":photo", (ctx) => { + const html = parse(ctx.msg); // Convert caption to HTML string +}); +``` + +## Advanced usage + +### Customize the Output HTML Tag + +This package converts entities into semantic HTML, adhering to best practices and standards as closely as possible. +However, you might find that the provided output is not exactly what you expected. + +To address this, you can use your own `renderer` to customize the HTML elements surrounding the text according to your rules. +You can modify specific rules by extending the default [`RendererHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts) or override all the rules by implementing the [`Renderer`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts). + +To extend the existing `renderer`, do the following: + +```ts +import { EntitiesParser, RendererHtml } from "@qz/telegram-entities-parser"; +import type { + CommonEntity, + RendererOutput, +} from "@qz/telegram-entities-parser/types"; + +// Change the rule for bold type entity, +// but leave the rest of the types as defined by `RendererHtml`. +class MyRenderer extends RendererHtml { + bold( + options: { text: string; entity: CommonEntity }, + ): RendererOutput { + return { + prefix: '', + suffix: "", + }; + } +} + +const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); +``` + +The `options` parameter accepts an object with `text` and `entity`. + +- `text`: The specific text that the current entity refers to. +- `entity`: This may be represented by various interfaces depending on the entity type, such as `CommonEntity`, `CustomEmojiEntity`, `PreEntity`, `TextLinkEntity`, or `TextMentionEntity`. + For instance, the `bold` type has an entity with the `CommonEntity` interface, while the `text_link` type may have an entity with the `TextLinkEntity` interface, as it includes additional properties like `url`. + +Here is the full list of interfaces and the output for each entity type: + +| Entity Type | Interface | Result | +| ---------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `blockquote` | `CommonEntity` | `
...
` | +| `bold` | `CommonEntity` | ` ... ` | +| `bot_command` | `CommonEntity` | ` ... ` | +| `cashtag` | `CommonEntity` | ` ... ` | +| `code` | `CommonEntity` | ` ... ` | +| `custom_emoji` | `CustomEmojiEntity` | ` ... ` | +| `email` | `CommonEntity` | ` ... ` | +| `expandableBlockquote` | `CommonEntity` | `
...
` | +| `hashtag` | `CommonEntity` | ` ... ` | +| `italic` | `CommonEntity` | ` ... ` | +| `mention` | `CommonEntity` | ` ... ` | +| `phone_number` | `CommonEntity` | ` ... ` | +| `pre` | `PreEntity` | `
 ...
` | +| `spoiler` | `CommonEntity` | ` ... ` | +| `strikethrough` | `CommonEntity` | ` ... ` | +| `text_link` | `TextLinkEntity` | ` ... ` | +| `text_mention` | `TextMentionEntity` | ` ... ` or ` ... ` | +| `underline` | `CommonEntity` | ` ... ` | +| `url` | `CommonEntity` | ` ... ` | + +If you are unsure which interface is correct, refer to how the [Renderer](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts) or [RendererHtml](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts) is implemented. + +### Customize the Text Sanitizer + +The output text is sanitized by default to ensure proper HTML rendering and prevent XSS vulnerabilities. + +| Input | Output | +| ----- | -------- | +| `&` | `&` | +| `<` | `<` | +| `>` | `>` | +| `"` | `"` | +| `'` | `'` | + +For example, the result `Bold & Italic` will be sanitized to `Bold & Italic`. + +You can override this behavior by specifying a `textSanitizer` when instantiating the [`EntitiesParser`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/mod.ts): + +- If you do not specify `textSanitizer`, it will default to using [`sanitizerHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/utils/sanitizer_html.ts) as the sanitizer. +- Setting the value to `false` will skip sanitization, keeping the output text as the original. + This is not recommended, as it may result in incorrect rendering and make your application vulnerable to XSS attacks. + Ensure proper handling if you choose this option. +- If you provide a function, it will be used instead of the default sanitizer. + +Example, + +```ts +const myTextSanitizer: TextSanitizer = (options: TextSanitizerOption): string => + // Replace dangerous character + options.text.replace(/[&<>"']/g, (match) => { + switch (match) { + case "&": + return "&"; + case "<": + return "<"; + case ">": + return ">"; + case '"': + return """; + case "'": + return "'"; + default: + return match; + } + }); + +// Implement the sanitizer. +const entitiesParser = new EntitiesParser({ textSanitizer: myTextSanitizer }); +``` + +## Cases When It's Better to Not Use This Package + +If you face problems similar to those listed below, you might be able to resolve them without using this package. + +### Copy and Forward the Same Message + +Use [`forwardMessage`](https://core.telegram.org/bots/api#forwardmessage) to forward messages of any kind. + +You can also use the [`copyMessage`](https://core.telegram.org/bots/api#copymessage) API, which performs the same action but does not include a link to the original message. +[`copyMessage`](https://core.telegram.org/bots/api#copymessage) behaves like copying the message and sending it back to Telegram, making it appear as a regular message rather than a forwarded one. + +Example: + +```ts +bot.on(":text", async (ctx) => { + // The target chat id to send. + const chatId = "-946659600"; + // Forward the current message without a link to the original message. + await ctx.copyMessage(chatId); + // Forward the current message with a link to the original message. + await ctx.forwardMessage(chatId); +}); +``` + +### Reply to Messages with Modified Text Format + +You can easily reply to incoming messages using HTML, Markdown, or entities. + +```ts +bot.on(":text", async (ctx) => { + // Reply using HTML + await ctx.reply("bold italic", { parse_mode: "HTML" }); + // Reply using Telegram Markdown V2 + await ctx.reply("*bold* _italic_", { parse_mode: "MarkdownV2" }); + // Reply with entities + await ctx.reply("bold italic", { + entities: [ + { offset: 0, length: 5, type: "bold" }, + { offset: 5, length: 6, type: "italic" }, + ], + }); +}); +``` + +grammY also provides a useful plugin called [`parse-mode`](./parse-mode) for better message formatting. +You can format messages like this: + +```ts +ctx.replyFmt(fmt`${bold("bold")} ${italic("italic")}`); +``` + +[Check it out](./parse-mode) if you're interested. + +## Plugin Summary + +- Name: telegram-entities-parser +- Package: +- Source: From af7be6df10b7fc8196ed36eb3a837f6e4a506305 Mon Sep 17 00:00:00 2001 From: qz Date: Wed, 18 Sep 2024 07:07:45 +0700 Subject: [PATCH 05/37] update plugin list --- site/docs/.vitepress/configs/locales/en.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/.vitepress/configs/locales/en.ts b/site/docs/.vitepress/configs/locales/en.ts index cdbce35b7b..ed04607fe7 100644 --- a/site/docs/.vitepress/configs/locales/en.ts +++ b/site/docs/.vitepress/configs/locales/en.ts @@ -263,7 +263,7 @@ const pluginThirdparty = { }, { text: "Convert Telegram Entities", - link: "/plugins/grammy-entity", + link: "/plugins/telegram-entities-parser", }, { text: "[Submit your PR!]", From 56a6e47dd33dd3678f3ec1ccb0b276a469cdea0f Mon Sep 17 00:00:00 2001 From: qz Date: Wed, 18 Sep 2024 07:09:50 +0700 Subject: [PATCH 06/37] remove the old file --- site/docs/plugins/grammy-entity.md | 125 ----------------------------- 1 file changed, 125 deletions(-) delete mode 100644 site/docs/plugins/grammy-entity.md diff --git a/site/docs/plugins/grammy-entity.md b/site/docs/plugins/grammy-entity.md deleted file mode 100644 index 760c5c045c..0000000000 --- a/site/docs/plugins/grammy-entity.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -prev: false -next: false ---- - -# Convert Telegram Entities (grammy-entity) - -Converts [Telegram entities](https://core.telegram.org/bots/api#messageentity) to [HTML](https://core.telegram.org/bots/api#html-style) or [Markdown](https://core.telegram.org/bots/api#markdownv2-style). - -## When Should I Use This? - -Probably NEVER! - -While this plugin can generate Telegram-compatible HTML or MarkdownV2, it’s usually best to just send the text and entities back to Telegram. - -Converting them to HTML or Markdown is only necessary in those rare cases when you need to use Telegram-formatted text **outside** of Telegram itself. - -If you’re still unsure whether this plugin is the right fit for your use case, please don’t hesitate to ask in our [Telegram group](https://t.me/grammyjs). -In most cases, people find they don’t actually need this plugin to solve their problems! - -## Installation - -Simply run this line of code in your terminal. - -::: code-group - -```sh:no-line-numbers [Deno] -deno add @qz/grammy-entity -``` - -```sh:no-line-numbers [Bun] -bunx jsr add @qz/grammy-entity -``` - -```sh:no-line-numbers [pnpm] -pnpm dlx jsr add @qz/grammy-entity -``` - -```sh:no-line-numbers [Yarn] -yarn dlx jsr add @qz/grammy-entity -``` - -```sh:no-line-numbers [npm] -npx jsr add @qz/grammy-entity -``` - -::: - -## Simple Usage - -Using this plugin is super straightforward! -Here’s a quick example. - -```ts -import { toHTML, toMarkdownV2 } from "@qz/grammy-entity"; - -bot.on(":text", (ctx) => { - const html = toHTML(ctx.msg); // Convert text to HTML string - const md = toMarkdownV2(ctx.msg); // Convert text to MarkdownV2 string -}); -``` - -Both functions will also work with captioned messages, such as photos or videos. - -```ts -bot.on(":photo", (ctx) => { - const html = toHTML(ctx.msg); // Convert caption to HTML string - const md = toMarkdownV2(ctx.msg); // Convert caption to MarkdownV2 string -}); -``` - -You can also pass a text and entities object directly: - -```ts -toHTML({ text: '...', entities: [...] }); // Get the HTML string -``` - -## Advanced Usage - -The `toHTML` and `toMarkdown` functions are designed to produce HTML or Markdown that’s compatible with Telegram, which is a sensible default for a Telegram library. - -However, if you want to serialize your data differently for another system, you can do that too! -Simply use the `serializeWith` function. - -To get started, you’ll need to create a serializer with the following type. - -```ts -import type { Serializer } from "@qz/grammy-entity"; - -const myHTMLSerializer: Serializer (match, node) { - // Your custom implementation here -} -``` - -Each matched node will be passed to your function, and you only need to wrap it however you like! - -If you’re looking for inspiration, check out the implementation of the [serializers](https://github.com/quadratz/grammy-entity/blob/main/src/serializers.ts). -You can easily copy, paste, and tweak it to fit your needs. - -We’ve also got some built-in escapers available for your convenience. - -```ts -import { escapeHtml, escapeMarkdownV2, type Escaper } from "@qz/grammy-entity"; - -escapeHtml(text); // Get HTML escaped text -escapeMarkdownV2(text); // Escape text for Telegram's MarkdownV2 - -// Or create your own escaper -const myEscaper: Escaper = (match) => {/* Your implementation here */}; -``` - -With these tools at your disposal, you can whip up your own HTML serializer like this: - -```ts -import { escapeHtml, serializeWith } from "@qz/grammy-entity"; - -const serialize = serializeWith(myHTMLSerializer, escapeHtml); -serialize(ctx.msg); -``` - -## Plugin Summary - -- Name: grammy-entity -- Package: -- Source: From ab91a757399847ad4b8b13f876f06e475f70e6ae Mon Sep 17 00:00:00 2001 From: qz Date: Wed, 18 Sep 2024 07:25:48 +0700 Subject: [PATCH 07/37] fix formatting --- site/docs/plugins/telegram-entities-parser.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/site/docs/plugins/telegram-entities-parser.md b/site/docs/plugins/telegram-entities-parser.md index 3de12bd515..35997696a0 100644 --- a/site/docs/plugins/telegram-entities-parser.md +++ b/site/docs/plugins/telegram-entities-parser.md @@ -7,7 +7,6 @@ next: false Converts [Telegram entities](https://core.telegram.org/bots/api#messageentity) to semantic HTML. -Specially designed for [grammY](https://grammy.dev/plugins/telegram-entities-parser), but should also compatible with other framework. ## When Should I Use This? @@ -17,7 +16,7 @@ While this plugin can generate HTML, it's generally best to send the text and en Converting them to HTML is only necessary in rare cases where you need to use Telegram-formatted text **outside** of Telegram itself, such as displaying Telegram messages on a website. -See the [_Cases When It's Better to Not Use This Package_](#cases-when-its-better-to-not-use-this-package) section to determine if you have a similar problem to solve. +See the [_Cases When It's Better to Not Use This Package_](#cases-when-it-s-better-to-not-use-this-package) section to determine if you have a similar problem to solve. If you're unsure whether this plugin is the right fit for your use case, please don't hesitate to ask in our [Telegram group](https://t.me/grammyjs). In most cases, people find they don't actually need this plugin to solve their problems! @@ -231,6 +230,8 @@ bot.on(":text", async (ctx) => { }); ``` +::: tip Use parse-mode for a Better Formatting Experience + grammY also provides a useful plugin called [`parse-mode`](./parse-mode) for better message formatting. You can format messages like this: @@ -239,6 +240,7 @@ ctx.replyFmt(fmt`${bold("bold")} ${italic("italic")}`); ``` [Check it out](./parse-mode) if you're interested. +::: ## Plugin Summary From 1f4bbdae87d2d1bc6cd68511803c21aa70f19663 Mon Sep 17 00:00:00 2001 From: qz Date: Sun, 22 Sep 2024 09:03:07 +0700 Subject: [PATCH 08/37] Rename plugin name to `entity-parser` --- site/docs/.vitepress/configs/locales/en.ts | 4 ++-- .../plugins/{telegram-entities-parser.md => entity-parser.md} | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) rename site/docs/plugins/{telegram-entities-parser.md => entity-parser.md} (99%) diff --git a/site/docs/.vitepress/configs/locales/en.ts b/site/docs/.vitepress/configs/locales/en.ts index ed04607fe7..7460e4b331 100644 --- a/site/docs/.vitepress/configs/locales/en.ts +++ b/site/docs/.vitepress/configs/locales/en.ts @@ -262,8 +262,8 @@ const pluginThirdparty = { link: "/plugins/autoquote", }, { - text: "Convert Telegram Entities", - link: "/plugins/telegram-entities-parser", + text: "Entity Parser", + link: "/plugins/entity-parser", }, { text: "[Submit your PR!]", diff --git a/site/docs/plugins/telegram-entities-parser.md b/site/docs/plugins/entity-parser.md similarity index 99% rename from site/docs/plugins/telegram-entities-parser.md rename to site/docs/plugins/entity-parser.md index 35997696a0..a9041e15ca 100644 --- a/site/docs/plugins/telegram-entities-parser.md +++ b/site/docs/plugins/entity-parser.md @@ -3,7 +3,7 @@ prev: false next: false --- -# Convert Telegram Entities (telegram-entities-parser) +# Entity Parser (`entity-parser`) Converts [Telegram entities](https://core.telegram.org/bots/api#messageentity) to semantic HTML. @@ -244,6 +244,6 @@ ctx.replyFmt(fmt`${bold("bold")} ${italic("italic")}`); ## Plugin Summary -- Name: telegram-entities-parser +- Name: entity-parser - Package: - Source: From 63b72f5ba2e41b1e19fbc5dac424a46e45e65af1 Mon Sep 17 00:00:00 2001 From: qz Date: Sun, 22 Sep 2024 09:12:12 +0700 Subject: [PATCH 09/37] Fix typo entity type `expandableBlockquote` --- site/docs/plugins/entity-parser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/plugins/entity-parser.md b/site/docs/plugins/entity-parser.md index a9041e15ca..775d54684b 100644 --- a/site/docs/plugins/entity-parser.md +++ b/site/docs/plugins/entity-parser.md @@ -123,7 +123,7 @@ Here is the full list of interfaces and the output for each entity type: | `code` | `CommonEntity` | ` ... ` | | `custom_emoji` | `CustomEmojiEntity` | ` ... ` | | `email` | `CommonEntity` | ` ... ` | -| `expandableBlockquote` | `CommonEntity` | `
...
` | +| `expandable_blockquote` | `CommonEntity` | `
...
` | | `hashtag` | `CommonEntity` | ` ... ` | | `italic` | `CommonEntity` | ` ... ` | | `mention` | `CommonEntity` | ` ... ` | From 26e163f15de455b147d2dee32504237ee3a57f0c Mon Sep 17 00:00:00 2001 From: Qz Date: Mon, 23 Sep 2024 17:35:37 +0700 Subject: [PATCH 10/37] Apply suggestions from code review Co-authored-by: Roj --- site/docs/plugins/entity-parser.md | 22 +++++----------------- 1 file changed, 5 insertions(+), 17 deletions(-) diff --git a/site/docs/plugins/entity-parser.md b/site/docs/plugins/entity-parser.md index 775d54684b..24b6aef7ce 100644 --- a/site/docs/plugins/entity-parser.md +++ b/site/docs/plugins/entity-parser.md @@ -5,8 +5,7 @@ next: false # Entity Parser (`entity-parser`) -Converts [Telegram entities](https://core.telegram.org/bots/api#messageentity) -to semantic HTML. +Converts [Telegram entities](https://core.telegram.org/bots/api#messageentity) to semantic HTML. ## When Should I Use This? @@ -71,12 +70,12 @@ bot.on(":photo", (ctx) => { }); ``` -## Advanced usage +## Advanced Usage ### Customize the Output HTML Tag This package converts entities into semantic HTML, adhering to best practices and standards as closely as possible. -However, you might find that the provided output is not exactly what you expected. +However, the provided output might not always be what you expect. To address this, you can use your own `renderer` to customize the HTML elements surrounding the text according to your rules. You can modify specific rules by extending the default [`RendererHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts) or override all the rules by implementing the [`Renderer`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts). @@ -160,8 +159,6 @@ You can override this behavior by specifying a `textSanitizer` when instantiatin Ensure proper handling if you choose this option. - If you provide a function, it will be used instead of the default sanitizer. -Example, - ```ts const myTextSanitizer: TextSanitizer = (options: TextSanitizerOption): string => // Replace dangerous character @@ -197,12 +194,10 @@ Use [`forwardMessage`](https://core.telegram.org/bots/api#forwardmessage) to for You can also use the [`copyMessage`](https://core.telegram.org/bots/api#copymessage) API, which performs the same action but does not include a link to the original message. [`copyMessage`](https://core.telegram.org/bots/api#copymessage) behaves like copying the message and sending it back to Telegram, making it appear as a regular message rather than a forwarded one. -Example: - ```ts bot.on(":text", async (ctx) => { // The target chat id to send. - const chatId = "-946659600"; + const chatId = -946659600; // Forward the current message without a link to the original message. await ctx.copyMessage(chatId); // Forward the current message with a link to the original message. @@ -232,14 +227,7 @@ bot.on(":text", async (ctx) => { ::: tip Use parse-mode for a Better Formatting Experience -grammY also provides a useful plugin called [`parse-mode`](./parse-mode) for better message formatting. -You can format messages like this: - -```ts -ctx.replyFmt(fmt`${bold("bold")} ${italic("italic")}`); -``` - -[Check it out](./parse-mode) if you're interested. +Use the official plugin [`parse-mode`](./parse-mode) for a better experience constructing formatted messages. ::: ## Plugin Summary From 47ae41a14c73ae98923614a65371a10b9867dee9 Mon Sep 17 00:00:00 2001 From: qz Date: Mon, 23 Sep 2024 17:54:29 +0700 Subject: [PATCH 11/37] fix fmt --- site/docs/plugins/entity-parser.md | 40 +++++++++++++++--------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/site/docs/plugins/entity-parser.md b/site/docs/plugins/entity-parser.md index 24b6aef7ce..d57f9fa8d9 100644 --- a/site/docs/plugins/entity-parser.md +++ b/site/docs/plugins/entity-parser.md @@ -113,27 +113,27 @@ The `options` parameter accepts an object with `text` and `entity`. Here is the full list of interfaces and the output for each entity type: -| Entity Type | Interface | Result | -| ---------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `blockquote` | `CommonEntity` | `
...
` | -| `bold` | `CommonEntity` | ` ... ` | -| `bot_command` | `CommonEntity` | ` ... ` | -| `cashtag` | `CommonEntity` | ` ... ` | -| `code` | `CommonEntity` | ` ... ` | -| `custom_emoji` | `CustomEmojiEntity` | ` ... ` | -| `email` | `CommonEntity` | ` ... ` | +| Entity Type | Interface | Result | +| ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `blockquote` | `CommonEntity` | `
...
` | +| `bold` | `CommonEntity` | ` ... ` | +| `bot_command` | `CommonEntity` | ` ... ` | +| `cashtag` | `CommonEntity` | ` ... ` | +| `code` | `CommonEntity` | ` ... ` | +| `custom_emoji` | `CustomEmojiEntity` | ` ... ` | +| `email` | `CommonEntity` | ` ... ` | | `expandable_blockquote` | `CommonEntity` | `
...
` | -| `hashtag` | `CommonEntity` | ` ... ` | -| `italic` | `CommonEntity` | ` ... ` | -| `mention` | `CommonEntity` | ` ... ` | -| `phone_number` | `CommonEntity` | ` ... ` | -| `pre` | `PreEntity` | `
 ...
` | -| `spoiler` | `CommonEntity` | ` ... ` | -| `strikethrough` | `CommonEntity` | ` ... ` | -| `text_link` | `TextLinkEntity` | ` ... ` | -| `text_mention` | `TextMentionEntity` | ` ... ` or ` ... ` | -| `underline` | `CommonEntity` | ` ... ` | -| `url` | `CommonEntity` | ` ... ` | +| `hashtag` | `CommonEntity` | ` ... ` | +| `italic` | `CommonEntity` | ` ... ` | +| `mention` | `CommonEntity` | ` ... ` | +| `phone_number` | `CommonEntity` | ` ... ` | +| `pre` | `PreEntity` | `
 ...
` | +| `spoiler` | `CommonEntity` | ` ... ` | +| `strikethrough` | `CommonEntity` | ` ... ` | +| `text_link` | `TextLinkEntity` | ` ... ` | +| `text_mention` | `TextMentionEntity` | ` ... ` or ` ... ` | +| `underline` | `CommonEntity` | ` ... ` | +| `url` | `CommonEntity` | ` ... ` | If you are unsure which interface is correct, refer to how the [Renderer](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts) or [RendererHtml](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts) is implemented. From e6014efbe2913ba4e8849705eac88306c029429c Mon Sep 17 00:00:00 2001 From: qz Date: Mon, 23 Sep 2024 22:39:07 +0700 Subject: [PATCH 12/37] fix typo --- site/docs/plugins/entity-parser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/plugins/entity-parser.md b/site/docs/plugins/entity-parser.md index d57f9fa8d9..7942eeaca4 100644 --- a/site/docs/plugins/entity-parser.md +++ b/site/docs/plugins/entity-parser.md @@ -127,7 +127,7 @@ Here is the full list of interfaces and the output for each entity type: | `italic` | `CommonEntity` | ` ... ` | | `mention` | `CommonEntity` | ` ... ` | | `phone_number` | `CommonEntity` | ` ... ` | -| `pre` | `PreEntity` | `
 ...
` | +| `pre` | `PreEntity` | `
 ...
` or `
 ...
` | | `spoiler` | `CommonEntity` | ` ... ` | | `strikethrough` | `CommonEntity` | ` ... ` | | `text_link` | `TextLinkEntity` | ` ... ` | From 1f889b9a9826a25bc2feb78c11cb4408ef57d5b8 Mon Sep 17 00:00:00 2001 From: Qz Date: Tue, 24 Sep 2024 02:47:44 +0700 Subject: [PATCH 13/37] Apply suggestions from code review Co-authored-by: KnorpelSenf --- site/docs/plugins/entity-parser.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/site/docs/plugins/entity-parser.md b/site/docs/plugins/entity-parser.md index 7942eeaca4..dc1dc6992c 100644 --- a/site/docs/plugins/entity-parser.md +++ b/site/docs/plugins/entity-parser.md @@ -15,7 +15,7 @@ While this plugin can generate HTML, it's generally best to send the text and en Converting them to HTML is only necessary in rare cases where you need to use Telegram-formatted text **outside** of Telegram itself, such as displaying Telegram messages on a website. -See the [_Cases When It's Better to Not Use This Package_](#cases-when-it-s-better-to-not-use-this-package) section to determine if you have a similar problem to solve. +See the [_Cases When It's Better Not to Use This Package_](#cases-when-it-s-better-not-to-use-this-package) section to determine if you have a similar problem to solve. If you're unsure whether this plugin is the right fit for your use case, please don't hesitate to ask in our [Telegram group](https://t.me/grammyjs). In most cases, people find they don't actually need this plugin to solve their problems! @@ -72,7 +72,7 @@ bot.on(":photo", (ctx) => { ## Advanced Usage -### Customize the Output HTML Tag +### Customizing the Output HTML Tag This package converts entities into semantic HTML, adhering to best practices and standards as closely as possible. However, the provided output might not always be what you expect. @@ -183,11 +183,11 @@ const myTextSanitizer: TextSanitizer = (options: TextSanitizerOption): string => const entitiesParser = new EntitiesParser({ textSanitizer: myTextSanitizer }); ``` -## Cases When It's Better to Not Use This Package +## Cases When It's Better Not to Use This Package If you face problems similar to those listed below, you might be able to resolve them without using this package. -### Copy and Forward the Same Message +### Copying and Forwarding the Same Message Use [`forwardMessage`](https://core.telegram.org/bots/api#forwardmessage) to forward messages of any kind. @@ -205,7 +205,7 @@ bot.on(":text", async (ctx) => { }); ``` -### Reply to Messages with Modified Text Format +### Replying to Messages with Modified Text Format You can easily reply to incoming messages using HTML, Markdown, or entities. @@ -227,7 +227,7 @@ bot.on(":text", async (ctx) => { ::: tip Use parse-mode for a Better Formatting Experience -Use the official plugin [`parse-mode`](./parse-mode) for a better experience constructing formatted messages. +Use the official [`parse-mode`](./parse-mode) plugin for a better experience constructing formatted messages. ::: ## Plugin Summary From cd83a9076534dba8150c2d1c9b151723f918dd09 Mon Sep 17 00:00:00 2001 From: Qz Date: Tue, 24 Sep 2024 03:15:06 +0700 Subject: [PATCH 14/37] Apply suggestions from code review --- site/docs/plugins/entity-parser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/plugins/entity-parser.md b/site/docs/plugins/entity-parser.md index dc1dc6992c..f07c334427 100644 --- a/site/docs/plugins/entity-parser.md +++ b/site/docs/plugins/entity-parser.md @@ -162,7 +162,7 @@ You can override this behavior by specifying a `textSanitizer` when instantiatin ```ts const myTextSanitizer: TextSanitizer = (options: TextSanitizerOption): string => // Replace dangerous character - options.text.replace(/[&<>"']/g, (match) => { + options.text.replaceAll(/[&<>"']/, (match) => { switch (match) { case "&": return "&"; From 8170e593dee2f4faf7b361072fa1688dc04f73e9 Mon Sep 17 00:00:00 2001 From: qz Date: Mon, 14 Oct 2024 07:08:02 +0700 Subject: [PATCH 15/37] Sync changes to Indonesian --- site/docs/id/guide/reactions.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/site/docs/id/guide/reactions.md b/site/docs/id/guide/reactions.md index 0a1a9c1aa8..5cbd15575e 100644 --- a/site/docs/id/guide/reactions.md +++ b/site/docs/id/guide/reactions.md @@ -46,8 +46,9 @@ Terdapat beberapa cara untuk menangani update berupa reaksi. Di chat pribadi dan grup, bot akan menerima sebuah update `message_reaction` jika seorang user mengubah reaksi suatu pesan. Di channel (atau postingan channel yang diteruskan ke grup secara otomatis), bot akan menerima sebuah update `message_reaction_count` yang berisi jumlah total reaksinya saja, tanpa menampilkan siapa yang mereaksi. -Untuk menerima update kedua jenis reaksi tersebut, kamu perlu mengaktifkannya terlebih dahulu. -Berikut contoh cara mengaktifkannya dengan menggunakan [long polling](./deployment-types#long-polling-vs-webhook) bawaan. +Untuk menerima kedua jenis update tersebut, **bot harus menjadi administrator** di chat yang bersangkutan. +Selain itu, `allowed_updates` juga perlu diaktikan. +Berikut contoh cara mengaktifkannya menggunakan [long polling](./deployment-types#long-polling-vs-webhook) bawaan. ```ts bot.start({ From af2832f38e1d65875e77392122af27caf5ad3a87 Mon Sep 17 00:00:00 2001 From: qz Date: Mon, 14 Oct 2024 07:12:18 +0700 Subject: [PATCH 16/37] Revert "Sync changes to Indonesian" This reverts commit 8170e593dee2f4faf7b361072fa1688dc04f73e9. --- site/docs/id/guide/reactions.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/site/docs/id/guide/reactions.md b/site/docs/id/guide/reactions.md index 5cbd15575e..0a1a9c1aa8 100644 --- a/site/docs/id/guide/reactions.md +++ b/site/docs/id/guide/reactions.md @@ -46,9 +46,8 @@ Terdapat beberapa cara untuk menangani update berupa reaksi. Di chat pribadi dan grup, bot akan menerima sebuah update `message_reaction` jika seorang user mengubah reaksi suatu pesan. Di channel (atau postingan channel yang diteruskan ke grup secara otomatis), bot akan menerima sebuah update `message_reaction_count` yang berisi jumlah total reaksinya saja, tanpa menampilkan siapa yang mereaksi. -Untuk menerima kedua jenis update tersebut, **bot harus menjadi administrator** di chat yang bersangkutan. -Selain itu, `allowed_updates` juga perlu diaktikan. -Berikut contoh cara mengaktifkannya menggunakan [long polling](./deployment-types#long-polling-vs-webhook) bawaan. +Untuk menerima update kedua jenis reaksi tersebut, kamu perlu mengaktifkannya terlebih dahulu. +Berikut contoh cara mengaktifkannya dengan menggunakan [long polling](./deployment-types#long-polling-vs-webhook) bawaan. ```ts bot.start({ From c69a09840af60240146fca8df8cfd7a3498f76d5 Mon Sep 17 00:00:00 2001 From: Qz Date: Wed, 16 Oct 2024 14:10:13 +0700 Subject: [PATCH 17/37] Update site/docs/plugins/entity-parser.md Co-authored-by: KnorpelSenf --- site/docs/plugins/entity-parser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/plugins/entity-parser.md b/site/docs/plugins/entity-parser.md index f07c334427..0cfe641d5a 100644 --- a/site/docs/plugins/entity-parser.md +++ b/site/docs/plugins/entity-parser.md @@ -27,7 +27,7 @@ Run the following command in your terminal based on your runtime or package mana ::: code-group ```sh:no-line-numbers [Deno] -deno add @qz/telegram-entities-parser +deno add jsr:@qz/telegram-entities-parser ``` ```sh:no-line-numbers [Bun] From 300c5b6f3454d4ab8190a68d22ea2d8c7de8f879 Mon Sep 17 00:00:00 2001 From: qz Date: Wed, 16 Oct 2024 14:18:01 +0700 Subject: [PATCH 18/37] Sync deno 2.0 --- site/docs/plugins/entity-parser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/plugins/entity-parser.md b/site/docs/plugins/entity-parser.md index 0cfe641d5a..1d59a7599b 100644 --- a/site/docs/plugins/entity-parser.md +++ b/site/docs/plugins/entity-parser.md @@ -92,7 +92,7 @@ import type { // Change the rule for bold type entity, // but leave the rest of the types as defined by `RendererHtml`. class MyRenderer extends RendererHtml { - bold( + override bold( options: { text: string; entity: CommonEntity }, ): RendererOutput { return { From f0e2f620a5bb4a7b833d9ff78f1189f1660f6106 Mon Sep 17 00:00:00 2001 From: MasedMSD <68379695+MasedMSD@users.noreply.github.com> Date: Fri, 22 Nov 2024 15:24:24 +0500 Subject: [PATCH 19/37] sync Russian --- site/docs/.vitepress/configs/locales/ru.ts | 4 + site/docs/ru/plugins/entity-parser.md | 237 +++++++++++++++++++++ 2 files changed, 241 insertions(+) create mode 100644 site/docs/ru/plugins/entity-parser.md diff --git a/site/docs/.vitepress/configs/locales/ru.ts b/site/docs/.vitepress/configs/locales/ru.ts index 5808491f1b..9aec7343db 100644 --- a/site/docs/.vitepress/configs/locales/ru.ts +++ b/site/docs/.vitepress/configs/locales/ru.ts @@ -230,6 +230,10 @@ const pluginThirdparty = { text: "Полезный Middleware", link: "/ru/plugins/middlewares", }, + { + text: "Парсер сущностей", + link: "/ru/plugins/entity-parser", + }, { text: "Автоцитата", link: "/ru/plugins/autoquote", diff --git a/site/docs/ru/plugins/entity-parser.md b/site/docs/ru/plugins/entity-parser.md new file mode 100644 index 0000000000..161e095b32 --- /dev/null +++ b/site/docs/ru/plugins/entity-parser.md @@ -0,0 +1,237 @@ +--- +prev: false +next: false +--- + +# Парсер сущностей (`entity-parser`) + +Преобразует [сущности Telegram](https://core.telegram.org/bots/api#messageentity) в семантический HTML. + +## Когда стоит это использовать? + +Вероятно, НИКОГДА! + +Хотя этот плагин может генерировать HTML, в большинстве случаев лучше передавать текст и сущности обратно в Telegram. + +Преобразование в HTML требуется только в редких случаях, например, если вам нужно использовать текст с форматированием Telegram **вне** самого Telegram, например, для отображения сообщений на сайте. + +Посмотрите раздел [_Случаи, когда лучше не использовать этот пакет_](#случаи-когда-лучше-не-использовать-этот-пакет), чтобы понять, сталкиваетесь ли вы с аналогичной задачей. + +Если вы не уверены, подходит ли этот плагин для вашего случая, не стесняйтесь задавать вопросы в наших [англоязычном](https://t.me/grammyjs) и [русскоязычном](https://t.me/grammyjs_ru) чатах. +В большинстве случаев выясняется, что для решения ваших задач этот плагин не нужен! + +## Уставнока + +Выполните следующую команду в вашем терминале, исходя из используемого пакетного менеджера: + +::: code-group + +```sh:no-line-numbers [Deno] +deno add jsr:@qz/telegram-entities-parser +``` + +```sh:no-line-numbers [Bun] +bunx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [pnpm] +pnpm dlx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [Yarn] +yarn dlx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [npm] +npx jsr add @qz/telegram-entities-parser +``` + +::: + +## Простое использование + +Использовать этот плагин очень просто. +Вот краткий пример: + +```ts +import { EntitiesParser } from "@qz/telegram-entities-parser"; +import type { Message } from "@qz/telegram-entities-parser/types"; + +// Для повышения производительности создайте парсер вне функции. +const entitiesParser = new EntitiesParser(); +const parse = (message: Message) => entitiesParser.parse({ message }); + +bot.on(":text", (ctx) => { + const html = parse(ctx.msg); // Преобразует текст в строку HTML +}); + +bot.on(":photo", (ctx) => { + const html = parse(ctx.msg); // Преобразует подпись к фото в строку HTML +}); +``` + +## Расширенное использование + +### Настройка выходного HTML тега + +Этот пакет преобразует сущности в семантический HTML, следуя лучшим практикам и стандартам настолько близко, насколько это возможно. +Однако предоставленный результат может не всегда соответствовать вашим ожиданиям. + +Чтобы это исправить, вы можете использовать собственный `renderer` для настройки HTML тегов, окружающих текст, в соответствии с вашими правилами. +Вы можете изменить конкретные правила, расширив стандартный [`RendererHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts), или переопределить все правила, реализовав собственный [`Renderer`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts). + +Чтобы расширить существующий `renderer`, выполните следующие шаги: + +```ts +import { EntitiesParser, RendererHtml } from "@qz/telegram-entities-parser"; +import type { + CommonEntity, + RendererOutput, +} from "@qz/telegram-entities-parser/types"; + +// Изменение правила для жирного текста, +// оставив остальные типы, определенные в `RendererHtml`. +class MyRenderer extends RendererHtml { + override bold( + options: { text: string; entity: CommonEntity }, + ): RendererOutput { + return { + prefix: '', + suffix: "", + }; + } +} + +const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); +``` + +Параметр `options` принимает объект с полями `text` и `entity`. + +- `text`: Конкретный текст, к которому относится текущая сущность. +- `entity`: Может быть представлен различными интерфейсами в зависимости от типа сущности, такими как `CommonEntity`, `CustomEmojiEntity`, `PreEntity`, `TextLinkEntity` или `TextMentionEntity`. + Например, сущность типа `bold` имеет интерфейс `CommonEntity`, тогда как тип `text_link` может иметь интерфейс `TextLinkEntity`, так как включает дополнительные свойства, такие как `url`. + +Вот полный список интерфейсов и выходных данных для каждого типа сущности: + +| Entity Type | Interface | Result | +| ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `blockquote` | `CommonEntity` | `
...
` | +| `bold` | `CommonEntity` | ` ... ` | +| `bot_command` | `CommonEntity` | ` ... ` | +| `cashtag` | `CommonEntity` | ` ... ` | +| `code` | `CommonEntity` | ` ... ` | +| `custom_emoji` | `CustomEmojiEntity` | ` ... ` | +| `email` | `CommonEntity` | ` ... ` | +| `expandable_blockquote` | `CommonEntity` | `
...
` | +| `hashtag` | `CommonEntity` | ` ... ` | +| `italic` | `CommonEntity` | ` ... ` | +| `mention` | `CommonEntity` | ` ... ` | +| `phone_number` | `CommonEntity` | ` ... ` | +| `pre` | `PreEntity` | `
 ...
` or `
 ...
` | +| `spoiler` | `CommonEntity` | ` ... ` | +| `strikethrough` | `CommonEntity` | ` ... ` | +| `text_link` | `TextLinkEntity` | ` ... ` | +| `text_mention` | `TextMentionEntity` | ` ... ` or ` ... ` | +| `underline` | `CommonEntity` | ` ... ` | +| `url` | `CommonEntity` | ` ... ` | + +Если вы не уверены, какой интерфейс использовать, обратитесь к реализации [Renderer](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts) или [RendererHtml](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts). + +### Настройка санитайзера текста + +Выводимый текст по умолчанию проходит санитизацию для обеспечения корректного HTML-рендеринга и предотвращения XSS уязвимостей. + +| Ввод | Вывод | +| ----- | -------- | +| `&` | `&` | +| `<` | `<` | +| `>` | `>` | +| `"` | `"` | +| `'` | `'` | + +Например, результат `Bold & Italic` будет санитизирован в `Bold & Italic`. + +Вы можете изменить это поведение, указав `textSanitizer` при создании экземпляра [`EntitiesParser`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/mod.ts): + +- Если вы не укажете `textSanitizer`, по умолчанию будет использоваться [`sanitizerHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/utils/sanitizer_html.ts) для санитизации. +- Установка значения в `false` отключит санитизацию, сохраняя текст вывода в исходном виде. + Это не рекомендуется, так как может привести к некорректному рендерингу и сделать ваше приложение уязвимым для XSS атак. + Если вы выбираете этот вариант, убедитесь в правильной обработке данных. +- Если вы предоставите функцию, она будет использована вместо стандартного санитайзера. + +```ts +const myTextSanitizer: TextSanitizer = (options: TextSanitizerOption): string => + // Замените опасные символы + options.text.replaceAll(/[&<>"']/, (match) => { + switch (match) { + case "&": + return "&"; + case "<": + return "<"; + case ">": + return ">"; + case '"': + return """; + case "'": + return "'"; + default: + return match; + } + }); + +// Используйте собственный санитайзер +const entitiesParser = new EntitiesParser({ textSanitizer: myTextSanitizer }); +``` + +## Случаи, когда лучше не использовать этот пакет + +Если вы сталкиваетесь с проблемами, подобными перечисленным ниже, возможно, вы сможете решить их без использования этого пакета. + +### Копирование и пересылка одного и того же сообщения + +Используйте метод [`forwardMessage`](https://core.telegram.org/bots/api#forwardmessage) для пересылки сообщений любого типа. + +Вы также можете воспользоваться методом [`copyMessage`](https://core.telegram.org/bots/api#copymessage), который выполняет ту же задачу, но без ссылки на оригинальное сообщение. +Метод [`copyMessage`](https://core.telegram.org/bots/api#copymessage) работает как копирование сообщения и отправка его обратно в Telegram, что делает его похожим на обычное сообщение, а не на пересланное. + +```ts +bot.on(":text", async (ctx) => { + // ID целевого чата для отправки. + const chatId = -946659600; + // Копировать текущее сообщение без ссылки на оригинальное. + await ctx.copyMessage(chatId); + // Переслать текущее сообщение с ссылкой на оригинальное. + await ctx.forwardMessage(chatId); +}); +``` + +### Ответ на сообщения с изменённым форматом текста + +Вы можете легко отвечать на входящие сообщения, используя HTML, Markdown или сущности. + +```ts +bot.on(":text", async (ctx) => { + // Ответ с использованием HTML + await ctx.reply("bold italic", { parse_mode: "HTML" }); + // Ответ с использованием Telegram Markdown V2 + await ctx.reply("*bold* _italic_", { parse_mode: "MarkdownV2" }); + // Ответ с использованием сущностей + await ctx.reply("bold italic", { + entities: [ + { offset: 0, length: 5, type: "bold" }, + { offset: 5, length: 6, type: "italic" }, + ], + }); +}); +``` + +::: tip Используйте parse-mode для улучшенного форматирования + +Используйте официальный плагин [`parse-mode`](./parse-mode) для более удобного создания форматированных сообщений. +::: + +## Краткая информация о плагине + +- Название: entity-parser +- Пакет: +- Исходник: From e29a5aad41b133e519a53a52c58501f9ac9c9333 Mon Sep 17 00:00:00 2001 From: Nazar Antoniuk Date: Fri, 22 Nov 2024 20:14:38 +0200 Subject: [PATCH 20/37] sync to Ukrainian --- site/docs/.vitepress/configs/locales/uk.ts | 4 + site/docs/uk/plugins/entity-parser.md | 238 +++++++++++++++++++++ 2 files changed, 242 insertions(+) create mode 100644 site/docs/uk/plugins/entity-parser.md diff --git a/site/docs/.vitepress/configs/locales/uk.ts b/site/docs/.vitepress/configs/locales/uk.ts index 0c9aebfdc0..59c8b41330 100644 --- a/site/docs/.vitepress/configs/locales/uk.ts +++ b/site/docs/.vitepress/configs/locales/uk.ts @@ -234,6 +234,10 @@ const pluginThirdparty = { text: "Автоматичне встановлення відповіді", link: "/uk/plugins/autoquote", }, + { + text: "Парсер сутностей", + link: "/uk/plugins/entity-parser", + }, { text: "[Відправте свій PR!]", link: "/uk/plugins/#створюите-власні-плагіни", diff --git a/site/docs/uk/plugins/entity-parser.md b/site/docs/uk/plugins/entity-parser.md new file mode 100644 index 0000000000..7e65763b38 --- /dev/null +++ b/site/docs/uk/plugins/entity-parser.md @@ -0,0 +1,238 @@ +--- +prev: false +next: false +--- + +# Парсер сутностей (`entity-parser`) + +Перетворює [сутності Telegram](https://core.telegram.org/bots/api#messageentity) у семантичний HTML. + +## Коли мені слід використовувати це? + +Напевно, ніколи! + +Хоча цей плагін може генерувати HTML, зазвичай краще надсилати до Telegram безпосередньо текст і сутності. + +Перетворення в HTML необхідне лише в рідкісних випадках, коли вам потрібно використовувати текст у форматі Telegram **поза межами** самого Telegram, наприклад, для відображення повідомлень Telegram на вебсайті. + +Перегляньте розділ [_Випадки, коли краще не використовувати цей пакет_](#випадки-коли-краще-не-використовувати-цей-пакет), щоб визначити, чи є у вас подібна проблема, яку потрібно вирішити. + +Якщо ви не впевнені, чи підходить цей плагін для вашого випадку використання, будь ласка, не соромтеся запитувати в нашій [групі в Telegram](https://t.me/grammyjs). +У більшості випадків люди приходять до висновку, що їм насправді не потрібен цей плагін для вирішення їхніх проблем! + +## Встановлення + +Запустіть наступну команду у вашому терміналі на основі вашого середовища виконання або пакетного менеджера: + +::: code-group + +```sh:no-line-numbers [Deno] +deno add jsr:@qz/telegram-entities-parser +``` + +```sh:no-line-numbers [Bun] +bunx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [pnpm] +pnpm dlx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [Yarn] +yarn dlx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [npm] +npx jsr add @qz/telegram-entities-parser +``` + +::: + +## Просте використання + +Використовувати цей плагін дуже просто. +Ось короткий приклад: + +```ts +import { EntitiesParser } from "@qz/telegram-entities-parser"; +import type { Message } from "@qz/telegram-entities-parser/types"; + +// Для кращої продуктивності створіть екземпляр поза функцією. +const entitiesParser = new EntitiesParser(); +const parse = (message: Message) => entitiesParser.parse({ message }); + +bot.on(":text", (ctx) => { + const html = parse(ctx.msg); // Перетворення тексту в рядок HTML. +}); + +bot.on(":photo", (ctx) => { + const html = parse(ctx.msg); // Перетворення підпису в рядок HTML. +}); +``` + +## Просунуте використання + +### Налаштування вихідного тегу HTML + +Цей пакет перетворює сутності у семантичний HTML, дотримуючись найкращих практик і стандартів, наскільки це можливо. +Однак, результат може не завжди відповідати вашим очікуванням. + +Щоб вирішити цю проблему, ви можете використати власний `renderer` для налаштування елементів HTML, що оточують текст, відповідно до ваших правил. +Ви можете змінити певні правила, розширивши стандартний [`RendererHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts) або перевизначити всі правила, застосувавши [`Renderer`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts). + +Щоб розширити існуючий `renderer`, зробіть наступне: + +```ts +import { EntitiesParser, RendererHtml } from "@qz/telegram-entities-parser"; +import type { + CommonEntity, + RendererOutput, +} from "@qz/telegram-entities-parser/types"; + +// Змініть правило для сутності з жирним шрифтом, +// залишивши решту типів, як визначено у `RendererHtml`. +class MyRenderer extends RendererHtml { + override bold( + options: { text: string; entity: CommonEntity }, + ): RendererOutput { + return { + prefix: '', + suffix: "", + }; + } +} + +const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); +``` + +Параметр `options` приймає обʼєкт з `text` та `entity`. + +- `text`: конкретний текст, на який посилається поточна сутність. +- `entity`: залежно від типу сутності може бути представлений різними інтерфейсами, як-от `CommonEntity`, `CustomEmojiEntity`, `PreEntity`, `TextLinkEntity` або `TextMentionEntity`. + Наприклад, тип `bold` має сутність з інтерфейсом `CommonEntity`, тоді як тип `text_link` може мати сутність з інтерфейсом `TextLinkEntity`, оскільки він включає додаткові властивості, наприклад, `url`. + +Ось повний список інтерфейсів та результати для кожного типу сутності: + +| Тип сутності | Інтерфейс | Результат | +| ----------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `blockquote` | `CommonEntity` | `
...
` | +| `bold` | `CommonEntity` | ` ... ` | +| `bot_command` | `CommonEntity` | ` ... ` | +| `cashtag` | `CommonEntity` | ` ... ` | +| `code` | `CommonEntity` | ` ... ` | +| `custom_emoji` | `CustomEmojiEntity` | ` ... ` | +| `email` | `CommonEntity` | ` ... ` | +| `expandable_blockquote` | `CommonEntity` | `
...
` | +| `hashtag` | `CommonEntity` | ` ... ` | +| `italic` | `CommonEntity` | ` ... ` | +| `mention` | `CommonEntity` | ` ... ` | +| `phone_number` | `CommonEntity` | ` ... ` | +| `pre` | `PreEntity` | `
 ...
` або `
 ...
` | +| `spoiler` | `CommonEntity` | ` ... ` | +| `strikethrough` | `CommonEntity` | ` ... ` | +| `text_link` | `TextLinkEntity` | ` ... ` | +| `text_mention` | `TextMentionEntity` | ` ... ` або ` ... ` | +| `underline` | `CommonEntity` | ` ... ` | +| `url` | `CommonEntity` | ` ... ` | + +Якщо ви не впевнені, який інтерфейс правильний, зверніться до того, як реалізовано [Renderer](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts) або [RendererHtml](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts). + +### Налаштування санітайзера тексту + +Вихідний текст за замовчуванням очищується, щоб забезпечити правильне відображення HTML і запобігти XSS-вразливостям. + +| Вхідний символ | Вихідна сутність HTML | +| -------------- | --------------------- | +| `&` | `&` | +| `<` | `<` | +| `>` | `>` | +| `"` | `"` | +| `'` | `'` | + +Наприклад, результат `Жирний & Курсив` буде очищено до `Жирний & Курсив`. + +Ви можете змінити цю поведінку, вказавши `textSanitizer` при створенні екземпляра [`EntitiesParser`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/mod.ts): + +- Якщо ви не вкажете `textSanitizer`, буде використано [`sanitizerHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/utils/sanitizer_html.ts) як типовий санітайзер. +- Якщо вказати значення `false`, очищення буде пропущено, а виведений текст буде збережено як оригінал. + Це не рекомендується, оскільки може призвести до некоректного рендерингу і зробити вашу програму вразливою до XSS-атак. + Якщо ви вибрали цю опцію, забезпечте належну обробку результату. +- Якщо ви надасте функцію, вона буде використовуватися замість типового санітайзера. + +```ts +const myTextSanitizer: TextSanitizer = (options: TextSanitizerOption): string => + // Замінюємо небезпечні символи. + options.text.replaceAll(/[&<>"']/, (match) => { + switch (match) { + case "&": + return "&"; + case "<": + return "<"; + case ">": + return ">"; + case '"': + return """; + case "'": + return "'"; + default: + return match; + } + }); + +// Застосовуємо санітайзер. +const entitiesParser = new EntitiesParser({ textSanitizer: myTextSanitizer }); +``` + +## Випадки, коли краще не використовувати цей пакет + +Якщо ви зіткнулися з проблемами, подібними до наведених нижче, можливо, вам вдасться вирішити їх без використання цього пакету. + +### Копіювання та пересилання одного і того ж повідомлення + +Використовуйте [`forwardMessage`](https://core.telegram.org/bots/api#forwardmessage) для пересилання повідомлень будь-якого типу. + +Ви також можете використовувати [`copyMessage`](https://core.telegram.org/bots/api#copymessage), який виконає ту ж саму дію, але не міститиме посилання на оригінальне повідомлення. +[`copyMessage`](https://core.telegram.org/bots/api#copymessage) поводиться так, ніби копіює повідомлення і надсилає його назад у Telegram, при цьому воно відображається як звичайне повідомлення, а не як переслане. + +```ts +bot.on(":text", async (ctx) => { + // Ідентифікатор цільового чату для надсилання. + const chatId = -946659600; + // Пересилаємо поточне повідомлення без посилання на початкове повідомлення. + await ctx.copyMessage(chatId); + // Пересилаємо поточне повідомлення з посиланням на початкове повідомлення. + await ctx.forwardMessage(chatId); +}); +``` + +### Відповідь на повідомлення зі зміненим форматуванням тексту + +Ви можете легко відповідати на вхідні повідомлення за допомогою HTML, Markdown або сутностей. + +```ts +bot.on(":text", async (ctx) => { + // Відповідаємо за допомогою HTML. + await ctx.reply("жирний курсив", { parse_mode: "HTML" }); + // Відповідаємо за допомогою Telegram Markdown V2. + await ctx.reply("*жирний* _курсив_", { parse_mode: "MarkdownV2" }); + // Відповідаємо за допомогою сутностей. + await ctx.reply("жирний курсив", { + entities: [ + { offset: 0, length: 5, type: "bold" }, + { offset: 5, length: 6, type: "italic" }, + ], + }); +}); +``` + +::: tip Використовуйте плагін режиму форматування для кращого форматування + +Використовуйте офіційний плагін [`parse-mode`](./parse-mode) для кращого досвіду створення форматованих повідомлень. + +::: + +## Загальні відомості про плагін + +- Назва: `entity-parser` +- Пакет: +- Джерело: From 43fd83f0100122c248c157100c2515296ccd4e8e Mon Sep 17 00:00:00 2001 From: MasedMSD <68379695+MasedMSD@users.noreply.github.com> Date: Fri, 22 Nov 2024 23:25:28 +0500 Subject: [PATCH 21/37] fix fmt errors --- site/docs/ru/plugins/entity-parser.md | 33 +++++++++++++-------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/site/docs/ru/plugins/entity-parser.md b/site/docs/ru/plugins/entity-parser.md index 161e095b32..6956eec7c9 100644 --- a/site/docs/ru/plugins/entity-parser.md +++ b/site/docs/ru/plugins/entity-parser.md @@ -11,7 +11,7 @@ next: false Вероятно, НИКОГДА! -Хотя этот плагин может генерировать HTML, в большинстве случаев лучше передавать текст и сущности обратно в Telegram. +Хотя этот плагин может генерировать HTML, в большинстве случаев лучше передавать текст и сущности обратно в Telegram. Преобразование в HTML требуется только в редких случаях, например, если вам нужно использовать текст с форматированием Telegram **вне** самого Telegram, например, для отображения сообщений на сайте. @@ -48,10 +48,10 @@ npx jsr add @qz/telegram-entities-parser ::: -## Простое использование +## Простое использование Использовать этот плагин очень просто. -Вот краткий пример: +Вот краткий пример: ```ts import { EntitiesParser } from "@qz/telegram-entities-parser"; @@ -74,10 +74,10 @@ bot.on(":photo", (ctx) => { ### Настройка выходного HTML тега -Этот пакет преобразует сущности в семантический HTML, следуя лучшим практикам и стандартам настолько близко, насколько это возможно. +Этот пакет преобразует сущности в семантический HTML, следуя лучшим практикам и стандартам настолько близко, насколько это возможно. Однако предоставленный результат может не всегда соответствовать вашим ожиданиям. -Чтобы это исправить, вы можете использовать собственный `renderer` для настройки HTML тегов, окружающих текст, в соответствии с вашими правилами. +Чтобы это исправить, вы можете использовать собственный `renderer` для настройки HTML тегов, окружающих текст, в соответствии с вашими правилами. Вы можете изменить конкретные правила, расширив стандартный [`RendererHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts), или переопределить все правила, реализовав собственный [`Renderer`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts). Чтобы расширить существующий `renderer`, выполните следующие шаги: @@ -108,12 +108,12 @@ const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); Параметр `options` принимает объект с полями `text` и `entity`. - `text`: Конкретный текст, к которому относится текущая сущность. -- `entity`: Может быть представлен различными интерфейсами в зависимости от типа сущности, такими как `CommonEntity`, `CustomEmojiEntity`, `PreEntity`, `TextLinkEntity` или `TextMentionEntity`. +- `entity`: Может быть представлен различными интерфейсами в зависимости от типа сущности, такими как `CommonEntity`, `CustomEmojiEntity`, `PreEntity`, `TextLinkEntity` или `TextMentionEntity`. Например, сущность типа `bold` имеет интерфейс `CommonEntity`, тогда как тип `text_link` может иметь интерфейс `TextLinkEntity`, так как включает дополнительные свойства, такие как `url`. Вот полный список интерфейсов и выходных данных для каждого типа сущности: -| Entity Type | Interface | Result | +| Тип сущности | Интерфейс | Результат | | ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `blockquote` | `CommonEntity` | `
...
` | | `bold` | `CommonEntity` | ` ... ` | @@ -141,20 +141,20 @@ const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); Выводимый текст по умолчанию проходит санитизацию для обеспечения корректного HTML-рендеринга и предотвращения XSS уязвимостей. -| Ввод | Вывод | -| ----- | -------- | -| `&` | `&` | -| `<` | `<` | -| `>` | `>` | -| `"` | `"` | -| `'` | `'` | +| Ввод | Вывод | +| ---- | -------- | +| `&` | `&` | +| `<` | `<` | +| `>` | `>` | +| `"` | `"` | +| `'` | `'` | Например, результат `Bold & Italic` будет санитизирован в `Bold & Italic`. Вы можете изменить это поведение, указав `textSanitizer` при создании экземпляра [`EntitiesParser`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/mod.ts): - Если вы не укажете `textSanitizer`, по умолчанию будет использоваться [`sanitizerHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/utils/sanitizer_html.ts) для санитизации. -- Установка значения в `false` отключит санитизацию, сохраняя текст вывода в исходном виде. +- Установка значения в `false` отключит санитизацию, сохраняя текст вывода в исходном виде. Это не рекомендуется, так как может привести к некорректному рендерингу и сделать ваше приложение уязвимым для XSS атак. Если вы выбираете этот вариант, убедитесь в правильной обработке данных. - Если вы предоставите функцию, она будет использована вместо стандартного санитайзера. @@ -191,7 +191,7 @@ const entitiesParser = new EntitiesParser({ textSanitizer: myTextSanitizer }); Используйте метод [`forwardMessage`](https://core.telegram.org/bots/api#forwardmessage) для пересылки сообщений любого типа. -Вы также можете воспользоваться методом [`copyMessage`](https://core.telegram.org/bots/api#copymessage), который выполняет ту же задачу, но без ссылки на оригинальное сообщение. +Вы также можете воспользоваться методом [`copyMessage`](https://core.telegram.org/bots/api#copymessage), который выполняет ту же задачу, но без ссылки на оригинальное сообщение. Метод [`copyMessage`](https://core.telegram.org/bots/api#copymessage) работает как копирование сообщения и отправка его обратно в Telegram, что делает его похожим на обычное сообщение, а не на пересланное. ```ts @@ -226,7 +226,6 @@ bot.on(":text", async (ctx) => { ``` ::: tip Используйте parse-mode для улучшенного форматирования - Используйте официальный плагин [`parse-mode`](./parse-mode) для более удобного создания форматированных сообщений. ::: From e09e84f2acf59dd8d19f2d0efb4c38a3b593c0ff Mon Sep 17 00:00:00 2001 From: MasedMSD <68379695+MasedMSD@users.noreply.github.com> Date: Fri, 22 Nov 2024 23:27:12 +0500 Subject: [PATCH 22/37] again --- site/docs/ru/plugins/entity-parser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/ru/plugins/entity-parser.md b/site/docs/ru/plugins/entity-parser.md index 6956eec7c9..a7266d7e84 100644 --- a/site/docs/ru/plugins/entity-parser.md +++ b/site/docs/ru/plugins/entity-parser.md @@ -11,7 +11,7 @@ next: false Вероятно, НИКОГДА! -Хотя этот плагин может генерировать HTML, в большинстве случаев лучше передавать текст и сущности обратно в Telegram. +Хотя этот плагин может генерировать HTML, в большинстве случаев лучше передавать текст и сущности обратно в Telegram. Преобразование в HTML требуется только в редких случаях, например, если вам нужно использовать текст с форматированием Telegram **вне** самого Telegram, например, для отображения сообщений на сайте. From 5aaab5df1d0b625af49b22589988e5db777d5763 Mon Sep 17 00:00:00 2001 From: Andrii Zontov Date: Fri, 22 Nov 2024 22:58:46 +0100 Subject: [PATCH 23/37] Update site/docs/uk/plugins/entity-parser.md --- site/docs/uk/plugins/entity-parser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/uk/plugins/entity-parser.md b/site/docs/uk/plugins/entity-parser.md index 7e65763b38..b7fc901003 100644 --- a/site/docs/uk/plugins/entity-parser.md +++ b/site/docs/uk/plugins/entity-parser.md @@ -15,7 +15,7 @@ next: false Перетворення в HTML необхідне лише в рідкісних випадках, коли вам потрібно використовувати текст у форматі Telegram **поза межами** самого Telegram, наприклад, для відображення повідомлень Telegram на вебсайті. -Перегляньте розділ [_Випадки, коли краще не використовувати цей пакет_](#випадки-коли-краще-не-використовувати-цей-пакет), щоб визначити, чи є у вас подібна проблема, яку потрібно вирішити. +Перегляньте розділ [_Випадки, коли краще не використовувати цей пакет_](#випадки-коли-краще-не-використовувати-цеи-пакет), щоб визначити, чи є у вас подібна проблема, яку потрібно вирішити. Якщо ви не впевнені, чи підходить цей плагін для вашого випадку використання, будь ласка, не соромтеся запитувати в нашій [групі в Telegram](https://t.me/grammyjs). У більшості випадків люди приходять до висновку, що їм насправді не потрібен цей плагін для вирішення їхніх проблем! From 4c41245006594d9daacdbe38a81b7177acb8c552 Mon Sep 17 00:00:00 2001 From: qz Date: Sat, 23 Nov 2024 05:04:50 +0700 Subject: [PATCH 24/37] en: fix formatting --- site/docs/plugins/entity-parser.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/site/docs/plugins/entity-parser.md b/site/docs/plugins/entity-parser.md index 1d59a7599b..04cdc9ccfc 100644 --- a/site/docs/plugins/entity-parser.md +++ b/site/docs/plugins/entity-parser.md @@ -232,6 +232,6 @@ Use the official [`parse-mode`](./parse-mode) plugin for a better experience con ## Plugin Summary -- Name: entity-parser -- Package: -- Source: +- Name: `entity-parser` +- [Package](https://jsr.io/@qz/telegram-entities-parser) +- [Source](https://github.com/quadratz/telegram-entities-parser) From d7377d1673fa06fc847052c8921400f7de59281c Mon Sep 17 00:00:00 2001 From: qz Date: Sat, 23 Nov 2024 05:08:38 +0700 Subject: [PATCH 25/37] sync commit 5740978 to all languages --- site/docs/ru/plugins/entity-parser.md | 6 +++--- site/docs/uk/plugins/entity-parser.md | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/site/docs/ru/plugins/entity-parser.md b/site/docs/ru/plugins/entity-parser.md index a7266d7e84..376b901ca4 100644 --- a/site/docs/ru/plugins/entity-parser.md +++ b/site/docs/ru/plugins/entity-parser.md @@ -231,6 +231,6 @@ bot.on(":text", async (ctx) => { ## Краткая информация о плагине -- Название: entity-parser -- Пакет: -- Исходник: +- Название: `entity-parser` +- [Пакет](https://jsr.io/@qz/telegram-entities-parser) +- [Исходник](https://github.com/quadratz/telegram-entities-parser) diff --git a/site/docs/uk/plugins/entity-parser.md b/site/docs/uk/plugins/entity-parser.md index b7fc901003..4003551434 100644 --- a/site/docs/uk/plugins/entity-parser.md +++ b/site/docs/uk/plugins/entity-parser.md @@ -234,5 +234,5 @@ bot.on(":text", async (ctx) => { ## Загальні відомості про плагін - Назва: `entity-parser` -- Пакет: -- Джерело: +- [Пакет](https://jsr.io/@qz/telegram-entities-parser) +- [Джерело](https://github.com/quadratz/telegram-entities-parser) From 24c5decbdd8dbfd65a79b4f981717986c541a892 Mon Sep 17 00:00:00 2001 From: qz Date: Sat, 23 Nov 2024 07:03:26 +0700 Subject: [PATCH 26/37] sync changes to indonesian --- site/docs/.vitepress/configs/locales/id.ts | 4 + site/docs/id/plugins/entity-parser.md | 238 +++++++++++++++++++++ 2 files changed, 242 insertions(+) create mode 100644 site/docs/id/plugins/entity-parser.md diff --git a/site/docs/.vitepress/configs/locales/id.ts b/site/docs/.vitepress/configs/locales/id.ts index 98064e1f94..5480951d54 100644 --- a/site/docs/.vitepress/configs/locales/id.ts +++ b/site/docs/.vitepress/configs/locales/id.ts @@ -230,6 +230,10 @@ const pluginThirdparty = { text: "Autoquote", link: "/id/plugins/autoquote", }, + { + text: "Entity Parser", + link: "/id/plugins/entity-parser", + }, { text: "[Kirim PR-mu!]", link: "/id/plugins/#buat-plugin-mu-sendiri", diff --git a/site/docs/id/plugins/entity-parser.md b/site/docs/id/plugins/entity-parser.md new file mode 100644 index 0000000000..3dfc1d2fcf --- /dev/null +++ b/site/docs/id/plugins/entity-parser.md @@ -0,0 +1,238 @@ +--- +prev: false +next: false +--- + +# Entity Parser (`entity-parser`) + +Mengubah [Telegram entities](https://core.telegram.org/bots/api#messageentity) menjadi semantic HTML. + +## Kapan Plugin Ini Diperlukan? + +Kemungkinan besar kamu TIDAK AKAN PERNAH membutuhkannya sama sekali! + +Meski plugin ini mampu menghasilkan HTML, namun, pada umumnya, mengirim teks beserta entity-nya kembali ke Telegram jauh lebih baik. + +Pengonversian ke HTML hanya dibutuhkan untuk kondisi khusus ketika kamu perlu menggunakan teks pemformatan Telegram **di luar** ekosistem Telegram itu sendiri, misalnya menampilkan pesan Telegram di suatu website. + +Silahkan lihat bagian [_Contoh-Contoh Kasus yang Sebaiknya Tidak Menggunakan Plugin Ini_](#contoh-contoh-kasus-yang-sebaiknya-tidak-menggunakan-plugin-ini) untuk menemukan solusi yang lebih baik ketika kamu memiliki permasalahan yang serupa. + +Jika kamu masih ragu apakah plugin ini sesuai, jangan ragun untuk bertanya di [grup Telegram]((https://t.me/grammyjs)) kami. +Dalam kebanyakan kasus, sebagian besar orang sebenarnya tidak terlalu memerlukan plugin untuk menyelesaikan permasalahan mereka! + +## Penginstalan + +Jalankan perintah berikut di terminal. +Sesuaikan dengan runtime atau package manager yang kamu gunakan: + +::: code-group + +```sh:no-line-numbers [Deno] +deno add jsr:@qz/telegram-entities-parser +``` + +```sh:no-line-numbers [Bun] +bunx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [pnpm] +pnpm dlx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [Yarn] +yarn dlx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [npm] +npx jsr add @qz/telegram-entities-parser +``` + +::: + +## Penggunaan Sederhana + +Menggunakan plugin ini cukup simpel. +Berikut contohnya: + +```ts +import { EntitiesParser } from "@qz/telegram-entities-parser"; +import type { Message } from "@qz/telegram-entities-parser/types"; + +// Agar tidak mempengaruhi performa, buat instansiasi di luar function terkait. +const entitiesParser = new EntitiesParser(); +const parse = (message: Message) => entitiesParser.parse({ message }); + +bot.on(":text", (ctx) => { + const html = parse(ctx.msg); // Konversi teks menjadi string HTML +}); + +bot.on(":photo", (ctx) => { + const html = parse(ctx.msg); // Konversi caption menjadi string HTML +}); +``` + +## Penggunaan Tingkat Lanjut + +### Menyesuaikan Keluaran Tag HTML + +Plugin ini mengonversi entity menjadi semantic HTML sesuai dengan standar dan praktik terbaik sebisa mungkin. +Namun, keluaran yang dihasilkan mungkin tidak sesuai dengan harapan kamu. + +Untuk mengatasinya, kamu bisa menggunakan `renderer`-mu sendiri untuk menyesuaikan element HTML yang membungkus teks terkait sesuai dengan aturan yang telah diterapkan. +Kamu bisa memodifikasi aturan tertentu dengan cara meng-extend [`RendererHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts) bawaan ataupun menimpa semua aturan dengan cara mengimplementasikan [`Renderer`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts). + +Untuk meng-extend `renderer` yang sudah ada, lakukan hal berikut: + +```ts +import { EntitiesParser, RendererHtml } from "@qz/telegram-entities-parser"; +import type { + CommonEntity, + RendererOutput, +} from "@qz/telegram-entities-parser/types"; + +// Gunakan aturan yang diterapkan oleh `RendererHtml`, +// tetapi khusus untuk entity bold, gunakan aturan berikut: +class MyRenderer extends RendererHtml { + override bold( + options: { text: string; entity: CommonEntity }, + ): RendererOutput { + return { + prefix: '', + suffix: "", + }; + } +} + +const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); +``` + +Parameter `options` menerima sebuah object berupa `text` dan `entity`. + +- `text`: Porsi teks yang direferensikan oleh entity terkait. +- `entity`: Paramater ini memiliki beragam interface sesuai dengan tipe entity-nya, entah itu `CommonEntity`, `CustomEmojiEntity`, `PreEntity`, `TextLinkEntity`, ataupun `TextMentionEntity`. + Contohnya, tipe `bold` memiliki entity dengan interface `CommonEntity`, sementara tipe `text_link` interface-nya berupa `TextLinkEntity` karena mengandung property tambahan seperti `url`. + +Berikut daftar lengkap interface beserta keluaran untuk masing-masing tipe entity: + +| Tipe Entity | Interface | Keluaran | +| ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `blockquote` | `CommonEntity` | `
...
` | +| `bold` | `CommonEntity` | ` ... ` | +| `bot_command` | `CommonEntity` | ` ... ` | +| `cashtag` | `CommonEntity` | ` ... ` | +| `code` | `CommonEntity` | ` ... ` | +| `custom_emoji` | `CustomEmojiEntity` | ` ... ` | +| `email` | `CommonEntity` | ` ... ` | +| `expandable_blockquote` | `CommonEntity` | `
...
` | +| `hashtag` | `CommonEntity` | ` ... ` | +| `italic` | `CommonEntity` | ` ... ` | +| `mention` | `CommonEntity` | ` ... ` | +| `phone_number` | `CommonEntity` | ` ... ` | +| `pre` | `PreEntity` | `
 ...
` atau `
 ...
` | +| `spoiler` | `CommonEntity` | ` ... ` | +| `strikethrough` | `CommonEntity` | ` ... ` | +| `text_link` | `TextLinkEntity` | ` ... ` | +| `text_mention` | `TextMentionEntity` | ` ... ` atau ` ... ` | +| `underline` | `CommonEntity` | ` ... ` | +| `url` | `CommonEntity` | ` ... ` | + +Jika kamu ragu interface mana yang benar, silahkan lihat pengimplentasian [Renderer](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts) dan [RendererHtml](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts). + +### Menyesuaikan Pembersih Teks (Text Sanitizer) + +Secara bawaan, keluaran teks dibersihkan agar HTML bisa di-render dengan baik dan menghindari kerentanan XSS. + +| Masukan | Keluaran | +| ------- | -------- | +| `&` | `&` | +| `<` | `<` | +| `>` | `>` | +| `"` | `"` | +| `'` | `'` | + +Sebagai contoh, hasil keluaran `Tebal & Miring` akan dibersihkan menjadi `Tebal & Miring`. + +Kamu bisa mengubah perilaku tersebut dengan cara menentukan `textSanitizer` ketika menginisiasi [`EntitiesParser`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/mod.ts): + +- Jika `textSanitizer` tidak ditentukan, ia secara bawaan akan menggunakan [`sanitizerHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/utils/sanitizer_html.ts) sebagai pembersihnya. +- Jika nilai `false` diberikan, pembersihan tidak akan dilakukan, sehingga keluaran teks yang dihasilkan apa adanya. + Langkah ini tidak disarankan karena dapat menyebabkan kesalahan pe-render-an dan membuat aplikasimu rentan terhadap serangan XSS. + Pastikan penanganan dilakukan dengan baik jika kamu memilih opsi ini. +- Jika sebuah function diberikan, function tersebut akan digunakan sebagai pembersih bawaannya. + +```ts +const myTextSanitizer: TextSanitizer = (options: TextSanitizerOption): string => + // Ganti karakter-karakter yang berbahaya + options.text.replaceAll(/[&<>"']/, (match) => { + switch (match) { + case "&": + return "&"; + case "<": + return "<"; + case ">": + return ">"; + case '"': + return """; + case "'": + return "'"; + default: + return match; + } + }); + +// Terapkan pembersihnya (sanitizer). +const entitiesParser = new EntitiesParser({ textSanitizer: myTextSanitizer }); +``` + +## Contoh-Contoh Kasus yang Sebaiknya Tidak Menggunakan Plugin Ini + +Jika menghadapi permasalahan serupa dengan berikut, kamu kemungkinan besar bisa menyelesaikannya tanpa menggunakan plugin ini. + +### Menyalin dan Meneruskan Pesan yang Sama + +Gunakan [`forwardMessage`](https://core.telegram.org/bots/api#forwardmessage) untuk meneruskan pesan apapun. + +Kamu juga bisa menggunakan API [`copyMessage`](https://core.telegram.org/bots/api#copymessage) untuk melakukan aksi yang serupa tanpa menyertakan link ke pesan aslinya. +[`copyMessage`](https://core.telegram.org/bots/api#copymessage) memiliki perilaku layaknya menyalin lalu mengirim ulang pesan tersebut ke Telegram, sehingga wujudnya berupa pesan biasa alih-alih pesan terusan. + +```ts +bot.on(":text", async (ctx) => { + // Id chat tujuan. + const chatId = -946659600; + // Teruskan pesan berikut tanpa menyertakan link ke pesan aslinya. + await ctx.copyMessage(chatId); + // Teruskan pesan berikut dengan menyertakan link ke pesan aslinya. + await ctx.forwardMessage(chatId); +}); +``` + +### Membalas Pesan Menggunakan Format Teks yang Telah Dimodifikasi + +Kamu juga bisa dengan mudah membalas pesan yang datang menggunakan HTML, Markdown, atau entity. + +```ts +bot.on(":text", async (ctx) => { + // Balas dengan HTML + await ctx.reply("tebal miring", { parse_mode: "HTML" }); + // Balas dengan Telegram Markdown V2 + await ctx.reply("*tebal* _miring_", { parse_mode: "MarkdownV2" }); + // Balas dengan entity + await ctx.reply("tebal miring", { + entities: [ + { offset: 0, length: 5, type: "bold" }, + { offset: 6, length: 6, type: "italic" }, + ], + }); +}); +``` + +::: tip Gunakan parse-mode untuk Pengalaman Pemformatan yang Lebih Baik + +Gunakan plugin resmi [`parse-mode`](./parse-mode) untuk memformat pesan dengan cara yang lebih elegan. +::: + +## Ringkasan Plugin + +- Nama: `entity-parser` +- [Package](https://jsr.io/@qz/telegram-entities-parser) +- [Sumber](https://github.com/quadratz/telegram-entities-parser) From fd584ec6757c7b2e6b0344ea5dfdc0adcf9d1970 Mon Sep 17 00:00:00 2001 From: qz Date: Sat, 23 Nov 2024 07:12:53 +0700 Subject: [PATCH 27/37] id: fix fmt --- site/docs/id/plugins/entity-parser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/id/plugins/entity-parser.md b/site/docs/id/plugins/entity-parser.md index 3dfc1d2fcf..a1df652caf 100644 --- a/site/docs/id/plugins/entity-parser.md +++ b/site/docs/id/plugins/entity-parser.md @@ -17,7 +17,7 @@ Pengonversian ke HTML hanya dibutuhkan untuk kondisi khusus ketika kamu perlu me Silahkan lihat bagian [_Contoh-Contoh Kasus yang Sebaiknya Tidak Menggunakan Plugin Ini_](#contoh-contoh-kasus-yang-sebaiknya-tidak-menggunakan-plugin-ini) untuk menemukan solusi yang lebih baik ketika kamu memiliki permasalahan yang serupa. -Jika kamu masih ragu apakah plugin ini sesuai, jangan ragun untuk bertanya di [grup Telegram]((https://t.me/grammyjs)) kami. +Jika kamu masih ragu apakah plugin ini sesuai, jangan ragun untuk bertanya di [grup Telegram](https://t.me/grammyjs) kami. Dalam kebanyakan kasus, sebagian besar orang sebenarnya tidak terlalu memerlukan plugin untuk menyelesaikan permasalahan mereka! ## Penginstalan From b1faf0e84a8b256fa6641f1e3058299201fb2cb4 Mon Sep 17 00:00:00 2001 From: MasedMSD <68379695+MasedMSD@users.noreply.github.com> Date: Sat, 23 Nov 2024 11:13:40 +0500 Subject: [PATCH 28/37] little fix --- site/docs/ru/plugins/entity-parser.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/site/docs/ru/plugins/entity-parser.md b/site/docs/ru/plugins/entity-parser.md index 376b901ca4..47f3901dbb 100644 --- a/site/docs/ru/plugins/entity-parser.md +++ b/site/docs/ru/plugins/entity-parser.md @@ -127,11 +127,11 @@ const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); | `italic` | `CommonEntity` | ` ... ` | | `mention` | `CommonEntity` | ` ... ` | | `phone_number` | `CommonEntity` | ` ... ` | -| `pre` | `PreEntity` | `
 ...
` or `
 ...
` | +| `pre` | `PreEntity` | `
 ...
` или `
 ...
` | | `spoiler` | `CommonEntity` | ` ... ` | | `strikethrough` | `CommonEntity` | ` ... ` | | `text_link` | `TextLinkEntity` | ` ... ` | -| `text_mention` | `TextMentionEntity` | ` ... ` or ` ... ` | +| `text_mention` | `TextMentionEntity` | ` ... ` или ` ... ` | | `underline` | `CommonEntity` | ` ... ` | | `url` | `CommonEntity` | ` ... ` | @@ -212,14 +212,14 @@ bot.on(":text", async (ctx) => { ```ts bot.on(":text", async (ctx) => { // Ответ с использованием HTML - await ctx.reply("bold italic", { parse_mode: "HTML" }); + await ctx.reply("жирный курсив", { parse_mode: "HTML" }); // Ответ с использованием Telegram Markdown V2 - await ctx.reply("*bold* _italic_", { parse_mode: "MarkdownV2" }); + await ctx.reply("*жирный* _курсив_", { parse_mode: "MarkdownV2" }); // Ответ с использованием сущностей - await ctx.reply("bold italic", { + await ctx.reply("жирный курсив", { entities: [ - { offset: 0, length: 5, type: "bold" }, - { offset: 5, length: 6, type: "italic" }, + { offset: 0, length: 6, type: "bold" }, + { offset: 7, length: 6, type: "italic" }, ], }); }); From eb6bc11f40ef1a4db674a0654c2fad0d16c1ce5c Mon Sep 17 00:00:00 2001 From: MasedMSD <68379695+MasedMSD@users.noreply.github.com> Date: Sat, 23 Nov 2024 11:15:55 +0500 Subject: [PATCH 29/37] fix fmt --- site/docs/ru/plugins/entity-parser.md | 38 +++++++++++++-------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/site/docs/ru/plugins/entity-parser.md b/site/docs/ru/plugins/entity-parser.md index 47f3901dbb..0801f05f8f 100644 --- a/site/docs/ru/plugins/entity-parser.md +++ b/site/docs/ru/plugins/entity-parser.md @@ -113,27 +113,27 @@ const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); Вот полный список интерфейсов и выходных данных для каждого типа сущности: -| Тип сущности | Интерфейс | Результат | -| ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `blockquote` | `CommonEntity` | `
...
` | -| `bold` | `CommonEntity` | ` ... ` | -| `bot_command` | `CommonEntity` | ` ... ` | -| `cashtag` | `CommonEntity` | ` ... ` | -| `code` | `CommonEntity` | ` ... ` | -| `custom_emoji` | `CustomEmojiEntity` | ` ... ` | -| `email` | `CommonEntity` | ` ... ` | -| `expandable_blockquote` | `CommonEntity` | `
...
` | -| `hashtag` | `CommonEntity` | ` ... ` | -| `italic` | `CommonEntity` | ` ... ` | -| `mention` | `CommonEntity` | ` ... ` | -| `phone_number` | `CommonEntity` | ` ... ` | +| Тип сущности | Интерфейс | Результат | +| ----------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `blockquote` | `CommonEntity` | `
...
` | +| `bold` | `CommonEntity` | ` ... ` | +| `bot_command` | `CommonEntity` | ` ... ` | +| `cashtag` | `CommonEntity` | ` ... ` | +| `code` | `CommonEntity` | ` ... ` | +| `custom_emoji` | `CustomEmojiEntity` | ` ... ` | +| `email` | `CommonEntity` | ` ... ` | +| `expandable_blockquote` | `CommonEntity` | `
...
` | +| `hashtag` | `CommonEntity` | ` ... ` | +| `italic` | `CommonEntity` | ` ... ` | +| `mention` | `CommonEntity` | ` ... ` | +| `phone_number` | `CommonEntity` | ` ... ` | | `pre` | `PreEntity` | `
 ...
` или `
 ...
` | -| `spoiler` | `CommonEntity` | ` ... ` | -| `strikethrough` | `CommonEntity` | ` ... ` | -| `text_link` | `TextLinkEntity` | ` ... ` | +| `spoiler` | `CommonEntity` | ` ... ` | +| `strikethrough` | `CommonEntity` | ` ... ` | +| `text_link` | `TextLinkEntity` | ` ... ` | | `text_mention` | `TextMentionEntity` | ` ... ` или ` ... ` | -| `underline` | `CommonEntity` | ` ... ` | -| `url` | `CommonEntity` | ` ... ` | +| `underline` | `CommonEntity` | ` ... ` | +| `url` | `CommonEntity` | ` ... ` | Если вы не уверены, какой интерфейс использовать, обратитесь к реализации [Renderer](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts) или [RendererHtml](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts). From b0b1300f828b590843e4c7dc07715c7c5cf1adb5 Mon Sep 17 00:00:00 2001 From: MasedMSD <68379695+MasedMSD@users.noreply.github.com> Date: Tue, 3 Dec 2024 18:01:22 +0500 Subject: [PATCH 30/37] ru: changed order --- site/docs/.vitepress/configs/locales/ru.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/site/docs/.vitepress/configs/locales/ru.ts b/site/docs/.vitepress/configs/locales/ru.ts index 9aec7343db..d03eed8e58 100644 --- a/site/docs/.vitepress/configs/locales/ru.ts +++ b/site/docs/.vitepress/configs/locales/ru.ts @@ -230,14 +230,14 @@ const pluginThirdparty = { text: "Полезный Middleware", link: "/ru/plugins/middlewares", }, - { - text: "Парсер сущностей", - link: "/ru/plugins/entity-parser", - }, { text: "Автоцитата", link: "/ru/plugins/autoquote", }, + { + text: "Парсер сущностей", + link: "/ru/plugins/entity-parser", + }, { text: "[Создайте свой PR!]", link: "/ru/plugins/#create-your-own-plugins", From ad8ae5c63a14bbb5e2e7561cd9d5d724d61b376d Mon Sep 17 00:00:00 2001 From: Habemuscode <34692207+habemuscode@users.noreply.github.com> Date: Fri, 6 Dec 2024 23:28:23 +0100 Subject: [PATCH 31/37] Add spanish --- site/docs/.vitepress/configs/locales/es.ts | 4 + site/docs/es/plugins/entity-parser.md | 273 +++++++++++++++++++++ 2 files changed, 277 insertions(+) create mode 100644 site/docs/es/plugins/entity-parser.md diff --git a/site/docs/.vitepress/configs/locales/es.ts b/site/docs/.vitepress/configs/locales/es.ts index 202bc3abc9..54a74d7653 100644 --- a/site/docs/.vitepress/configs/locales/es.ts +++ b/site/docs/.vitepress/configs/locales/es.ts @@ -234,6 +234,10 @@ const pluginThirdparty = { text: "Citar automáticamente", link: "/es/plugins/autoquote", }, + { + text: "Analizador de entidades", + link: "/es/plugins/entity-parser", + }, { text: "[¡Envíe su PR!]", link: "/es/plugins/#crear-tus-propios-plugins", diff --git a/site/docs/es/plugins/entity-parser.md b/site/docs/es/plugins/entity-parser.md new file mode 100644 index 0000000000..5a8c8bc4e5 --- /dev/null +++ b/site/docs/es/plugins/entity-parser.md @@ -0,0 +1,273 @@ +--- +prev: false +next: false +--- + +# Analizador de entidades (`entity-parser`) + +Convierte +[entidades de Telegram](https://core.telegram.org/bots/api#messageentity) 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_](#casos-en-los-que-es-mejor-no-utilizar-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](https://t.me/grammyjs). 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: + +::: code-group + +```sh:no-line-numbers [Deno] +deno add jsr:@qz/telegram-entities-parser +``` + +```sh:no-line-numbers [Bun] +bunx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [pnpm] +pnpm dlx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [Yarn] +yarn dlx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [npm] +npx jsr add @qz/telegram-entities-parser +``` + +::: + +## Uso sencillo + +El uso de este plugin es muy sencillo. He aquí un ejemplo rápido: + +```ts +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 +}); +``` + +## 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 +[`RendererHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts) +por defecto o anular todas las reglas implementando el +[`Renderer`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts). + +Para extender el `renderer` existente, haz lo siguiente: + +```ts +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: '', + suffix: "", + }; + } +} + +const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); +``` + +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, como `CommonEntity`, `CustomEmojiEntity`, `PreEntity`, + `TextLinkEntity`, o `TextMentionEntity`. Por ejemplo, el tipo `bold` tiene una + entidad con la interfaz `CommonEntity`, mientras que el tipo `text_link` puede + tener una entidad con la interfaz `TextLinkEntity`, ya que incluye propiedades + adicionales como `url`. + +Aquí está la lista completa de interfaces y la salida para cada tipo de entidad: + +| Entity Type | Interface | Result | +| ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `blockquote` | `CommonEntity` | `
...
` | +| `bold` | `CommonEntity` | ` ... ` | +| `bot_command` | `CommonEntity` | ` ... ` | +| `cashtag` | `CommonEntity` | ` ... ` | +| `code` | `CommonEntity` | ` ... ` | +| `custom_emoji` | `CustomEmojiEntity` | ` ... ` | +| `email` | `CommonEntity` | ` ... ` | +| `expandable_blockquote` | `CommonEntity` | `
...
` | +| `hashtag` | `CommonEntity` | ` ... ` | +| `italic` | `CommonEntity` | ` ... ` | +| `mention` | `CommonEntity` | ` ... ` | +| `phone_number` | `CommonEntity` | ` ... ` | +| `pre` | `PreEntity` | `
 ...
` o `
 ...
` | +| `spoiler` | `CommonEntity` | ` ... ` | +| `strikethrough` | `CommonEntity` | ` ... ` | +| `text_link` | `TextLinkEntity` | ` ... ` | +| `text_mention` | `TextMentionEntity` | ` ... ` o ` ... ` | +| `underline` | `CommonEntity` | ` ... ` | +| `url` | `CommonEntity` | ` ... ` | + +Si no está seguro de cuál es la interfaz correcta, consulte cómo se implementa +[Renderer](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts) +o +[RendererHtml](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts). + +### 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 `Negrita & Cursiva` se saneará a +`Negrita & Cursiva`. + +Puede anular este comportamiento especificando un `textSanitizer` al crear una +instancia de +[`EntitiesParser`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/mod.ts): + +- Si no especifica `textSanitizer`, se utilizará de manera predeterminada + [`sanitizerHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/utils/sanitizer_html.ts) + como sanitizador. +- 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. + +```ts +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 }); +``` + +## 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 [`forwardMessage`](https://core.telegram.org/bots/api#forwardmessage) +para reenviar mensajes de cualquier tipo. + +También puedes utilizar la API +[`copyMessage`](https://core.telegram.org/bots/api#copymessage), que realiza la +misma acción pero no incluye un enlace al mensaje original. +[`copyMessage`](https://core.telegram.org/bots/api#copymessage) se comporta como +copiar el mensaje y enviarlo de vuelta a Telegram, haciendo que aparezca como un +mensaje normal en lugar de uno reenviado. + +```ts +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); +}); +``` + +### Responder a mensajes con formato de texto modificado + +Puede responder fácilmente a los mensajes entrantes utilizando HTML, Markdown o +entidades. + +```ts +bot.on(":text", async (ctx) => { + // Responder con HTML + await ctx.reply("bold italic", { 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" }, + ], + }); +}); +``` + +::: tip Use parse-mode para una mejor experiencia de formateo + +Utiliza el plugin oficial [`parse-mode`](./parse-mode) para una mejor +experiencia en la construcción de mensajes formateados. ::: + +## Resumen del plugin + +- Nombre: `entity-parser` +- [Fuente](https://jsr.io/@qz/telegram-entities-parser) +- [Referencia](https://github.com/quadratz/telegram-entities-parser) From 56a846ff34a80286b1c439431a73a3bd965298f8 Mon Sep 17 00:00:00 2001 From: Habemuscode <34692207+habemuscode@users.noreply.github.com> Date: Fri, 6 Dec 2024 23:30:37 +0100 Subject: [PATCH 32/37] Apply formatter --- site/docs/es/plugins/entity-parser.md | 38 +++++++++++++-------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/site/docs/es/plugins/entity-parser.md b/site/docs/es/plugins/entity-parser.md index 5a8c8bc4e5..3d0bc14cc1 100644 --- a/site/docs/es/plugins/entity-parser.md +++ b/site/docs/es/plugins/entity-parser.md @@ -131,27 +131,27 @@ El parámetro `options` acepta un objeto con `text` y `entity`. Aquí está la lista completa de interfaces y la salida para cada tipo de entidad: -| Entity Type | Interface | Result | -| ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `blockquote` | `CommonEntity` | `
...
` | -| `bold` | `CommonEntity` | ` ... ` | -| `bot_command` | `CommonEntity` | ` ... ` | -| `cashtag` | `CommonEntity` | ` ... ` | -| `code` | `CommonEntity` | ` ... ` | -| `custom_emoji` | `CustomEmojiEntity` | ` ... ` | -| `email` | `CommonEntity` | ` ... ` | -| `expandable_blockquote` | `CommonEntity` | `
...
` | -| `hashtag` | `CommonEntity` | ` ... ` | -| `italic` | `CommonEntity` | ` ... ` | -| `mention` | `CommonEntity` | ` ... ` | -| `phone_number` | `CommonEntity` | ` ... ` | +| Entity Type | Interface | Result | +| ----------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `blockquote` | `CommonEntity` | `
...
` | +| `bold` | `CommonEntity` | ` ... ` | +| `bot_command` | `CommonEntity` | ` ... ` | +| `cashtag` | `CommonEntity` | ` ... ` | +| `code` | `CommonEntity` | ` ... ` | +| `custom_emoji` | `CustomEmojiEntity` | ` ... ` | +| `email` | `CommonEntity` | ` ... ` | +| `expandable_blockquote` | `CommonEntity` | `
...
` | +| `hashtag` | `CommonEntity` | ` ... ` | +| `italic` | `CommonEntity` | ` ... ` | +| `mention` | `CommonEntity` | ` ... ` | +| `phone_number` | `CommonEntity` | ` ... ` | | `pre` | `PreEntity` | `
 ...
` o `
 ...
` | -| `spoiler` | `CommonEntity` | ` ... ` | -| `strikethrough` | `CommonEntity` | ` ... ` | -| `text_link` | `TextLinkEntity` | ` ... ` | +| `spoiler` | `CommonEntity` | ` ... ` | +| `strikethrough` | `CommonEntity` | ` ... ` | +| `text_link` | `TextLinkEntity` | ` ... ` | | `text_mention` | `TextMentionEntity` | ` ... ` o ` ... ` | -| `underline` | `CommonEntity` | ` ... ` | -| `url` | `CommonEntity` | ` ... ` | +| `underline` | `CommonEntity` | ` ... ` | +| `url` | `CommonEntity` | ` ... ` | Si no está seguro de cuál es la interfaz correcta, consulte cómo se implementa [Renderer](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts) From 3e4d055d1558a5ac3c8e0bbb25bd7a00f97b5648 Mon Sep 17 00:00:00 2001 From: Nazar Antoniuk Date: Mon, 16 Dec 2024 16:32:00 +0200 Subject: [PATCH 33/37] Apply suggestions from code review Co-authored-by: Andrii Zontov Co-authored-by: Qz --- site/docs/uk/plugins/entity-parser.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/site/docs/uk/plugins/entity-parser.md b/site/docs/uk/plugins/entity-parser.md index 4003551434..be327a85e0 100644 --- a/site/docs/uk/plugins/entity-parser.md +++ b/site/docs/uk/plugins/entity-parser.md @@ -137,7 +137,7 @@ const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); Якщо ви не впевнені, який інтерфейс правильний, зверніться до того, як реалізовано [Renderer](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts) або [RendererHtml](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts). -### Налаштування санітайзера тексту +### Редагування та очищення тексту Вихідний текст за замовчуванням очищується, щоб забезпечити правильне відображення HTML і запобігти XSS-вразливостям. @@ -149,15 +149,15 @@ const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); | `"` | `"` | | `'` | `'` | -Наприклад, результат `Жирний & Курсив` буде очищено до `Жирний & Курсив`. +Наприклад, результат `Жирний & Курсив` буде перетворений в `Жирний & Курсив`. Ви можете змінити цю поведінку, вказавши `textSanitizer` при створенні екземпляра [`EntitiesParser`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/mod.ts): -- Якщо ви не вкажете `textSanitizer`, буде використано [`sanitizerHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/utils/sanitizer_html.ts) як типовий санітайзер. +- Якщо ви не вкажете `textSanitizer`, буде використано [`sanitizerHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/utils/sanitizer_html.ts) як типовий очищувач. - Якщо вказати значення `false`, очищення буде пропущено, а виведений текст буде збережено як оригінал. Це не рекомендується, оскільки може призвести до некоректного рендерингу і зробити вашу програму вразливою до XSS-атак. Якщо ви вибрали цю опцію, забезпечте належну обробку результату. -- Якщо ви надасте функцію, вона буде використовуватися замість типового санітайзера. +- Якщо ви надасте функцію, вона буде використовуватися замість типового очищувача. ```ts const myTextSanitizer: TextSanitizer = (options: TextSanitizerOption): string => @@ -179,7 +179,7 @@ const myTextSanitizer: TextSanitizer = (options: TextSanitizerOption): string => } }); -// Застосовуємо санітайзер. +// Застосовуємо очищувач. const entitiesParser = new EntitiesParser({ textSanitizer: myTextSanitizer }); ``` @@ -218,8 +218,8 @@ bot.on(":text", async (ctx) => { // Відповідаємо за допомогою сутностей. await ctx.reply("жирний курсив", { entities: [ - { offset: 0, length: 5, type: "bold" }, - { offset: 5, length: 6, type: "italic" }, + { offset: 0, length: 6, type: "bold" }, + { offset: 7, length: 6, type: "italic" }, ], }); }); From 465daa20eb9acee2063478525fcb28a15be86092 Mon Sep 17 00:00:00 2001 From: Andrii Zontov Date: Wed, 18 Dec 2024 00:50:01 +0100 Subject: [PATCH 34/37] Update site/docs/uk/plugins/entity-parser.md Co-authored-by: Nazar Antoniuk --- site/docs/uk/plugins/entity-parser.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/docs/uk/plugins/entity-parser.md b/site/docs/uk/plugins/entity-parser.md index be327a85e0..402294cd52 100644 --- a/site/docs/uk/plugins/entity-parser.md +++ b/site/docs/uk/plugins/entity-parser.md @@ -225,7 +225,7 @@ bot.on(":text", async (ctx) => { }); ``` -::: tip Використовуйте плагін режиму форматування для кращого форматування +::: tip Просунуте форматування Використовуйте офіційний плагін [`parse-mode`](./parse-mode) для кращого досвіду створення форматованих повідомлень. From b80ac3539f336f0ece3fcafcffc62bedc02d070b Mon Sep 17 00:00:00 2001 From: agoudbg <55237525+agoudbg@users.noreply.github.com> Date: Wed, 15 Jan 2025 21:39:09 +0800 Subject: [PATCH 35/37] Grammy entity zh (#1178) --- site/docs/.vitepress/configs/locales/zh.ts | 4 + site/docs/zh/plugins/entity-parser.md | 237 +++++++++++++++++++++ 2 files changed, 241 insertions(+) create mode 100644 site/docs/zh/plugins/entity-parser.md diff --git a/site/docs/.vitepress/configs/locales/zh.ts b/site/docs/.vitepress/configs/locales/zh.ts index f24c5775bf..edb1c0d691 100644 --- a/site/docs/.vitepress/configs/locales/zh.ts +++ b/site/docs/.vitepress/configs/locales/zh.ts @@ -234,6 +234,10 @@ const pluginThirdparty = { text: "自动引用", link: "/zh/plugins/autoquote", }, + { + text: "实体解析器 (Entity Parser)", + link: "/zh/plugins/entity-parser", + }, { text: "[提交你的 PR!]", link: "/zh/plugins/#创建你自己的插件", diff --git a/site/docs/zh/plugins/entity-parser.md b/site/docs/zh/plugins/entity-parser.md new file mode 100644 index 0000000000..2e86ca583e --- /dev/null +++ b/site/docs/zh/plugins/entity-parser.md @@ -0,0 +1,237 @@ +--- +prev: false +next: false +--- + +# 实体解析器 (`entity-parser`) + +将 [Telegram 实体 (entities)](https://core.telegram.org/bots/api#messageentity) 转换为语义 HTML。 + +## 我应该在什么时候用这个插件？ + +最好**永远别用**！ + +虽然这个插件可以生成 HTML，但一般而言最好将文本和实体发送回 Telegram。 + +仅在极少数情况下才需要将实体转换为 HTML，即您需要在 Telegram **之外**使用带 Telegram 格式的文本，例如在网站上显示 Telegram 消息。 + +请参阅 [_最好不要使用这个包的情况_](#最好不要使用这个包的情况) 部分，确认您是不是有类似的问题要解决。 + +如果您不确定在您的情况下使用此插件是否合适，请随时在我们的 [Telegram 群组](https://t.me/grammyjs) 中提问。 +在大多数情况下，人们会发现他们实际上并不需要这个插件来解决他们的问题！ + +## 安装 + +根据您的运行时或包管理器在终端中运行以下命令： + +::: code-group + +```sh:no-line-numbers [Deno] +deno add jsr:@qz/telegram-entities-parser +``` + +```sh:no-line-numbers [Bun] +bunx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [pnpm] +pnpm dlx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [Yarn] +yarn dlx jsr add @qz/telegram-entities-parser +``` + +```sh:no-line-numbers [npm] +npx jsr add @qz/telegram-entities-parser +``` + +::: + +## 基本用法 + +使用此插件非常简单。 +这是一个简单的示例： + +```ts +import { EntitiesParser } from "@qz/telegram-entities-parser"; +import type { Message } from "@qz/telegram-entities-parser/types"; + +// 为了获得更好的性能，请在函数外部创建实例。 +const entitiesParser = new EntitiesParser(); +const parse = (message: Message) => entitiesParser.parse({ message }); + +bot.on(":text", (ctx) => { + const html = parse(ctx.msg); // 将文本转换为 HTML 字符串 +}); + +bot.on(":photo", (ctx) => { + const html = parse(ctx.msg); // 将标题转换为 HTML 字符串 +}); +``` + +## 高级用法 + +### 自定义输出的 HTML 标签 + +这个包将实体转换为语义 HTML，尽可能地遵循最佳实践和标准。 +但是，提供的输出可能并不总是您所期望的。 + +为了解决这个问题，您可以使用自己的 `renderer` 根据规则自定义环绕文本的 HTML 元素。 +您可以通过扩展默认的 [`RendererHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts) 来修改特定规则，或者通过实现 [`Renderer`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts) 来覆盖所有规则。 + +要扩展现有的 `renderer`，请执行以下操作： + +```ts +import { EntitiesParser, RendererHtml } from "@qz/telegram-entities-parser"; +import type { + CommonEntity, + RendererOutput, +} from "@qz/telegram-entities-parser/types"; + +// 更改粗体类型实体的规则， +// 但保留 `RendererHtml` 定义的其余类型。 +class MyRenderer extends RendererHtml { + override bold( + options: { text: string; entity: CommonEntity }, + ): RendererOutput { + return { + prefix: '', + suffix: "", + }; + } +} + +const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); +``` + +`options` 参数接受带有 `text` 和 `entity` 参数的对象。 + +- `text`：当前实体引用的特定文本。 +- `entity`：根据实体类型以不同接口表示，例如 `CommonEntity`、`CustomEmojiEntity`、`PreEntity`、`TextLinkEntity` 或 `TextMentionEntity`。 + 例如，`bold` 实体符合 `CommonEntity` 接口，而 `text_link` 实体则符合 `TextLinkEntity` 接口，因为它包含其他属性，例如 `url`。 + +以下是接口的完整列表以及每种实体类型的输出： + +| 实体类型 | 接口 | 结果 | +| ----------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `blockquote` | `CommonEntity` | `
...
` | +| `bold` | `CommonEntity` | ` ... ` | +| `bot_command` | `CommonEntity` | ` ... ` | +| `cashtag` | `CommonEntity` | ` ... ` | +| `code` | `CommonEntity` | ` ... ` | +| `custom_emoji` | `CustomEmojiEntity` | ` ... ` | +| `email` | `CommonEntity` | ` ... ` | +| `expandable_blockquote` | `CommonEntity` | `
...
` | +| `hashtag` | `CommonEntity` | ` ... ` | +| `italic` | `CommonEntity` | ` ... ` | +| `mention` | `CommonEntity` | ` ... ` | +| `phone_number` | `CommonEntity` | ` ... ` | +| `pre` | `PreEntity` | `
 ...
` or `
 ...
` | +| `spoiler` | `CommonEntity` | ` ... ` | +| `strikethrough` | `CommonEntity` | ` ... ` | +| `text_link` | `TextLinkEntity` | ` ... ` | +| `text_mention` | `TextMentionEntity` | ` ... ` or ` ... ` | +| `underline` | `CommonEntity` | ` ... ` | +| `url` | `CommonEntity` | ` ... ` | + +如果你不确定哪个接口是正确的，请参考 [Renderer](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts) 或 [RendererHtml](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts) 的实现方式。 + +### 自定义文本清理器 + +默认情况下，输出文本经过清理，以确保正确呈现 HTML 并防止 XSS 漏洞。 + +| 输入 | 输出 | +| ---- | -------- | +| `&` | `&` | +| `<` | `<` | +| `>` | `>` | +| `"` | `"` | +| `'` | `'` | + +例如，结果 `粗体 & 斜体` 将被清理为 `粗体 & 斜体`。 + +您可以在实例化 [`EntitiesParser`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/mod.ts) 时指定 `textSanitizer` 来覆盖此行为： + +- 如果您未指定 `textSanitizer`，它将默认使用 [`sanitizerHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/utils/sanitizer_html.ts) 作为清理程序。 +- 将值设置为 `false` 将跳过清理，保持输出文本为原始文本。 + 不建议这样做，因为它可能会导致渲染不正确，并使您的应用程序容易受到 XSS 攻击。 + 如果选择此选项，请确保您正确处理输出文本。 +- 如果您提供一个函数，它将被用来代替默认清理程序。 + +```ts +const myTextSanitizer: TextSanitizer = (options: TextSanitizerOption): string => + // 替换危险的字符 + options.text.replaceAll(/[&<>"']/, (match) => { + switch (match) { + case "&": + return "&"; + case "<": + return "<"; + case ">": + return ">"; + case '"': + return """; + case "'": + return "'"; + default: + return match; + } + }); + +// 实施清理。 +const entitiesParser = new EntitiesParser({ textSanitizer: myTextSanitizer }); +``` + +## 最好不要使用这个包的情况 + +如果您遇到的问题和下面列出的问题类似，您可能不需要使用这个包就能解决问题。 + +### 复制和转发同一条消息 + +使用 [`forwardMessage`](https://core.telegram.org/bots/api#forwardmessage) 即可转发任何类型的消息。 + +您还可以使用 [`copyMessage`](https://core.telegram.org/bots/api#copymessage) API。该 API 会执行同样的操作，但不包含指向原始消息的链接。 +[`copyMessage`](https://core.telegram.org/bots/api#copymessage) 的行为类似于复制消息并将其发送回 Telegram，使其显示为常规消息而不是转发的消息。 + +```ts +bot.on(":text", async (ctx) => { + // 要发送消息的对话的 ID。 + const chatId = -946659600; + // 转发当前消息，不包含原始消息的链接。 + await ctx.copyMessage(chatId); + // 转发当前消息，包含原始消息的链接。 + await ctx.forwardMessage(chatId); +}); +``` + +### 回复修改了文本格式的消息 + +你可以轻松使用 HTML、Markdown 或实体 (`entities`) 来回复消息。 + +```ts +bot.on(":text", async (ctx) => { + // 使用 HTML 回复 + await ctx.reply("bold italic", { parse_mode: "HTML" }); + // 使用 Telegram Markdown V2 回复 + await ctx.reply("*bold* _italic_", { parse_mode: "MarkdownV2" }); + // 使用实体回复 + await ctx.reply("bold italic", { + entities: [ + { offset: 0, length: 5, type: "bold" }, + { offset: 5, length: 6, type: "italic" }, + ], + }); +}); +``` + +::: tip 使用 parse-mode 获得更好的格式化体验 + +使用官方 [`parse-mode` (解析模式)](./parse-mode) 插件获得更好的格式化消息构建体验。 +::: + +## 插件概述 + +- 名称: `entity-parser` +- [包](https://jsr.io/@qz/telegram-entities-parser) +- [源码](https://github.com/quadratz/telegram-entities-parser) From f9982d7bef36fe4962b5012be612ec74b3e552e4 Mon Sep 17 00:00:00 2001 From: agoudbg <55237525+agoudbg@users.noreply.github.com> Date: Thu, 16 Jan 2025 14:25:57 +0800 Subject: [PATCH 36/37] [Zh] fix "or" translation (#1179) --- site/docs/zh/plugins/entity-parser.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/site/docs/zh/plugins/entity-parser.md b/site/docs/zh/plugins/entity-parser.md index 2e86ca583e..d35aa75004 100644 --- a/site/docs/zh/plugins/entity-parser.md +++ b/site/docs/zh/plugins/entity-parser.md @@ -127,11 +127,11 @@ const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); | `italic` | `CommonEntity` | ` ... ` | | `mention` | `CommonEntity` | ` ... ` | | `phone_number` | `CommonEntity` | ` ... ` | -| `pre` | `PreEntity` | `
 ...
` or `
 ...
` | +| `pre` | `PreEntity` | `
 ...
` 或 `
 ...
` | | `spoiler` | `CommonEntity` | ` ... ` | | `strikethrough` | `CommonEntity` | ` ... ` | | `text_link` | `TextLinkEntity` | ` ... ` | -| `text_mention` | `TextMentionEntity` | ` ... ` or ` ... ` | +| `text_mention` | `TextMentionEntity` | ` ... ` 或 ` ... ` | | `underline` | `CommonEntity` | ` ... ` | | `url` | `CommonEntity` | ` ... ` | From 4c556b75530ada9991f7124ad29fbb4407b9fbe5 Mon Sep 17 00:00:00 2001 From: Acer <> Date: Thu, 16 Jan 2025 07:46:55 +0000 Subject: [PATCH 37/37] duzen statt siezen --- site/docs/zh/plugins/entity-parser.md | 30 +++++++++++++-------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/site/docs/zh/plugins/entity-parser.md b/site/docs/zh/plugins/entity-parser.md index d35aa75004..09fe9a00ed 100644 --- a/site/docs/zh/plugins/entity-parser.md +++ b/site/docs/zh/plugins/entity-parser.md @@ -13,16 +13,16 @@ next: false 虽然这个插件可以生成 HTML，但一般而言最好将文本和实体发送回 Telegram。 -仅在极少数情况下才需要将实体转换为 HTML，即您需要在 Telegram **之外**使用带 Telegram 格式的文本，例如在网站上显示 Telegram 消息。 +仅在极少数情况下才需要将实体转换为 HTML，即你需要在 Telegram **之外**使用带 Telegram 格式的文本，例如在网站上显示 Telegram 消息。 -请参阅 [_最好不要使用这个包的情况_](#最好不要使用这个包的情况) 部分，确认您是不是有类似的问题要解决。 +请参阅 [_最好不要使用这个包的情况_](#最好不要使用这个包的情况) 部分，确认你是不是有类似的问题要解决。 -如果您不确定在您的情况下使用此插件是否合适，请随时在我们的 [Telegram 群组](https://t.me/grammyjs) 中提问。 +如果你不确定在你的情况下使用此插件是否合适，请随时在我们的 [Telegram 群组](https://t.me/grammyjs) 中提问。 在大多数情况下，人们会发现他们实际上并不需要这个插件来解决他们的问题！ ## 安装 -根据您的运行时或包管理器在终端中运行以下命令： +根据你的运行时或包管理器在终端中运行以下命令： ::: code-group @@ -75,10 +75,10 @@ bot.on(":photo", (ctx) => { ### 自定义输出的 HTML 标签 这个包将实体转换为语义 HTML，尽可能地遵循最佳实践和标准。 -但是，提供的输出可能并不总是您所期望的。 +但是，提供的输出可能并不总是你所期望的。 -为了解决这个问题，您可以使用自己的 `renderer` 根据规则自定义环绕文本的 HTML 元素。 -您可以通过扩展默认的 [`RendererHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts) 来修改特定规则，或者通过实现 [`Renderer`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts) 来覆盖所有规则。 +为了解决这个问题，你可以使用自己的 `renderer` 根据规则自定义环绕文本的 HTML 元素。 +你可以通过扩展默认的 [`RendererHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer_html.ts) 来修改特定规则，或者通过实现 [`Renderer`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/renderers/renderer.ts) 来覆盖所有规则。 要扩展现有的 `renderer`，请执行以下操作： @@ -109,7 +109,7 @@ const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); - `text`：当前实体引用的特定文本。 - `entity`：根据实体类型以不同接口表示，例如 `CommonEntity`、`CustomEmojiEntity`、`PreEntity`、`TextLinkEntity` 或 `TextMentionEntity`。 - 例如，`bold` 实体符合 `CommonEntity` 接口，而 `text_link` 实体则符合 `TextLinkEntity` 接口，因为它包含其他属性，例如 `url`。 + 例如，`bold` 实体符合 `CommonEntity` 接口，而 `text_link` 实体则符合 `TextLinkEntity` 接口，因为它包含其他额外属性，例如 `url`。 以下是接口的完整列表以及每种实体类型的输出： @@ -151,13 +151,13 @@ const entitiesParser = new EntitiesParser({ renderer: new MyRenderer() }); 例如，结果 `粗体 & 斜体` 将被清理为 `粗体 & 斜体`。 -您可以在实例化 [`EntitiesParser`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/mod.ts) 时指定 `textSanitizer` 来覆盖此行为： +你可以在实例化 [`EntitiesParser`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/mod.ts) 时指定 `textSanitizer` 来覆盖此行为： -- 如果您未指定 `textSanitizer`，它将默认使用 [`sanitizerHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/utils/sanitizer_html.ts) 作为清理程序。 +- 如果你未指定 `textSanitizer`，它将默认使用 [`sanitizerHtml`](https://github.com/quadratz/telegram-entities-parser/blob/main/src/utils/sanitizer_html.ts) 作为清理程序。 - 将值设置为 `false` 将跳过清理，保持输出文本为原始文本。 - 不建议这样做，因为它可能会导致渲染不正确，并使您的应用程序容易受到 XSS 攻击。 - 如果选择此选项，请确保您正确处理输出文本。 -- 如果您提供一个函数，它将被用来代替默认清理程序。 + 不建议这样做，因为它可能会导致渲染不正确，并使你的应用程序容易受到 XSS 攻击。 + 如果选择此选项，请确保你正确处理输出文本。 +- 如果你提供一个函数，它将被用来代替默认清理程序。 ```ts const myTextSanitizer: TextSanitizer = (options: TextSanitizerOption): string => @@ -185,13 +185,13 @@ const entitiesParser = new EntitiesParser({ textSanitizer: myTextSanitizer }); ## 最好不要使用这个包的情况 -如果您遇到的问题和下面列出的问题类似，您可能不需要使用这个包就能解决问题。 +如果你遇到的问题和下面列出的问题类似，你可能不需要使用这个包就能解决问题。 ### 复制和转发同一条消息 使用 [`forwardMessage`](https://core.telegram.org/bots/api#forwardmessage) 即可转发任何类型的消息。 -您还可以使用 [`copyMessage`](https://core.telegram.org/bots/api#copymessage) API。该 API 会执行同样的操作，但不包含指向原始消息的链接。 +你还可以使用 [`copyMessage`](https://core.telegram.org/bots/api#copymessage) API。该 API 会执行同样的操作，但不包含指向原始消息的链接。 [`copyMessage`](https://core.telegram.org/bots/api#copymessage) 的行为类似于复制消息并将其发送回 Telegram，使其显示为常规消息而不是转发的消息。 ```ts