@libs-ui/services-format-date

Service Angular định dạng ngày giờ linh hoạt, hỗ trợ nhiều kiểu input, format aliases locale-aware và đa ngôn ngữ vi/en.

Giới thiệu

FormatDateService là một thin wrapper của hàm formatDate() từ @libs-ui/utils, được đóng gói thành Angular service để dễ dàng inject qua DI và sử dụng trực tiếp trong template. Service hỗ trợ nhiều kiểu đầu vào (Unix timestamp giây, ISO string, dayjs object), định dạng tùy chỉnh theo chuẩn dayjs, format aliases ngắn gọn tự động chọn format phù hợp theo ngôn ngữ vi/en, cùng cơ chế override toàn cục cho các project cần custom logic.

Tính năng

• ✅ Input types đa dạng: Unix timestamp (giây), ISO string, dayjs object
• ✅ Format aliases locale-aware: dmy, dmy hm, dmy hms, my, dm... tự chọn format theo ngôn ngữ
• ✅ Đa ngôn ngữ: vi/en — tiếng Việt ngày trước tháng, tiếng Anh tháng trước ngày
• ✅ Tự động lấy ngôn ngữ từ UtilsCache.getLang() nếu không truyền lang
• ✅ null/undefined → trả về '' (không throw error)
• ✅ Custom format override toàn cục qua updateFunctionFormatDate
• ✅ Múi giờ chuẩn hóa qua getDayjs() (mặc định Asia/Ho_Chi_Minh)
• ✅ providedIn: 'root' — không cần khai báo providers thủ công

Khi nào sử dụng

• Cần inject service để dùng transform() trực tiếp trong template Angular (ví dụ: trong computed, @switch, binding).
• Muốn mock service trong unit test — dễ mock hơn hàm utils standalone.
• Cần format ngày giờ theo ngôn ngữ hiện tại của ứng dụng mà không muốn tự quản lý lang.
• Cần format date trong TypeScript class thông qua DI (nếu không cần DI, dùng thẳng formatDate() từ @libs-ui/utils).

Cài đặt

npm install @libs-ui/services-format-date

Import

import { FormatDateService } from '@libs-ui/services-format-date';

Ví dụ sử dụng

Ví dụ 1 — Cơ bản: Unix timestamp với format mặc định

import { Component, inject } from '@angular/core';
import { FormatDateService } from '@libs-ui/services-format-date';

@Component({
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <p>{{ formatDateService.transform(timestamp) }}</p>
    <!-- Output: "2024/05/20 17:30" -->

    <p>{{ formatDateService.transform(timestamp, 'DD/MM/YYYY') }}</p>
    <!-- Output: "20/05/2024" -->
  `,
})
export class ExampleComponent {
  readonly formatDateService = inject(FormatDateService);

  timestamp = 1716222600; // Unix timestamp (giây)
}

Ví dụ 2 — Format aliases locale-aware (vi/en)

import { Component, inject } from '@angular/core';
import { FormatDateService } from '@libs-ui/services-format-date';

@Component({
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <!-- lang='vi': "20 Thg 5, 2024 10:30" -->
    <p>{{ formatDateService.transform(dateStr, 'dmy hm', 'vi') }}</p>

    <!-- lang='en': "May 20, 2024 10:30" -->
    <p>{{ formatDateService.transform(dateStr, 'dmy hm', 'en') }}</p>

    <!-- Chỉ ngày tháng năm (vi): "20 Thg 5, 2024" -->
    <p>{{ formatDateService.transform(dateStr, 'dmy', 'vi') }}</p>

    <!-- Chỉ tháng năm (vi): "Thg 5, 2024" -->
    <p>{{ formatDateService.transform(dateStr, 'my', 'vi') }}</p>
  `,
})
export class LocaleExampleComponent {
  readonly formatDateService = inject(FormatDateService);

  dateStr = '2024-05-20T10:30:00'; // ISO string
}

Ví dụ 3 — Trong TypeScript class (computed, xử lý logic)

import { Component, inject, computed, signal } from '@angular/core';
import { FormatDateService } from '@libs-ui/services-format-date';

@Component({
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `<p>{{ displayDate() }}</p>`,
})
export class ComputedExampleComponent {
  private readonly formatDateService = inject(FormatDateService);

  private rawTimestamp = signal<number>(1716222600);

  protected displayDate = computed(() =>
    this.formatDateService.transform(this.rawTimestamp(), 'dmy hm', 'vi')
  );
}

Ví dụ 4 — ISO string với format giây

import { Component, inject } from '@angular/core';
import { FormatDateService } from '@libs-ui/services-format-date';

