@ableco/overpass 中文文档教程

Question

Overpass

JSON:API 端点和 React 组件之间基于 Redux 的钩子驱动的桥梁。

Installation

Using npm

npm install @ableco/overpass

Using yarn

yarn add @ableco/overpass

Getting started

要映射应用程序的 JSON:API 资源，请使用 defineResources 定义一个 resources 对象：

import { defineResources } from "@ableco/overpass";

const resources = defineResources(({ resource }) => {
  resource("categories");
  resource("products");
  resource("orders");
  resource("items");
});

然后，使用 包装您的应用程序成分。 它将允许您在应用程序中跨组件使用 Overpass。

接受一些道具，稍后您将看到。 使用 resources 属性让 Overpass 知道如何存储您的资源：

import { defineResources } from "@ableco/overpass";

const resources = defineResources(({ resource }) => {
  resource("categories");
  resource("products");
  resource("orders");
  resource("items");
});

<OverpassProvider
  api={{
    apiPrefix: "/api",
  }}
  resources={resources}
>
  {/* your app */}
</OverpassProvider>

Usage

Fetching data

有两种方法可以在 Overpass 中获取数据。 第一个是通过获取资源集合，第二个是通过获取称为实体的单个资源。

注意：Overpass 使用 React hooks 来处理存储的资源。

要获取实体集合，您可以使用 useFetchCollection。 调用 useFetchCollection 的结果是一个可以在 useEffect 挂钩中使用的函数：

import { useFetchCollection } from "@ableco/overpass";

function CategoriesList() {
  const fetchCategories = useFetchCollection("categories");

  useEffect(() => {
    fetchCategories();
  }, []);

  return <div>{/* your component */}</div>;
}

要获取单个实体，您可以使用 useFetchEntity。 与 useFetchCollection 不同，useFetchEntity 不仅接收实体的名称，还接收单个实体的 ID：

import { useFetchEntity } from "@ableco/overpass";

function Product({ id }) {
  const fetchProduct = useFetchEntity("products", id);

  useEffect(() => {
    fetchProduct();
  }, []);

  return <div>{/* your component */}</div>;
}

Using fetched data

在使用 useFetchCollection 或 useFetchEntity< 获取数据后/code>，您可以使用 useCollection 或 useEntity 处理存储的实体：您还可以使用 useFilteredCollection

const categories = useCollection("categories");
const product = useEntity("products", id);

按单个属性过滤集合或实体或 useFilteredEntity：

const categoryProducts = useFilteredCollection(
  "products",
  "categoryId",
  categoryId,
);
const mainProduct = useFilteredEntity("products", "mainProduct", true);

Mutating remotely

注意：以下挂钩将在您的后端数据库中进行更改。

Creating entities

为了创建实体，Overpass 提供了一个名为 useCreateEntity 的挂钩。

useCreateEntity 返回的函数接收一个对象，该对象具有要创建的实体的属性：

const createItem = useCreateEntity("items");

async function addProductToCart(selectedProductId) {
  await createItem({ productId: selectedProductId });
}

Updating entities

useUpdateEntity 是一个 Overpass 挂钩，它接收两个参数，资源的名称和资源的 ID要更新的实体。

useUpdateEntity 返回的函数还接收一个对象，该对象具有要更新的实体的属性：

const updateItem = useUpdateEntity("items", itemId);

async function updateCartItem(quantity) {
  await updateItem({ quantity: quantity });
};

Deleting entities

useDeleteEntity 允许您删除实体。 useDeleteEntity 返回的函数接收要删除的实体的 ID：

const deleteItem = useDeleteEntity("items");

async function removeCartItem(itemId) {
  await deleteItem(itemId);
};

Testing

在终端中运行以下命令：

npm run test

如果您使用的是 yarn，则运行另一个命令：

yarn test

Contributing

欢迎贡献。 请查看贡献指南，了解您需要遵循的指南。

请阅读我们的行为准则，以便您了解我们期望所有参与者表现出的尊重行为。

License

Overpass 在 MIT 许可证下发布。 请参阅 LICENSE 以获取完整的许可文本。