Temporal.Duration

Mô tả

Định dạng duration ISO 8601

Các đối tượng Duration có thể được tuần tự hóa và phân tích cú pháp bằng cách sử dụng định dạng duration ISO 8601 (với một số phần mở rộng được chỉ định bởi ECMAScript). Chuỗi có dạng sau (khoảng trắng chỉ để dễ đọc và không nên có trong chuỗi thực tế):

±P nY nM nW nD T nH nM nS

± Optional

Ký tự dấu tùy chọn (+ hoặc -), đại diện cho duration dương hoặc âm. Mặc định là dương.

P

Ký tự chữ P hoặc p đại diện cho "period" (khoảng thời gian).

nY, nM, nW, nD, nH, nM, nS

Một số theo sau bởi một ký tự chữ, đại diện cho số năm (Y), tháng (M), tuần (W), ngày (D), giờ (H), phút (M) hoặc giây (S) tương ứng. Tất cả ngoại trừ thành phần cuối cùng phải là số nguyên. Thành phần cuối cùng, nếu là thành phần thời gian (giờ, phút hoặc giây), có thể có phần thập phân từ 1 đến 9 chữ số, được dẫn đầu bởi dấu chấm hoặc dấu phẩy, chẳng hạn như PT0.0021S hoặc PT1.1H. Bất kỳ thành phần nào có giá trị bằng không đều có thể được bỏ qua, nhưng ít nhất một thành phần phải có mặt (ngay cả khi có giá trị bằng không, trong trường hợp đó duration là không).

T

Ký tự chữ T hoặc t phân tách phần ngày với phần giờ, nên có mặt khi và chỉ khi có ít nhất một thành phần sau nó.

Dưới đây là một số ví dụ:

Khi tuần tự hóa, đầu ra tôn trọng các thành phần được lưu trữ nhiều nhất có thể, bảo tồn các thành phần chưa cân bằng. Tuy nhiên, các thành phần dưới giây được tuần tự hóa thành một giây thập phân duy nhất, vì vậy các giá trị chính xác của chúng, nếu chưa cân bằng, có thể bị mất. Dấu cộng được bỏ qua cho các duration dương. Duration bằng không luôn được tuần tự hóa thành PT0S.

Duration lịch

Duration lịch là duration có chứa bất kỳ đơn vị lịch nào: tuần, tháng và năm. Duration không lịch có thể di chuyển được và có thể tham gia vào các phép tính số học ngày/giờ mà không cần bất kỳ thông tin lịch nào, vì chúng biểu diễn một lượng thời gian cố định rõ ràng. Tuy nhiên, duration lịch không thể di chuyển được vì số ngày trong một tháng hoặc năm phụ thuộc vào hệ thống lịch và điểm thời gian tham chiếu. Do đó, cố gắng thực hiện bất kỳ phép tính nào trên duration lịch sẽ ném ra lỗi vì các duration không tự theo dõi lịch. Ví dụ, nếu chúng ta đang ở tháng 5 của lịch Gregorian, thì "1 tháng" là "31 ngày", nhưng nếu chúng ta đang ở tháng 4, thì "1 tháng" trở thành "30 ngày". Để cộng hoặc trừ duration lịch, bạn cần thêm chúng vào các ngày tháng thay thế:

const dur1 = Temporal.Duration.from({ years: 1 });
const dur2 = Temporal.Duration.from({ months: 1 });

dur1.add(dur2); // RangeError: for calendar duration arithmetic, use date arithmetic relative to a starting point

const startingPoint = Temporal.PlainDate.from("2021-01-01"); // ISO 8601 calendar
startingPoint.add(dur1).add(dur2).since(startingPoint); // "P396D"

Các phép tính khác, round(), total() và compare(), nhận tùy chọn relativeTo để cung cấp thông tin lịch và thời gian tham chiếu cần thiết. Tùy chọn này có thể là Temporal.PlainDate, Temporal.PlainDateTime, Temporal.ZonedDateTime, hoặc đối tượng hay chuỗi có thể chuyển đổi bằng Temporal.ZonedDateTime.from() (nếu tùy chọn timeZone được cung cấp hoặc chuỗi chứa chú thích múi giờ) hoặc Temporal.PlainDate.from().

Lưu ý rằng việc chuyển đổi days sang hours cũng mơ hồ về mặt kỹ thuật vì độ dài của một ngày có thể thay đổi do thay đổi offset, chẳng hạn như giờ mùa hè. Bạn có thể cung cấp relativeTo có múi giờ để tính đến những thay đổi này; nếu không, ngày 24 giờ được giả định.

