Chuyển đến nội dung chính

Khoảng Thời Gian

Một thuộc tính timeInterval là một quy tắc lặp lại, không phải là danh sách các khoảng thời gian: một ngày neo, các khoảng thời gian hàng ngày và các cờ lặp lại. Giải quyết nó thành các cặp [start, end] cụ thể cho khoảng thời gian bạn thực sự hiển thị với các trợ giúp cấp cao nhất expandAttributeTimeIntervals, expandTimeIntervals và bộ bảo vệ kiểu isTimeIntervalAttribute.

import { expandAttributeTimeIntervals } from 'oneentry';

const slots = expandAttributeTimeIntervals(page.attributeValues.interval, {
  from: '2025-04-01',
  to: '2025-04-30',
});
// [['2025-04-14T09:00:00.000Z', '2025-04-14T10:00:00.000Z'], …]

Cả ba trợ giúp đều là thuần túy — chúng không thay đổi đầu vào của mình và không thực hiện bất kỳ yêu cầu nào.

Nơi lưu trữ lịch trình​

API trả về lịch trình dưới hai hình thức, và cả hai đều được các trợ giúp chấp nhận:

Hình thứcNơi tìm thấyChứa
Thực thể (ITimeIntervalEntitySchedule)attributeValues[marker].value[].values[] trên các trang, sản phẩm, khối và tập thuộc tínhmột khoảng dates với các cặp times
Biểu mẫu (ITimeIntervalSchedule)attributes[].localizeInfos.intervals[] trên các biểu mẫumột range với các intervals mang một khoảng thời gian period tính bằng phút

expandAttributeTimeIntervals(attr, window)​

Đường dẫn một lần gọi cho các thuộc tính thực thể: nó đi qua các nhóm và lịch trình của thuộc tính, mở rộng từng cái và gộp các kết quả lại. Việc gộp lại là quan trọng — việc loại bỏ trùng lặp và sắp xếp chỉ giữ trong một lịch trình duy nhất, vì vậy việc kết hợp các nhóm bằng tay có thể tạo ra các khoảng thời gian trùng lặp hoặc không được sắp xếp.

Bất cứ điều gì không phải là thuộc tính timeInterval sẽ trả về một mảng rỗng, vì vậy bạn có thể gọi mà không cần kiểm tra type trước.

import { expandAttributeTimeIntervals } from 'oneentry';

const page = await Pages.getPageByUrl('booking');

const slots = expandAttributeTimeIntervals(page.attributeValues.interval, {
  from: '2025-04-01',
  to: '2025-04-30',
});

expandTimeIntervals(schedule, window)​

Giải quyết một lịch trình đơn. Hãy sử dụng nó khi bạn đã có một cái — đặc biệt là trên các biểu mẫu, mà lịch trình của chúng đã được gán kiểu tại localizeInfos.intervals:

import { expandTimeIntervals } from 'oneentry';

const form = await Forms.getFormByMarker('booking_form');
const field = form.attributes.find((a) => a.marker === 'schedule');

const slots = (field?.localizeInfos.intervals ?? []).flatMap((schedule) =>
  expandTimeIntervals(schedule, { from: '2025-05-01', to: '2025-05-31' }),
);

isTimeIntervalAttribute(attr)​

IAttributeValue.value được gán kiểu unknown, vì hình thức của nó phụ thuộc vào type. Bộ bảo vệ kiểu này thu hẹp một thuộc tính thành ITimeIntervalAttributeValue, cho phép bạn truy cập các lịch trình mà không cần ép kiểu:

import { isTimeIntervalAttribute } from 'oneentry';

const attr = page.attributeValues.interval;

if (isTimeIntervalAttribute(attr)) {
  attr.value[0].values[0].dates; // fully typed
}

Cửa sổ​

const window = { from: '2025-04-01', to: '2025-04-30' };
  • from và to chấp nhận một Date, một chuỗi ISO hoặc mili giây epoch.
  • Cả hai giới hạn đều bao gồm và được so sánh ở độ phân giải ngày UTC — phần thời gian trong ngày của from/to bị bỏ qua.
  • Cửa sổ là bắt buộc: một lịch trình là một quy tắc lặp lại không có giới hạn, và chỉ bạn biết nó cần được giải quyết xa đến đâu.