@Component({
  standalone: true,
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <!-- Output: "20/05/2024 10:30:00" -->
    <p>{{ formatDateService.transform(isoDate, 'DD/MM/YYYY HH:mm:ss') }}</p>

    <!-- null/undefined → '' (không crash) -->
    <p>{{ formatDateService.transform(null) }}</p>
  `,
})
export class IsoExampleComponent {
  readonly formatDateService = inject(FormatDateService);

  isoDate = '2024-05-20T10:30:00';
}

Ví dụ 5 — Không dùng DI: formatDate() từ @libs-ui/utils (khuyến nghị cho TypeScript thuần)

import { formatDate } from '@libs-ui/utils';

// Không inject service — dùng thẳng hàm utils
const result = formatDate(1716222600, 'YYYY/MM/DD HH:mm');
// Output: '2024/05/20 17:30'

const viDate = formatDate('2024-05-20T10:30:00', 'dmy hm', 'vi');
// Output: '20 Thg 5, 2024 10:30'

const enDate = formatDate('2024-05-20T10:30:00', 'dmy hm', 'en');
// Output: 'May 20, 2024 10:30'

Methods (Service)

| Method | Signature | Mô tả | |---|---|---| | transform | transform(time, format?, lang?): string | Định dạng giá trị thời gian thành chuỗi. Trả về '' nếu time là null/undefined. |

Chi tiết tham số transform()

| Tham số | Type | Default | Mô tả | |---|---|---|---| | time | string \| number \| dayjs.Dayjs \| undefined \| null | — | Giá trị thời gian cần format. null/undefined → trả về ''. | | format | string | 'YYYY/MM/DD HH:mm' | Format dayjs chuẩn hoặc alias ngắn gọn (xem bảng Format Aliases). | | lang | string \| undefined | UtilsCache.getLang() | Ngôn ngữ: 'vi' hoặc 'en'. Không truyền → tự lấy từ cache toàn cục. |

Returns: string — chuỗi đã format, hoặc '' nếu input là null/undefined.

Format Aliases (locale-aware)

Các alias dưới đây tự động chọn format phù hợp theo ngôn ngữ (lang). Format string trực tiếp (như DD/MM/YYYY) không phụ thuộc ngôn ngữ.

| Alias | Format vi | Format en | Ghi chú | |---|---|---|---| | dmy hm | D MMM, YYYY HH:mm | MMM D, YYYY HH:mm | Ngày tháng năm giờ phút | | dmy | D MMM, YYYY | MMM D, YYYY | Ngày tháng năm | | dm | D MMM | MMM D | Ngày tháng | | my | MMM, YYYY | MMM YYYY | Tháng năm | | dmy hms | D MMM, YYYY HH:mm:ss | MMM D, YYYY HH:mm:ss | Có giây | | dmy hmsS | D MMM, YYYY HH:mm:ss:SSS | MMM D, YYYY HH:mm:ss:SSS | Có millisecond | | HH:mm | HH:mm | HH:mm | 24h format | | HH:mm A | HH:mm A | HH:mm A | 12h AM/PM |

Các format string tương đương được map tự động:

| Format string truyền vào | Map sang alias | |---|---| | DD/MM/YYYY, YYYY-MM-DD, dd/MM/yyyy | dmy | | MM-DD, dd/MM, dd/mm | dm | | M/YYYY, YYYY-MM, MM/yyyy | my | | YYYY/MM/DD hh:mm:ss, dd/mm/yyyy hh:mm:ss | dmy hms | | Bất kỳ format khác không thuộc danh sách trên | Mặc định map sang dmy hm |

Types & Interfaces

import { TYPE_FUNCTION_FORMAT_DATE } from '@libs-ui/utils';

// Type của hàm custom override (dùng với updateFunctionFormatDate)
// type TYPE_FUNCTION_FORMAT_DATE = (time: dayjs.ConfigType, formatOutput: string, lang?: string) => string;

Custom Override toàn cục

Dùng updateFunctionFormatDate từ @libs-ui/utils để override toàn bộ logic format — chạy một lần khi app khởi động:

import { updateFunctionFormatDate } from '@libs-ui/utils';

// Trong AppComponent hoặc app initializer:
updateFunctionFormatDate((time, format, lang) => {
  // Custom format logic của project
  return myCustomFormatter(time, format, lang);
});

Lưu ý quan trọng

⚠️ Inject service hay dùng thẳng utils?: Nếu chỉ cần format date trong TypeScript (không trong template hoặc không cần DI/mock), dùng thẳng formatDate() từ @libs-ui/utils. Inject FormatDateService khi cần DI (mock test) hoặc dùng trong Angular template qua service reference.

⚠️ Unix timestamp là giây, không phải milliseconds: Date.now() trả về milliseconds. Khi dùng JS timestamp làm input, phải chia 1000: service.transform(Date.now() / 1000).

⚠️ lang không truyền → tự lấy từ UtilsCache: Đảm bảo ngôn ngữ global đã được set trước khi dùng service (thường trong AppComponent hoặc i18n setup). Nếu chưa set, format aliases có thể không trả về đúng locale.

⚠️ Format aliases chỉ locale-aware khi truyền lang='vi' hoặc lang='en': Format string trực tiếp như DD/MM/YYYY HH:mm không phụ thuộc ngôn ngữ, luôn cho cùng kết quả bất kể lang.

⚠️ Múi giờ mặc định Asia/Ho_Chi_Minh: Service dùng getDayjs() đã cấu hình timezone. Để đổi timezone toàn cục, gọi setDefaultTimeZone('America/New_York') từ @libs-ui/utils trước khi dùng.