Shopify JavaScript Buy SDK

JS Buy SDK 是一个轻量级库，可让您在任何网站中构建电子商务功能。它基于 Shopify 的 Storefront API，并提供从您的商店检索产品和系列、将产品添加到购物车以及结账的功能。

更新日志

查看我们的更新日志，了解有关我们发布的详细信息。

SDK 版本支持

JS Buy SDK 的每个版本都使用特定的 Storefront API 版本，并且 SDK 版本的支持与相应 Storefront API 版本的支持直接相关。Storefront API 版本信息可以在此处找到。

安装

使用 Yarn

$ yarn add shopify-buy

使用 NPM

$ npm install shopify-buy

CDN

最新版本的缩减 UMD 构建版本可通过 CDN 获取（有关最新版本的详细信息，请参阅更新日志）

<script src="https://sdks.shopifycdn.com/js-buy-sdk/v2/latest/index.umd.min.js"></script>

如果您不想使用最新版本，可以使用特定的旧版本

<script src="https://sdks.shopifycdn.com/js-buy-sdk/1.11.0/index.umd.min.js"></script>

您还可以获取版本的未优化版本（2.0.1 及更高版本）。这将比优化版本大，因为它将包含 Storefront API 中可用的所有字段

<script src="https://sdks.shopifycdn.com/js-buy-sdk/2.0.1/index.unoptimized.umd.min.js"></script>

构建

JS Buy SDK 有四个构建版本：ES、CommonJS、AMD 和 UMD。

ES，CommonJS

import Client from 'shopify-buy';

AMD

import Client from 'shopify-buy/index.amd';

UMD

import Client from 'shopify-buy/index.umd';

UMD 未优化：这将比优化版本大，因为它将包含 Storefront API 中可用的所有字段。只有当您需要添加自定义查询以补充 JS Buy SDK 查询时才应使用此版本。

import Client from 'shopify-buy/index.unoptimized.umd';

示例

初始化客户端

如果您的商店支持多种语言，Storefront API 可以返回已翻译的资源类型和字段。了解有关翻译内容的更多信息。

import Client from 'shopify-buy';

// Initializing a client to return content in the store's primary language
const client = Client.buildClient({
  domain: 'your-shop-name.myshopify.com',
  storefrontAccessToken: 'your-storefront-access-token'
});

// Initializing a client to return translated content
const clientWithTranslatedContent = Client.buildClient({
  domain: 'your-shop-name.myshopify.com',
  storefrontAccessToken: 'your-storefront-access-token',
  language: 'ja-JP'
});

获取产品

// Fetch all products in your shop
client.product.fetchAll().then((products) => {
  // Do something with the products
  console.log(products);
});

// Fetch a single product by ID
const productId = 'gid://shopify/Product/7857989384';

client.product.fetch(productId).then((product) => {
  // Do something with the product
  console.log(product);
});

// Fetch a single product by Handle
const handle = 'product-handle';

client.product.fetchByHandle(handle).then((product) => {
  // Do something with the product
  console.log(product);
});

获取系列

// Fetch all collections, including their products
client.collection.fetchAllWithProducts().then((collections) => {
  // Do something with the collections
  console.log(collections);
  console.log(collections[0].products);
});

// Fetch a single collection by ID, including its products
const collectionId = 'gid://shopify/Collection/369312584';
// Set a parameter for first x products, defaults to 20 if you don't provide a param

client.collection.fetchWithProducts(collectionId, {productsFirst: 10}).then((collection) => {
  // Do something with the collection
  console.log(collection);
  console.log(collection.products);
});

创建结账

// Create an empty checkout
client.checkout.create().then((checkout) => {
  // Do something with the checkout
  console.log(checkout);
});

更新结账属性

const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8';
const input = {customAttributes: [{key: "MyKey", value: "MyValue"}]};

client.checkout.updateAttributes(checkoutId, input).then((checkout) => {
  // Do something with the updated checkout
});

添加行项目

const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
const lineItemsToAdd = [
  {
    variantId: 'gid://shopify/ProductVariant/29106064584',
    quantity: 5,
    customAttributes: [{key: "MyKey", value: "MyValue"}]
  }
];

// Add an item to the checkout
client.checkout.addLineItems(checkoutId, lineItemsToAdd).then((checkout) => {
  // Do something with the updated checkout
  console.log(checkout.lineItems); // Array with one additional line item
});

更新行项目