Ngữ nghĩa lặp lại​

  • dates[0] / range[0] vừa là giai đoạn lặp lại vừa là ngày hợp lệ đầu tiên — không có gì sớm hơn được phát ra, bất kể cửa sổ rộng đến đâu.
  • dates[1] / range[1] kết thúc tính hợp lệ. Khi nó không kéo dài qua ngày bắt đầu, lịch trình được neo vào ngày duy nhất đó; với một cờ lặp lại được thiết lập, lặp lại sau đó là không có giới hạn và chỉ cửa sổ giới hạn kết quả.
  • inEveryWeek lặp lại mỗi 7 ngày từ điểm neo.
  • inEveryMonth lặp lại vào cùng một ngày trong tháng, bỏ qua các tháng quá ngắn.
  • Với cả hai cờ được thiết lập, quy tắc hàng tuần được áp dụng — điều này luôn có nghĩa như vậy trong thực tế.
  • Với không có cờ nào, lịch trình là một khoảng thời gian đơn giản: mỗi ngày trong đó tạo ra các khoảng thời gian.
  • Kết quả được loại bỏ trùng lặp và sắp xếp theo thời gian bắt đầu, sau đó là thời gian kết thúc.
  • Tất cả các phép toán đều theo UTC, vì vậy kết quả không phụ thuộc vào múi giờ của máy.

Di chuyển từ trường timeIntervals​

Các phiên bản SDK trước đây đã chèn một mảng timeIntervals được tính toán vào mỗi giá trị thuộc tính timeInterval. Trường đó không còn tồn tại. Nó tạo ra một năm đầy đủ các khoảng thời gian bất kể những gì người gọi cần — một thuộc tính duy nhất với các khoảng thời gian theo giờ được mở rộng thành khoảng 2,000 dòng JSON, và các khoảng thời gian chi tiết hơn đạt đến megabyte, đủ để vượt qua giới hạn bộ nhớ cache dữ liệu của framework. Nó cũng không bao giờ được khai báo trong bất kỳ giao diện hoặc sơ đồ nào, vì vậy người tiêu dùng TypeScript chỉ có thể truy cập nó thông qua ép kiểu.

// before — read the pre-computed field
const slots = page.attributeValues.interval.value[0].values[0].timeIntervals;

// now — expand the window you actually render
import { expandAttributeTimeIntervals } from 'oneentry';

const slots = expandAttributeTimeIntervals(page.attributeValues.interval, {
  from: '2025-04-01',
  to: '2025-04-30',
});

Dữ liệu nguồn đang được mở rộng (dates/range, times/intervals, inEveryWeek, inEveryMonth) không thay đổi và vẫn có mặt trên mỗi lịch trình — không có gì bị mất, nó chỉ được giải quyết theo yêu cầu thay vì một cách háo hức, và quy tắc gọn gàng là những gì được lưu vào bộ nhớ cache.

Các phương thức _addTimeIntervalsToSchedules và _addTimeIntervalsToFormSchedules đã bị loại bỏ khỏi mọi mô-đun (mặc dù có tiền tố _, chúng vẫn có thể được gọi, ví dụ: Pages._addTimeIntervalsToSchedules). Sử dụng expandTimeIntervals thay thế.

Các loại​

Tất cả những loại này đều được xuất từ gốc gói và từ oneentry/types (xem Nhập các loại):

LoạiMô tả
ITimeIntervalAttributeValueMột IAttributeValue được thu hẹp thành type: 'timeInterval', mà value là một mảng các nhóm
ITimeIntervalGroupMột mục trong value của thuộc tính — các lịch trình chia sẻ một intervalId
ITimeIntervalEntityScheduleMột lịch trình thực thể: dates, times, inEveryWeek, inEveryMonth
ITimeIntervalScheduleMột lịch trình biểu mẫu: range, intervals, inEveryWeek, inEveryMonth
ITimeIntervalRangeMột khoảng thời gian hàng ngày với start, end và một khoảng thời gian period tính bằng phút (null khi không được cắt)
ITimeIntervalPointMột điểm trong một ngày - { hours, minutes }
ITimeIntervalWindowCửa sổ mở rộng - { from, to }
TimeIntervalPairMột khoảng thời gian đã được giải quyết - [start, end], cả hai là chuỗi ISO 8601 UTC

Ví dụ: hiển thị một tháng các khoảng thời gian​

import { expandAttributeTimeIntervals } from 'oneentry';

const page = await Pages.getPageByUrl('booking');

if ('statusCode' in page) {
  throw new Error(page.message);
}

const slots = expandAttributeTimeIntervals(page.attributeValues.interval, {
  from: '2025-04-01',
  to: '2025-04-30',
});

// Group the slots by day for a calendar view
const byDay = slots.reduce((acc, [start, end]) => {
  const day = start.slice(0, 10);
  (acc[day] ??= []).push([start, end]);
  return acc;
}, {});

🔗 Tài liệu liên quan​