Giá trị thuộc tính

Các thuộc tính là cách mà OneEntry mô tả nội dung: một trang, sản phẩm, khối, người dùng, đơn hàng hoặc trường biểu mẫu mang một bản đồ các giá trị thuộc tính được khóa bởi dấu hiệu. SDK chuẩn hóa mọi thuộc tính của mọi phản hồi về cùng một hình dạng, vì vậy cùng một trường sẽ trông giống nhau bất kể mô-đun nào trả về nó.

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

page.attributeValues.title.value;   // "Catalog"        — string
page.attributeValues.amount.value;  // 5                — number
page.attributeValues.cover.value;   // { downloadLink } — the file object itself
page.attributeValues.notes.value;   // null             — no value set

Hình dạng đã chuẩn hóa

Một giá trị thuộc tính là một IAttributeValue: { type, value, position?, additionalFields? }. Giá trị của value phụ thuộc vào type:

Loại thuộc tính	value
string, text	string
integer, float, real	number — chuyển đổi từ dạng chuỗi của API
image, file với một tệp	chính đối tượng tệp
image, file với nhiều tệp	một mảng các đối tượng tệp
groupOfImages	luôn là một mảng — nó là một bộ sưu tập theo định nghĩa
list	một mảng
timeInterval	một mảng các nhóm — xem Khoảng thời gian
không có giá trị nào được thiết lập	luôn là null

Các thuộc tính tệp đơn được giải nén

Khi một thuộc tính image hoặc file chứa chính xác một tệp, giá trị của nó là chính đối tượng tệp. Chỉ những giá trị có hai hoặc nhiều tệp mới giữ nguyên dạng mảng.

const block = await Blocks.getBlockByMarker('promo');

// before: block.attributeValues.img.value[0].downloadLink
// now:    block.attributeValues.img.value.downloadLink

Điều này áp dụng trong mọi mô-đun. Trước đây, việc giải nén chỉ diễn ra trong các sản phẩm, menu, biểu mẫu, trường dữ liệu biểu mẫu, bộ thuộc tính, bộ sưu tập tích hợp và Pages.searchPage, và chỉ trên khóa attributeValues — ở mọi nơi khác (khối, tất cả các phương thức trang khác, Products.getProductsEmptyPage, Products.getProductBlockById, quản trị viên, giảm giá, mẫu, đơn hàng, người dùng) thuộc tính giống nhau đã đến dưới dạng một mảng có một phần tử, vì vậy người tiêu dùng phải phân nhánh theo hình dạng. Các thuộc tính attributes, các trường dữ liệu biểu mẫu và additionalFields lồng nhau chưa bao giờ được giải nén.

⚠️ Di chuyển: mã đọc value[0] từ sản phẩm hoặc menu không bị ảnh hưởng — những mô-đun đó đã trả về đối tượng. Mã đọc value[0] từ khối, trang, người dùng hoặc đơn hàng phải bỏ chỉ số.

groupOfImages là một bộ sưu tập theo định nghĩa và luôn giữ nguyên dạng mảng. Ở phía yêu cầu, IBodyTypeFile.value được gán kiểu IFileValue | IFileValue[] tương ứng.

Số là số

Các giá trị integer, float và real được chuyển đổi thành số. real trước đây được để lại dưới dạng chuỗi, vì vậy cùng một trường số đã đến tay người tiêu dùng dưới dạng 10 hoặc "10" tùy thuộc vào loại nào trong ba loại được khai báo:

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

// before: page.attributeValues.amount.value // "5"
// now:    page.attributeValues.amount.value // 5

Việc chuẩn hóa số cũng diễn ra trên các thuộc tính biểu mẫu và các trường dữ liệu biểu mẫu, mà đã bị bỏ qua hoàn toàn — một trường rating của thuộc tính biểu mẫu integer là một number, không phải chuỗi.

Khi gửi dữ liệu, hãy gửi một chuỗi: IBodyTypeStringNumberFloat.value là string | number | null, và các phản hồi sẽ trở lại đã được chuẩn hóa.

Một giá trị trống luôn là null

API trả về một bản đồ địa phương hóa trống cho một giá trị chưa được thiết lập. SDK trước đây đã truyền nó qua cho các loại giống như văn bản trong khi các loại số trở thành null — cùng một trạng thái "không có giá trị" có ba đại diện. Bây giờ nó luôn là null.

if (page.attributeValues.notes.value === null) {
  // nothing configured for this attribute
}

⚠️ Di chuyển: một integer/float chưa được thiết lập không còn là 0. Number(null) là 0, vì vậy một null rõ ràng từ API trước đây được báo cáo là một số không thực — một giá trị không thể phân biệt với 0 đã được cấu hình.

Mọi thứ được sắp xếp theo vị trí

attributeValues luôn được trả về theo thứ tự position, và các thuộc tính biểu mẫu bây giờ cũng vậy. API trả về các trường biểu mẫu không theo thứ tự — một trường với position: 10 có thể đến sau position: 14 — vì vậy việc hiển thị một biểu mẫu theo thứ tự CMS yêu cầu phải sắp xếp ở phía người tiêu dùng.

Một biểu mẫu không có thuộc tính trả về attributes: []. API gửi một đối tượng trống trong trường hợp đó, và SDK chuẩn hóa nó thành một mảng trống, vì vậy attributes luôn là IFormAttribute[] và form.attributes.map(...) là an toàn trên mọi biểu mẫu.

Các trường lồng nhau: additionalFields

Các giá trị thuộc tính lồng nhau đến dưới additionalFields. Theo mặc định, SDK chuyển đổi mảng mà API trả về thành một đối tượng được khóa bởi marker; đặt rawData: true trong cấu hình để giữ nguyên mảng gốc — xem Định dạng Trường Bổ sung.

// default (rawData: false)
attribute.additionalFields['my_field'].value;

// rawData: true
attribute.additionalFields.find((f) => f.marker === 'my_field').value;

Các additionalFields lồng nhau trải qua cùng một quá trình chuẩn hóa như các thuộc tính cấp cao — các tệp đơn được giải nén và các số cũng được chuyển đổi ở đó.

Gán kiểu cho một giá trị thuộc tính

IAttributeValue.value được gán kiểu unknown, vì hình dạng của nó phụ thuộc vào type. Hãy thu hẹp nó trước khi sử dụng — đối với các thuộc tính timeInterval, SDK cung cấp một bộ bảo vệ kiểu:

import { isTimeIntervalAttribute } from 'oneentry';
import type { IAttributeValues } from 'oneentry';

function readText(values: IAttributeValues, marker: string): string {
  const value = values[marker]?.value;
  return typeof value === 'string' ? value : '';
}

---

🔗 Tài liệu liên quan

• Khoảng thời gian - mở rộng các thuộc tính timeInterval thành các khe
• Nhập các loại - IAttributeValue, IAttributeValues và phần còn lại
• Mô-đun AttributesSets - cách cấu hình các thuộc tính

---