@libs-ui/pipes-format-text-first-letter-to-uppercase

Pipe Angular viết hoa chữ cái đầu tiên của chuỗi (sentence case), hỗ trợ nhiều tùy chọn làm sạch và chuẩn hóa text.

Giới thiệu

LibsUiPipesFormatTextFirstLetterToUpperCasePipe là một Angular standalone pipe dùng để viết hoa duy nhất ký tự đầu tiên của chuỗi (sentence case). Khác với capitalize (viết hoa đầu mỗi từ), pipe này chỉ tác động vào ký tự vị trí 0 của chuỗi. Pipe hỗ trợ thêm nhiều tùy chọn xử lý text như lowercase các ký tự còn lại, loại bỏ emoji, xóa khoảng trắng thừa và loại bỏ dấu unicode.

Tính năng

• Viết hoa chữ cái đầu tiên của chuỗi (sentence case)
• Hỗ trợ lowercaseOtherCharacter: chuyển toàn bộ ký tự còn lại về chữ thường
• Hỗ trợ uppercaseOtherCharacter: viết hoa tất cả ký tự
• Hỗ trợ trim: loại bỏ khoảng trắng đầu/cuối chuỗi
• Hỗ trợ removeMultipleSpace: thu gọn nhiều khoảng trắng liên tiếp thành một
• Hỗ trợ removeEmoji: loại bỏ emoji khỏi chuỗi
• Hỗ trợ removeUnicode: loại bỏ dấu unicode
• Trả về nguyên giá trị đầu vào khi chuỗi là null, undefined hoặc rỗng (không throw error)
• Standalone pipe — import trực tiếp vào component, không cần NgModule

Khi nào sử dụng

• Viết hoa chữ cái đầu của một câu hoặc đoạn văn (sentence case)
• Format tiêu đề câu thay vì title case (dùng capitalize nếu cần title case)
• Chuẩn hóa text input từ người dùng: chỉ capitalize ký tự đầu chuỗi
• Xử lý text có chứa emoji hoặc unicode đặc biệt ở đầu chuỗi trước khi hiển thị
• Hiển thị tên riêng, tên thành phố, câu mô tả với định dạng chuẩn

Cài đặt

npm install @libs-ui/pipes-format-text-first-letter-to-uppercase

Import

import { LibsUiPipesFormatTextFirstLetterToUpperCasePipe } from '@libs-ui/pipes-format-text-first-letter-to-uppercase';

// Interface options (tùy chọn, dùng khi cần type-safe cho options)
import { ITextFormatOptions } from '@libs-ui/interfaces-types';

Ví dụ sử dụng

Ví dụ 1 — Cơ bản (viết hoa ký tự đầu tiên)

import { Component } from '@angular/core';
import { LibsUiPipesFormatTextFirstLetterToUpperCasePipe } from '@libs-ui/pipes-format-text-first-letter-to-uppercase';

@Component({
  selector: 'app-example-basic',
  standalone: true,
  imports: [LibsUiPipesFormatTextFirstLetterToUpperCasePipe],
  template: `
    <p>{{ 'hello world' | LibsUiPipesFormatTextFirstLetterToUpperCasePipe }}</p>
    <!-- Output: Hello world -->

    <p>{{ 'angular framework' | LibsUiPipesFormatTextFirstLetterToUpperCasePipe }}</p>
    <!-- Output: Angular framework -->
  `,
})
export class ExampleBasicComponent {}

Ví dụ 2 — Sentence case (lowercase toàn bộ + hoa chữ đầu)

import { Component } from '@angular/core';
import { LibsUiPipesFormatTextFirstLetterToUpperCasePipe } from '@libs-ui/pipes-format-text-first-letter-to-uppercase';
import { ITextFormatOptions } from '@libs-ui/interfaces-types';

@Component({
  selector: 'app-example-sentence',
  standalone: true,
  imports: [LibsUiPipesFormatTextFirstLetterToUpperCasePipe],
  template: `
    <p>{{ 'HELLO WORLD EXAMPLE' | LibsUiPipesFormatTextFirstLetterToUpperCasePipe: sentenceOptions }}</p>
    <!-- Output: Hello world example -->
  `,
})
export class ExampleSentenceComponent {
  sentenceOptions: ITextFormatOptions = {
    lowercaseOtherCharacter: true,
    trim: true,
  };
}

Ví dụ 3 — Loại bỏ emoji trước khi capitalize

import { Component } from '@angular/core';
import { LibsUiPipesFormatTextFirstLetterToUpperCasePipe } from '@libs-ui/pipes-format-text-first-letter-to-uppercase';
import { ITextFormatOptions } from '@libs-ui/interfaces-types';

@Component({
  selector: 'app-example-emoji',
  standalone: true,
  imports: [LibsUiPipesFormatTextFirstLetterToUpperCasePipe],
  template: `
    <p>{{ '👋 hello world' | LibsUiPipesFormatTextFirstLetterToUpperCasePipe: emojiOptions }}</p>
    <!-- Output: Hello world -->
  `,
})
export class ExampleEmojiComponent {
  emojiOptions: ITextFormatOptions = {
    removeEmoji: true,
    trim: true,
  };
}

Ví dụ 4 — Kết hợp nhiều tùy chọn

import { Component } from '@angular/core';
import { LibsUiPipesFormatTextFirstLetterToUpperCasePipe } from '@libs-ui/pipes-format-text-first-letter-to-uppercase';
import { ITextFormatOptions } from '@libs-ui/interfaces-types';