Cân bằng duration

Có nhiều cách để biểu diễn cùng một duration: ví dụ, "1 phút và 30 giây" và "90 giây" là tương đương. Tuy nhiên, tùy thuộc vào ngữ cảnh, một biểu diễn có thể phù hợp hơn biểu diễn kia. Do đó, nói chung, đối tượng Duration bảo tồn các giá trị đầu vào nhiều nhất có thể, để khi bạn định dạng nó, nó sẽ được hiển thị như bạn mong đợi.

Mỗi thành phần của duration có phạm vi tối ưu của nó; giờ nên từ 0 đến 23, phút từ 0 đến 59, v.v. Khi một thành phần vượt quá phạm vi tối ưu của nó, phần dư có thể được "mang" vào thành phần lớn hơn tiếp theo. Để mang, chúng ta cần trả lời câu hỏi "bao nhiêu X trong một Y?", đây là câu hỏi phức tạp cho đơn vị lịch, vì vậy trong trường hợp này cần có lịch. Cũng lưu ý rằng theo mặc định, days được mang trực tiếp vào months; đơn vị tuần chỉ được mang vào nếu được yêu cầu rõ ràng. Nếu chúng ta mang nhiều nhất có thể, kết quả cuối cùng trong đó tất cả các thành phần đều nằm trong phạm vi tối ưu của chúng được gọi là duration "cân bằng". Các duration chưa cân bằng thường có dạng "nặng đầu", trong đó đơn vị lớn nhất không cân bằng (ví dụ: "27 giờ và 30 phút"); các dạng khác, chẳng hạn như "23 giờ và 270 phút", hiếm khi được thấy.

Phương thức round() luôn cân bằng duration thành dạng "nặng đầu", lên đến tùy chọn largestUnit. Với tùy chọn largestUnit thủ công đủ lớn, bạn có thể cân bằng hoàn toàn duration. Tương tự, các phương thức add() và subtract() cân bằng duration kết quả thành đơn vị lớn nhất của các duration đầu vào.

Lưu ý rằng vì định dạng duration ISO 8601 biểu diễn các thành phần dưới giây thành một số phân số duy nhất, nên không thể bảo tồn các thành phần dưới giây chưa cân bằng trong quá trình tuần tự hóa bằng định dạng mặc định. Ví dụ, "1000 mili giây" được tuần tự hóa thành "PT1S", và sau đó được giải tuần tự hóa thành "1 giây". Nếu bạn cần bảo tồn độ lớn của các thành phần dưới giây, bạn cần tuần tự hóa thủ công như một đối tượng JSON thay thế (vì theo mặc định phương thức toJSON() tuần tự hóa duration theo định dạng ISO 8601).

Dấu duration

Vì duration là sự khác biệt giữa hai thời điểm, nó có thể là dương, âm hoặc bằng không. Ví dụ, nếu bạn đang hiển thị thời gian sự kiện theo thời gian tương đối, thì các duration âm có thể đại diện cho các sự kiện trong quá khứ, và các duration dương cho tương lai. Trong biểu diễn của chúng tôi sử dụng tổ hợp các thành phần thời gian, dấu được lưu trữ trong mỗi thành phần: duration âm luôn có tất cả các thành phần âm (hoặc bằng không), và duration dương luôn có tất cả các thành phần dương (hoặc bằng không). Xây dựng duration với các thành phần có dấu hỗn hợp là không hợp lệ và sẽ bị từ chối bởi constructor hoặc phương thức with(). Các phương thức add() và subtract() sẽ cân bằng duration kết quả để tránh dấu hỗn hợp.

Constructor

Temporal.Duration()

Tạo một đối tượng Temporal.Duration mới bằng cách cung cấp trực tiếp dữ liệu cơ bản.

Phương thức tĩnh

Temporal.Duration.compare()

Trả về một số (-1, 0 hoặc 1) cho biết duration đầu tiên ngắn hơn, bằng hay dài hơn duration thứ hai.

Temporal.Duration.from()

Tạo một đối tượng Temporal.Duration mới từ một đối tượng Temporal.Duration khác, một đối tượng có các thuộc tính duration, hoặc một chuỗi ISO 8601.

Thuộc tính instance