const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
const lineItemsToUpdate = [
  {id: 'gid://shopify/CheckoutLineItem/194677729198640?checkout=e3bd71f7248c806f33725a53e33931ef', quantity: 2}
];

// Update the line item on the checkout (change the quantity or variant)
client.checkout.updateLineItems(checkoutId, lineItemsToUpdate).then((checkout) => {
  // Do something with the updated checkout
  console.log(checkout.lineItems); // Quantity of line item 'gid://shopify/Product/7857989384' updated to 2
});

删除行项目

const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
const lineItemIdsToRemove = [
  'gid://shopify/CheckoutLineItem/194677729198640?checkout=e3bd71f7248c806f33725a53e33931ef'
];

// Remove an item from the checkout
client.checkout.removeLineItems(checkoutId, lineItemIdsToRemove).then((checkout) => {
  // Do something with the updated checkout
  console.log(checkout.lineItems); // Checkout with line item 'gid://shopify/CheckoutLineItem/194677729198640?checkout=e3bd71f7248c806f33725a53e33931ef' removed
});

获取结账

const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'

client.checkout.fetch(checkoutId).then((checkout) => {
  // Do something with the checkout
  console.log(checkout);
});

添加折扣

const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout
const discountCode = 'best-discount-ever';

// Add a discount code to the checkout
client.checkout.addDiscount(checkoutId, discountCode).then(checkout => {
  // Do something with the updated checkout
  console.log(checkout);
});

删除折扣

const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout

// Removes the applied discount from an existing checkout.
client.checkout.removeDiscount(checkoutId).then(checkout => {
  // Do something with the updated checkout
  console.log(checkout);
});

更新送货地址

const checkoutId = 'gid://shopify/Checkout/e3bd71f7248c806f33725a53e33931ef?key=47092e448529068d1be52e5051603af8'; // ID of an existing checkout

const shippingAddress = {
   address1: 'Chestnut Street 92',
   address2: 'Apartment 2',
   city: 'Louisville',
   company: null,
   country: 'United States',
   firstName: 'Bob',
   lastName: 'Norman',
   phone: '555-625-1199',
   province: 'Kentucky',
   zip: '40202'
 };

// Update the shipping address for an existing checkout.
client.checkout.updateShippingAddress(checkoutId, shippingAddress).then(checkout => {
  // Do something with the updated checkout
});

完成结账

完成结账的最简单方法是使用创建结账时返回的 webUrl 属性。此 URL 会将客户重定向到 Shopify 的在线结账以完成购买。

扩展 SDK

并非 Storefront API 上可用的所有字段都通过 SDK 公开。如果您使用未优化版本的 SDK，您可以轻松构建自己的查询。为此，请使用 UMD 未优化构建版本。

初始化客户端

// fetch the large, unoptimized version of the SDK
import Client from 'shopify-buy/index.unoptimized.umd';

const client = Client.buildClient({
  domain: 'your-shop-name.myshopify.com',
  storefrontAccessToken: 'your-storefront-access-token'
});

获取产品

// Build a custom products query using the unoptimized version of the SDK
const productsQuery = client.graphQLClient.query((root) => {
  root.addConnection('products', {args: {first: 10}}, (product) => {
    product.add('title');
    product.add('tags');// Add fields to be returned
  });
});

// Call the send method with the custom products query
client.graphQLClient.send(productsQuery).then(({model, data}) => {
  // Do something with the products
  console.log(model);
});

示例应用程序

有关使用 JS Buy SDK 的更完整示例，请查看我们的 storefront-api-examples 项目。在 Node、Ember 和 React 中都有 JS Buy SDK 的特定示例应用程序。您可以使用这些示例作为创建自己的自定义店面的指南。

文档

贡献

如需有关在本地设置存储库、构建、测试和贡献方面的帮助，请参阅 CONTRIBUTING.md。

行为准则

所有希望通过代码或问题做出贡献的开发者，请查看 CODE_OF_CONDUCT.md。

许可证

MIT，详情请参阅 LICENSE.md。

Shopify JavaScript Buy SDK

更新日志

SDK 版本支持

目录

安装

构建

示例

初始化客户端

获取产品

获取系列

创建结账

更新结账属性

添加行项目

更新行项目

删除行项目

获取结账

添加折扣

删除折扣

更新送货地址

完成结账

扩展 SDK

初始化客户端

获取产品

示例应用程序

文档

贡献

行为准则

许可证