JavaScript SDK

Strapi JavaScript SDK 简化了与 Strapi 后端的交互，提供了一种直观的方式来获取、创建、更新和删除内容。本指南将引导你设置 SDK、配置身份验证以及有效使用其主要功能。

¥The Strapi JavaScript SDK simplifies interactions with your Strapi backend, providing an intuitive way to fetch, create, update, and delete content. This guide walks you through setting up the SDK, configuring authentication, and using its key features effectively.

入门

¥Getting Started

Prerequisites

在使用 Strapi JavaScript SDK 之前，请确保你具有以下内容：

¥Before using the Strapi JavaScript SDK, ensure you have the following:

• Strapi 后端已启动并运行。如果你尚未设置，请按照快速入门指南开始使用。

  ¥a Strapi backend up and running. If you haven't set one up yet, follow the quick start guide to get started.

• 你的 Strapi 实例的 API URL（通常遵循以下格式：http://localhost:1337/api）。

  ¥the API URL of your Strapi instance (typically follows the format: http://localhost:1337/api).

• 系统上安装了最新版本的 Node.js。

  ¥a recent version of Node.js installed on your system.

安装

¥Installation

要在你的项目中使用 SDK，请使用你首选的包管理器将其作为依赖安装：

¥To use the SDK in your project, install it as a dependency using your preferred package manager:

Yarn

yarn add @strapi/sdk-js

NPM

npm install @strapi/sdk-js

pnpm

  pnpm add @strapi/sdk-js

基本配置

¥Basic Configuration

要开始与你的 Strapi 后端交互，请初始化 SDK 并设置基本 API URL：

¥To start interacting with your Strapi backend, initialize the SDK and set the base API URL:

import { strapi } from '@strapi/sdk-js';



const sdk = strapi({ baseURL: 'http://localhost:1337/api' });

如果你在浏览器环境中使用 SDK，则可以使用 <script> 标记将其包含在内：

¥If you're using the SDK in a browser environment, you can include it using a <script> tag:

./src/api/[apiName]/routes/[routerName].ts (e.g './src/api/restaurant/routes/restaurant.ts')

<script src="https://cdn.jsdelivr.net/npm/@strapi/sdk-js"></script>

<script>
  const sdk = strapi.strapi({ baseURL: 'http://localhost:1337/api' });
</script>

验证

¥Authentication

SDK 支持不同的身份验证策略来访问 Strapi 后端中受保护的资源。

¥The SDK supports different authentication strategies to access protected resources in your Strapi backend.

API 令牌认证

¥API Token Authentication

如果你的 Strapi 实例使用 API 令牌，请按如下方式配置 SDK：

¥If your Strapi instance uses API tokens, configure the SDK as follows:

const sdk = strapi({


  baseURL: 'http://localhost:1337/api',
  auth: 'your-api-token-here',
});

这允许你的请求自动包含必要的身份验证凭据。

¥This allows your requests to include the necessary authentication credentials automatically.

API 参考

¥API Reference

Strapi SDK 实例提供了几个与 Strapi 后端交互的关键属性和方法：

¥The Strapi SDK instance provides several key properties and methods for interacting with your Strapi backend:

核心属性

¥Core Properties

范围	描述
baseURL	Strapi 后端的基本 API URL。
fetch()	一种用于发出类似于原生获取 API 的通用 API 请求的实用方法。
collection()	管理集合类型资源（例如，博客文章、产品）。
single()	管理单一类型资源（例如，主页设置、全局配置）。

通用获取

¥General purpose fetch

SDK 提供对底层 JavaScript 获取函数的访问，以进行直接 API 请求。请求始终与 SDK 初始化期间提供的基本 URL 相关。

¥The SDK provides access to the underlying JavaScript fetch function for making direct API requests. The request is always relative to the base URL provided during SDK initialization.

const result = await strapiSdk.fetch('articles', { method: 'GET' });

使用集合类型

¥Working with Collection-Types

Strapi 中的集合类型资源是具有多个条目的实体（例如，包含许多帖子的博客）。SDK 提供了一个 .collection() 方法来与这些资源交互。

¥Collection-type resources in Strapi are entities with multiple entries (e.g., a blog with many posts). The SDK provides a .collection() method to interact with these resources.

可用方法：

¥Available methods:

范围	描述
find(queryParams?)	使用可选的过滤、排序或分页获取多个文档
findOne(documentID, queryParams?)	通过其唯一 ID 检索单个文档。
create(data, queryParams?)	在集合中创建一个新文档。
update(documentID, data, queryParams?)	更新现有文档。
delete(documentID, queryParams?)	更新现有文档。

使用示例：

¥Usage examples:

const articles = sdk.collection('articles');



// Fetch all English articles sorted by title


const allArticles = await articles.find({ locale: 'en', sort: 'title' });



// Fetch a single article by ID


const singleArticle = await articles.findOne('article-document-id');



// Create a new article


const newArticle = await articles.create({ title: 'New Article', content: '...' });



// Update an existing article


const updatedArticle = await articles.update('article-document-id', { title: 'Updated Title' });



// Delete an article
await articles.delete('article-id');

使用单一类型

¥Working with Single-Types

Strapi 中的单一类型资源表示仅存在一次的唯一内容条目（例如，主页设置或站点范围的配置）。SDK 提供了一个 .single() 方法来与这些资源交互。

¥Single-type resources in Strapi represent unique content entries that exist only once (e.g., the homepage settings or site-wide configurations). The SDK provides a .single() method to interact with these resources.

可用方法：

¥Available methods:

范围	描述
find(queryParams?)	获取文档。
update(documentID, data, queryParams?)	更新文档。
delete(queryParams?)	删除文档。

使用示例：

¥Usage examples:

const homepage = sdk.single('homepage');



// Fetch the default homepage content


const defaultHomepage = await homepage.find();



// Fetch the Spanish version of the homepage


const spanishHomepage = await homepage.find({ locale: 'es' });



// Update the homepage draft content


const updatedHomepage = await homepage.update(


  { title: 'Updated Homepage Title' },
  { status: 'draft' }
);

// Delete the homepage content
await homepage.delete();