mirror of
https://github.com/acamarata/moment-hijri-plus.git
synced 2026-07-02 03:30:42 +00:00
61 lines
1.7 KiB
Markdown
61 lines
1.7 KiB
Markdown
# Advanced Usage
|
|
|
|
## Switching calendars per call
|
|
|
|
Each method accepts an optional options argument:
|
|
|
|
```typescript
|
|
import moment from 'moment';
|
|
import hijri from 'moment-hijri-plus';
|
|
|
|
moment.extend(hijri);
|
|
|
|
const m = moment('2023-03-23');
|
|
|
|
const uaqYear = m.iYear(); // UAQ (default)
|
|
const fcnaYear = m.iYear({ calendar: 'fcna' }); // FCNA
|
|
```
|
|
|
|
Near month boundaries, UAQ and FCNA may differ by one day.
|
|
|
|
## Null safety
|
|
|
|
`m.toHijri()` returns `null` for dates outside UAQ range (approximately 1900-2076 CE). Guard before using:
|
|
|
|
```typescript
|
|
const hijri = m.toHijri();
|
|
if (hijri !== null) {
|
|
console.log(hijri.hy, hijri.hm, hijri.hd);
|
|
}
|
|
```
|
|
|
|
## Combining with Moment.js locales
|
|
|
|
Moment.js locale settings affect Gregorian formatting but not Hijri tokens. Hijri tokens always produce the same English output regardless of locale. To localize Hijri month names, use `getHijriMonthName` from `date-fns-hijri` or build your own translation layer.
|
|
|
|
## Formatting alongside Gregorian tokens
|
|
|
|
Hijri tokens (`iYYYY`, `iMM`, `iDD`, `iMMMM`, etc.) coexist with Moment Gregorian tokens:
|
|
|
|
```typescript
|
|
m.format('YYYY-MM-DD (iD iMMMM iYYYY)');
|
|
// '2023-03-23 (1 Ramadan 1444)'
|
|
```
|
|
|
|
## Moment.js tree-shaking
|
|
|
|
Moment.js does not tree-shake well. If bundle size is a concern in a new project, consider migrating to Day.js + [dayjs-hijri-plus](https://github.com/acamarata/dayjs-hijri-plus) for the same Hijri API with significantly smaller bundles.
|
|
|
|
## TypeScript augmentation
|
|
|
|
The plugin augments Moment.js type definitions automatically:
|
|
|
|
```typescript
|
|
import moment from 'moment';
|
|
import hijri from 'moment-hijri-plus';
|
|
|
|
moment.extend(hijri);
|
|
|
|
const m = moment('2023-03-23');
|
|
const year: number = m.iYear(); // fully typed
|
|
```
|