@Component({
  selector: 'app-example-complex',
  standalone: true,
  imports: [LibsUiPipesFormatTextFirstLetterToUpperCasePipe],
  template: `
    <p>{{ rawText | LibsUiPipesFormatTextFirstLetterToUpperCasePipe: complexOptions }}</p>
    <!-- Output: Hello world example -->
  `,
})
export class ExampleComplexComponent {
  rawText = '  HELLO   WORLD   example  👋  ';

  complexOptions: ITextFormatOptions = {
    lowercaseOtherCharacter: true,
    trim: true,
    removeMultipleSpace: true,
    removeEmoji: true,
  };
}

Ví dụ 5 — Dùng hàm utils trực tiếp trong TypeScript

Pipe là thin wrapper của hàm firstLetterToUpperCase trong @libs-ui/utils. Khi cần gọi trong TypeScript (không phải template), import và dùng thẳng hàm — không cần inject pipe.

import { Component } from '@angular/core';
import { firstLetterToUpperCase } from '@libs-ui/utils';

@Component({
  selector: 'app-example-ts',
  standalone: true,
  template: `<p>{{ formattedText }}</p>`,
})
export class ExampleTsComponent {
  // Cơ bản
  formattedText = firstLetterToUpperCase('hello world');
  // Output: 'Hello world'

  // Sentence case
  sentenceCase = firstLetterToUpperCase('HELLO WORLD', {
    lowercaseOtherCharacter: true,
    trim: true,
  });
  // Output: 'Hello world'

  // Xử lý emoji + nhiều khoảng trắng
  cleanText = firstLetterToUpperCase('  👋 hello   world  ', {
    removeEmoji: true,
    trim: true,
    removeMultipleSpace: true,
  });
  // Output: 'Hello world'
}

Transform (Pipe)

Cú pháp

value | LibsUiPipesFormatTextFirstLetterToUpperCasePipe
value | LibsUiPipesFormatTextFirstLetterToUpperCasePipe : options

Bảng tham số

| Tham số | Type | Bắt buộc | Mô tả | Ví dụ | |---|---|---|---|---| | value | string | Có | Chuỗi cần format | 'hello world' | | options | ITextFormatOptions | Không | Tùy chọn xử lý text | { trim: true } | | options.lowercaseOtherCharacter | boolean | Không — mặc định false | Viết thường các ký tự còn lại (không phải đầu chuỗi) | { lowercaseOtherCharacter: true } | | options.uppercaseOtherCharacter | boolean | Không — mặc định false | Viết hoa tất cả ký tự | { uppercaseOtherCharacter: true } | | options.trim | boolean | Không — mặc định false | Loại bỏ khoảng trắng đầu/cuối | { trim: true } | | options.removeMultipleSpace | boolean | Không — mặc định false | Thay thế nhiều khoảng trắng liên tiếp bằng một | { removeMultipleSpace: true } | | options.removeEmoji | boolean | Không — mặc định false | Loại bỏ emoji khỏi chuỗi | { removeEmoji: true } | | options.removeUnicode | boolean | Không — mặc định false | Loại bỏ dấu unicode | { removeUnicode: true } |

Giá trị trả về

| Input | options | Output | |---|---|---| | 'hello world' | — | 'Hello world' | | 'HELLO WORLD' | { lowercaseOtherCharacter: true } | 'Hello world' | | 'hello world' | { uppercaseOtherCharacter: true } | 'HELLO WORLD' | | ' hello world ' | { trim: true } | 'Hello world' | | 'hello world' | { removeMultipleSpace: true } | 'Hello world' | | '👋 hello world' | { removeEmoji: true, trim: true } | 'Hello world' | | null | — | null (trả nguyên bản, không throw) | | '' | — | '' (trả nguyên bản, không throw) |

Types & Interfaces

import { ITextFormatOptions } from '@libs-ui/interfaces-types';

interface ITextFormatOptions {
  uppercaseOtherCharacter?: boolean;  // Viết hoa tất cả ký tự
  lowercaseOtherCharacter?: boolean;  // Viết thường các ký tự còn lại
  trim?: boolean;                     // Loại bỏ khoảng trắng đầu/cuối
  removeMultipleSpace?: boolean;      // Thu gọn nhiều khoảng trắng liên tiếp
  removeEmoji?: boolean;              // Loại bỏ emoji
  removeUnicode?: boolean;            // Loại bỏ dấu unicode
}

So sánh với Capitalize Pipe

| Pipe | Input | Output | Mô tả | |---|---|---|---| | LibsUiPipesFormatTextFirstLetterToUpperCasePipe | 'hello world' | 'Hello world' | Sentence case — chỉ hoa ký tự đầu tiên của chuỗi | | LibsUiPipesFormatTextCapitalizePipe | 'hello world' | 'Hello World' | Title case — hoa ký tự đầu mỗi từ |

Lưu ý quan trọng

⚠️ Sentence case, không phải title case: Pipe này chỉ viết hoa ký tự đầu tiên của toàn bộ chuỗi (vị trí 0). Muốn viết hoa đầu mỗi từ, dùng @libs-ui/pipes-format-text-capitalize.

⚠️ Thứ tự xử lý options: Các options được áp dụng theo thứ tự cố định trước khi capitalize — uppercaseOtherCharacter → lowercaseOtherCharacter → removeMultipleSpace → removeEmoji → removeUnicode → trim → viết hoa ký tự đầu tiên. Thứ tự này không thể thay đổi.

⚠️ Falsy value an toàn: Khi value là null, undefined, hoặc chuỗi rỗng '', pipe trả về nguyên giá trị đầu vào mà không throw error.

⚠️ Dùng trong TypeScript: Không cần inject pipe khi dùng trong file .ts. Import trực tiếp hàm firstLetterToUpperCase từ @libs-ui/utils để có hiệu năng tốt hơn.