Thư viện xStore JS#

Liquid dựng sẵn nội dung ở phía máy chủ và chỉ đọc. Mọi thao tác ghi — thêm vào giỏ, đăng nhập, đặt hàng, gửi đánh giá — đều thực hiện qua thư viện JavaScript xStore ở phía trình duyệt.

Nhúng thư viện#

Thư viện đã có sẵn trong theme.html của bộ giao diện mặc định. Nếu bạn tự viết theme.html, thêm dòng sau trước thẻ </body>:

<script src="{{ 'xstore-sdk.js' | asset_url }}"></script>

Sau khi tệp tải xong, đối tượng window.xStore sẵn sàng dùng ngay.

Gọi API#

Phần lớn phương thức trả về Promise, nên dùng async/await:

<script>
  const cart = await xStore.cart.get();
  console.log(cart.item_count);
</script>

Một số hàm chạy cục bộ và trả kết quả ngay, không phải Promise: xStore.auth.isLoggedIn(), xStore.auth.logout(), xStore.cart.getToken(), toàn bộ xStore.product.* và xStore.utils.*.

Thư viện gọi tới đường dẫn /api/... trên chính tên miền cửa hàng, nên bạn không cần khai báo địa chỉ máy chủ ở bất kỳ đâu trong giao diện.

Mã định danh là chuỗi#

Mọi mã định danh trong xStore — sản phẩm, phiên bản, danh mục, đơn hàng, địa chỉ, đánh giá… — đều là chuỗi 10 ký tự (chữ thường và số), không phải số:

"k3n8fq2wla"      // đúng
1234              // sai

Vì vậy đừng ép kiểu số ở bất kỳ đâu trong giao diện:

// SAI — mã sẽ thành NaN
await xStore.cart.addItem({ variant_id: Number(el.dataset.variant), quantity: 1 });

// ĐÚNG — giữ nguyên chuỗi
await xStore.cart.addItem({ variant_id: el.dataset.variant, quantity: 1 });

Giá trị lấy từ dataset, value của thẻ <select>/<input> hay từ biến Liquid đều đã là chuỗi, nên chỉ cần truyền thẳng.

Xử lý lỗi#

Khi máy chủ trả về lỗi, thư viện ném ra XstoreError với status (mã HTTP) và message (thông báo từ máy chủ):

<script>
  try {
    await xStore.cart.addItem({ variant_id: variantId, quantity: 1 });
  } catch (e) {
    if (e.status === 401) {
      window.location.href = '/dang-nhap?next=' + encodeURIComponent(location.pathname);
    } else {
      alert(e.message);
    }
  }
</script>

Luôn bọc lời gọi trong try/catch. Lỗi hay gặp: 401 (cần đăng nhập), 404 (không còn tồn tại), 409 (hết hàng), 429 (thao tác quá nhanh).

Lắng nghe sự kiện#

<script>
  xStore.on('cart:updated', (cart) => {
    document.getElementById('cart-badge').textContent = cart.item_count;
  });
</script>

Huỷ đăng ký bằng xStore.off(tên_sự_kiện, hàm).

Giỏ hàng của khách vãng lai#

Khách chưa đăng nhập vẫn có giỏ riêng, định danh bằng một mã lưu trong trình duyệt. Khi khách đăng nhập, thư viện tự gộp giỏ vãng lai vào tài khoản — giao diện không cần làm gì thêm.

Tham chiếu đầy đủ#

Mỗi module có trang riêng, kèm một ví dụ đầy đủ chạy được — chép vào theme.html hoặc vào tệp giao diện của trang là dùng được ngay.