@libs-ui/pipes-escape-html

Angular pipe escape các ký tự HTML đặc biệt, ngăn chặn XSS khi hiển thị nội dung không tin cậy.

Giới thiệu

LibsUiPipesEscapeHtmlPipe là một standalone Angular pipe bọc lại hàm escapeHtml từ @libs-ui/utils, chuyển đổi các ký tự HTML đặc biệt (<, >, &, ", ') thành HTML entities an toàn. Pipe xử lý null và undefined một cách an toàn — trả về chuỗi rỗng thay vì throw lỗi. Dùng trực tiếp trong Angular template bằng cú pháp pipe chuẩn.

Tính năng

• ✅ Escape 5 ký tự HTML đặc biệt: < > & " '
• ✅ Xử lý an toàn null và undefined (trả về '')
• ✅ Standalone pipe — import trực tiếp, không cần module
• ✅ Thin wrapper của escapeHtml từ @libs-ui/utils (có thể dùng hàm trực tiếp trong TS)
• ✅ Compatible với Angular Signals và OnPush Change Detection

Khi nào sử dụng

• Hiển thị nội dung từ user input để tránh XSS attacks
• Escape code snippets hoặc HTML examples trong UI
• Render an toàn dữ liệu từ API hoặc database có thể chứa HTML tags
• Truyền tham số vào i18n translate pipe khi tham số đến từ nguồn không tin cậy

Cài đặt

npm install @libs-ui/pipes-escape-html

Import

import { LibsUiPipesEscapeHtmlPipe } from '@libs-ui/pipes-escape-html';

@Component({
  standalone: true,
  imports: [LibsUiPipesEscapeHtmlPipe],
})
export class MyComponent {}

Ví dụ sử dụng

1. Escape XSS script tag

// component.ts
import { Component } from '@angular/core';
import { LibsUiPipesEscapeHtmlPipe } from '@libs-ui/pipes-escape-html';

@Component({
  standalone: true,
  imports: [LibsUiPipesEscapeHtmlPipe],
  template: `
    <p>{{ userInput | LibsUiPipesEscapeHtmlPipe }}</p>
  `,
})
export class CommentComponent {
  userInput = '<script>alert("xss")</script>';
  // Output: &lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;
}

2. Hiển thị an toàn user input chứa ký tự đặc biệt

// component.ts
import { Component, signal } from '@angular/core';
import { LibsUiPipesEscapeHtmlPipe } from '@libs-ui/pipes-escape-html';

@Component({
  standalone: true,
  imports: [LibsUiPipesEscapeHtmlPipe],
  template: `
    <div class="user-comment">
      <p>{{ userComment() | LibsUiPipesEscapeHtmlPipe }}</p>
    </div>
  `,
})
export class UserCommentComponent {
  userComment = signal('<img src=x onerror="alert(1)">');
  // Output: &lt;img src=x onerror=&quot;alert(1)&quot;&gt;
}

3. Escape ký tự đặc biệt trong chuỗi văn bản

// component.ts
import { Component } from '@angular/core';
import { LibsUiPipesEscapeHtmlPipe } from '@libs-ui/pipes-escape-html';

@Component({
  standalone: true,
  imports: [LibsUiPipesEscapeHtmlPipe],
  template: `
    <code>{{ specialChars | LibsUiPipesEscapeHtmlPipe }}</code>
  `,
})
export class CodeDisplayComponent {
  specialChars = '<div class="test">Hello & "World"</div>';
  // Output: &lt;div class=&quot;test&quot;&gt;Hello &amp; &quot;World&quot;&lt;/div&gt;
}

4. Xử lý null/undefined gracefully

// component.ts
import { Component, signal } from '@angular/core';
import { LibsUiPipesEscapeHtmlPipe } from '@libs-ui/pipes-escape-html';

@Component({
  standalone: true,
  imports: [LibsUiPipesEscapeHtmlPipe],
  template: `
    <p>{{ nullValue | LibsUiPipesEscapeHtmlPipe }}</p>
    <!-- Output: '' (chuỗi rỗng, không throw lỗi) -->
    <p>{{ undefinedValue | LibsUiPipesEscapeHtmlPipe }}</p>
    <!-- Output: '' -->
  `,
})
export class SafeComponent {
  nullValue: string | null = null;
  undefinedValue: string | undefined = undefined;
}

5. Dùng hàm escapeHtml trực tiếp trong TypeScript (không cần pipe)

Khi cần escape trong logic TS thay vì template, import trực tiếp hàm escapeHtml từ @libs-ui/utils — pipe chỉ là thin wrapper của hàm này.

import { Component, computed, signal } from '@angular/core';
import { escapeHtml } from '@libs-ui/utils';

@Component({
  standalone: true,
  template: `<p>{{ safeText() }}</p>`,
})
export class MyComponent {
  private rawInput = signal('<script>alert("xss")</script>');

  protected safeText = computed(() => escapeHtml(this.rawInput()));
  // Output: &lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;
}

Transform

Cú pháp

value | LibsUiPipesEscapeHtmlPipe

Tham số

| Tham số | Type | Bắt buộc | Mô tả | Ví dụ | |---------|-------------------------------|----------|----------------------------------------------------|--------------------------------------------------| | value | string \| null \| undefined | Có | Chuỗi cần escape các ký tự HTML đặc biệt | '<script>alert(1)</script>' |

Giá trị trả về

| Type | Mô tả | |----------|---------------------------------------------------------------------| | string | Chuỗi đã escape HTML entities. Trả về '' nếu input là null/undefined |

Ví dụ transform — template

<!-- Escape XSS -->
{{ '<script>alert(1)</script>' | LibsUiPipesEscapeHtmlPipe }}
<!-- Kết quả: &lt;script&gt;alert(1)&lt;/script&gt; -->

<!-- Escape ký tự đặc biệt -->
{{ '<div class="test">Hello & World</div>' | LibsUiPipesEscapeHtmlPipe }}
<!-- Kết quả: &lt;div class=&quot;test&quot;&gt;Hello &amp; World&lt;/div&gt; -->

<!-- Null trả về chuỗi rỗng -->
{{ null | LibsUiPipesEscapeHtmlPipe }}
<!-- Kết quả: '' -->

Ví dụ transform — standalone (pipe.transform)

import { LibsUiPipesEscapeHtmlPipe } from '@libs-ui/pipes-escape-html';

const pipe = new LibsUiPipesEscapeHtmlPipe();

pipe.transform('<script>alert(1)</script>');
// → '&lt;script&gt;alert(1)&lt;/script&gt;'

pipe.transform('<div class="a">Hello & "World"</div>');
// → '&lt;div class=&quot;a&quot;&gt;Hello &amp; &quot;World&quot;&lt;/div&gt;'

pipe.transform(null);
// → ''

pipe.transform(undefined);
// → ''

pipe.transform('');
// → ''

Bảng ký tự được escape

| Ký tự | HTML Entity | |-------|-------------| | < | < | | > | > | | & | & | | " | " | | ' | ' |

Lưu ý quan trọng

⚠️ Pipe trả về escaped text, không phải HTML an toàn để bind vào [innerHTML]: Sau khi escape, chuỗi sẽ hiển thị HTML entities dưới dạng text thuần. Nếu bind vào [innerHTML], nội dung sẽ hiển thị là text (entities sẽ được decode thành ký tự gốc dạng text), không render thành HTML. Đây là hành vi đúng — mục tiêu là ngăn render HTML nguy hiểm.

⚠️ Dùng hàm escapeHtml thay vì inject pipe trong TypeScript: Pipe là thin wrapper — khi cần escape trong logic TS, import trực tiếp escapeHtml từ @libs-ui/utils thay vì inject LibsUiPipesEscapeHtmlPipe. Không cần khai báo trong providers[].

⚠️ Không dùng pipe này để sanitize HTML cho phép render: Nếu cần cho phép một số HTML tags an toàn (bold, italic...) mà vẫn block XSS, dùng xssFilter từ @libs-ui/utils thay vì pipe này.

Unit Tests

# Chạy test cho lib
npx nx test pipes-escape-html

# Chạy test với coverage
npx nx test pipes-escape-html --coverage

# Chạy test single file
npx nx test pipes-escape-html --testFile=libs-ui/pipes/escape-html/src/escape-html.pipe.spec.ts