Các thuộc tính này được định nghĩa trên Temporal.Duration.prototype và được chia sẻ bởi tất cả các instance Temporal.Duration.

Temporal.Duration.prototype.blank

Trả về một boolean là true nếu duration này đại diện cho duration bằng không, và false nếu không. Tương đương với duration.sign === 0.

Temporal.Duration.prototype.constructor

Hàm constructor đã tạo đối tượng instance. Đối với các instance Temporal.Duration, giá trị ban đầu là constructor Temporal.Duration().

Temporal.Duration.prototype.days

Trả về một số nguyên đại diện cho số ngày trong duration.

Temporal.Duration.prototype.hours

Trả về một số nguyên đại diện cho số giờ trong duration.

Temporal.Duration.prototype.microseconds

Trả về một số nguyên đại diện cho số micro giây trong duration.

Temporal.Duration.prototype.milliseconds

Trả về một số nguyên đại diện cho số mili giây trong duration.

Temporal.Duration.prototype.minutes

Trả về một số nguyên đại diện cho số phút trong duration.

Temporal.Duration.prototype.months

Trả về một số nguyên đại diện cho số tháng trong duration.

Temporal.Duration.prototype.nanoseconds

Trả về một số nguyên đại diện cho số nano giây trong duration.

Temporal.Duration.prototype.seconds

Trả về một số nguyên đại diện cho số giây trong duration.

Temporal.Duration.prototype.sign

Trả về 1 nếu duration này là dương, -1 nếu âm và 0 nếu bằng không.

Temporal.Duration.prototype.weeks

Trả về một số nguyên đại diện cho số tuần trong duration.

Temporal.Duration.prototype.years

Trả về một số nguyên đại diện cho số năm trong duration.

Temporal.Duration.prototype[Symbol.toStringTag]

Giá trị ban đầu của thuộc tính [Symbol.toStringTag] là chuỗi "Temporal.Duration". Thuộc tính này được sử dụng trong Object.prototype.toString().

Phương thức instance

Temporal.Duration.prototype.abs()

Trả về một đối tượng Temporal.Duration mới với giá trị tuyệt đối của duration này (tất cả các trường giữ nguyên độ lớn, nhưng dấu trở thành dương).

Temporal.Duration.prototype.add()

Trả về một đối tượng Temporal.Duration mới với tổng của duration này và một duration đã cho (ở dạng có thể chuyển đổi bằng Temporal.Duration.from()). Kết quả được cân bằng.

Temporal.Duration.prototype.negated()

Trả về một đối tượng Temporal.Duration mới với giá trị phủ định của duration này (tất cả các trường giữ nguyên độ lớn, nhưng dấu bị đảo ngược).

Temporal.Duration.prototype.round()

Trả về một đối tượng Temporal.Duration mới với duration được làm tròn đến đơn vị nhỏ nhất đã cho và/hoặc cân bằng đến đơn vị lớn nhất đã cho.

Temporal.Duration.prototype.subtract()

Trả về một đối tượng Temporal.Duration mới với sự khác biệt giữa duration này và một duration đã cho (ở dạng có thể chuyển đổi bằng Temporal.Duration.from()). Tương đương với cộng giá trị phủ định của duration kia.

Temporal.Duration.prototype.toJSON()

Trả về một chuỗi đại diện cho duration này theo định dạng ISO 8601 giống như khi gọi toString(). Được thiết kế để được gọi ngầm định bởi JSON.stringify().

Temporal.Duration.prototype.toLocaleString()

Trả về một chuỗi với biểu diễn nhạy cảm với ngôn ngữ của duration này. Trong các triển khai có hỗ trợ API Intl.DurationFormat, phương thức này ủy quyền cho Intl.DurationFormat.

Temporal.Duration.prototype.toString()

Trả về một chuỗi đại diện cho duration này theo định dạng ISO 8601.

Temporal.Duration.prototype.total()

Trả về một số đại diện cho tổng duration theo đơn vị đã cho.

Temporal.Duration.prototype.valueOf()

Ném ra một TypeError, ngăn các instance Temporal.Duration bị chuyển đổi ngầm định thành primitives khi được sử dụng trong các phép tính số học hoặc so sánh.

Temporal.Duration.prototype.with()

Trả về một đối tượng Temporal.Duration mới đại diện cho duration này với một số trường được thay thế bằng các giá trị mới.

Đặc tả

Tương thích trình duyệt

Xem thêm

• Temporal