Remix 工具

此包包含一些简单的实用工具函数，用于 React Router。

安装

npm install remix-utils

可能需要其他可选依赖项，所有可选依赖项为

react-router
@oslojs/crypto
@oslojs/encoding
is-ip
intl-parse-accept-language
react
zod

需要额外可选依赖项的工具会在其文档中提及。

如果要安装所有依赖项，请运行

npm add @oslojs/crypto @oslojs/encoding is-ip intl-parse-accept-language zod

React 和 React Router 包应该已经安装在您的项目中。

从 Remix Utils v6 升级

查看 v6 到 v7 的升级指南。

API 参考

promiseHash

promiseHash 函数与 Remix 没有直接关系，但它是在处理加载器和操作时很有用的函数。

此函数是 Promise.all 的对象版本，允许您传递带有 promise 的对象，并获取具有相同键的已解析值的对象。

import { promiseHash } from "remix-utils/promise";

export async function loader({ request }: LoaderFunctionArgs) {
  return json(
    await promiseHash({
      user: getUser(request),
      posts: getPosts(request),
    })
  );
}

您可以使用嵌套的 promiseHash 来获取带有已解析值的嵌套对象。

import { promiseHash } from "remix-utils/promise";

export async function loader({ request }: LoaderFunctionArgs) {
  return json(
    await promiseHash({
      user: getUser(request),
      posts: promiseHash({
        list: getPosts(request),
        comments: promiseHash({
          list: getComments(request),
          likes: getLikes(request),
        }),
      }),
    })
  );
}

timeout

timeout 函数允许您为任何 promise 添加超时，如果 promise 在超时之前没有 resolve 或 reject，它将使用 TimeoutError reject。

import { timeout } from "remix-utils/promise";

try {
  let result = await timeout(fetch("https://example.com"), { ms: 100 });
} catch (error) {
  if (error instanceof TimeoutError) {
    // Handle timeout
  }
}

在这里，fetch 需要在少于 100 毫秒内发生，否则将抛出 TimeoutError。

如果 promise 可使用 AbortSignal 取消，则可以将 AbortController 传递给 timeout 函数。

import { timeout } from "remix-utils/promise";

try {
  let controller = new AbortController();
  let result = await timeout(
    fetch("https://example.com", { signal: controller.signal }),
    { ms: 100, controller }
  );
} catch (error) {
  if (error instanceof TimeoutError) {
    // Handle timeout
  }
}

在这里，100 毫秒后，timeout 将调用 controller.abort()，这将把 controller.signal 标记为已中止。

cacheAssets

注意这只能在 entry.client 内部运行。

此函数允许您轻松地在浏览器的缓存存储中缓存 Remix 构建的每个 JS 文件。

要使用它，请打开您的 entry.client 文件并添加此内容

import { cacheAssets } from "remix-utils/cache-assets";

cacheAssets().catch((error) => {
  // do something with the error, or not
});

该函数接收一个带有两个可选选项的 options 对象

cacheName 是要使用的 Cache 对象的名称，默认值为 assets。
buildPath 是所有 Remix 构建资产的路径名前缀，默认值为 /build/，它是 Remix 本身的默认构建路径。

重要的是，如果您在 remix.config.js 中更改了构建路径，请将相同的值传递给 cacheAssets，否则它将找不到您的 JS 文件。

除非您向应用程序添加 Service Worker 并想共享缓存，否则 cacheName 可以保持原样。

import { cacheAssets } from "remix-utils/cache-assets";

cacheAssests({ cacheName: "assets", buildPath: "/build/" }).catch((error) => {
  // do something with the error, or not
});

ClientOnly

注意这取决于 react。

ClientOnly 组件允许您仅在客户端渲染子元素，避免在服务器端渲染它。

您可以提供一个在 SSR 上使用的回退组件，虽然是可选的，但强烈建议提供一个，以避免内容布局偏移问题。

import { ClientOnly } from "remix-utils/client-only";

export default function Component() {
  return (
    <ClientOnly fallback={<SimplerStaticVersion />}>
      {() => <ComplexComponentNeedingBrowserEnvironment />}
    </ClientOnly>
  );
}

当您有一些需要浏览器环境才能工作的复杂组件（例如图表或地图）时，此组件非常方便。这样，您可以避免在服务器端渲染它，而是使用更简单的静态版本，例如 SVG 甚至是加载 UI。

渲染流程将是

SSR：始终渲染回退。
CSR 首次渲染：始终渲染回退。
CSR 更新：更新以渲染实际组件。
CSR 未来渲染：始终渲染实际组件，无需渲染回退。

此组件在内部使用 useHydrated 钩子。

ServerOnly

注意这取决于 react。

ServerOnly 组件与 ClientOnly 组件相反，它允许您仅在服务器端渲染子元素，避免在客户端渲染它。

您可以提供一个在 CSR 上使用的回退组件，虽然是可选的，但强烈建议提供一个，以避免内容布局偏移问题，除非您只渲染视觉上隐藏的元素。

import { ServerOnly } from "remix-utils/server-only";

export default function Component() {
  return (
    <ServerOnly fallback={<ComplexComponentNeedingBrowserEnvironment />}>
      {() => <SimplerStaticVersion />}
    </ServerOnly>
  );
}

此组件对于仅在服务器端渲染某些内容非常方便，例如可以稍后用来知道 JS 是否已加载的隐藏输入。

可以将其视为 <noscript> HTML 标签，但即使 JS 未能加载，但浏览器上启用了 JS，它也可以工作。

渲染流程将是

SSR：始终渲染子元素。
CSR 首次渲染：始终渲染子元素。
CSR 更新：更新以渲染回退组件（如果已定义）。
CSR 未来渲染：始终渲染回退组件，无需渲染子元素。

此组件在内部使用 useHydrated 钩子。

CORS

CORS 函数允许您在加载器和操作中实现 CORS 标头，以便您可以将它们用作其他客户端应用程序的 API。

使用 cors 函数有两种主要方法。

在您要启用它的每个加载器/操作中使用它。
在 entry.server handleRequest 和 handleDataRequest 导出中全局使用它。

如果要在每个加载器/操作中使用它，可以这样做

import { cors } from "remix-utils/cors";

export async function loader({ request }: LoaderFunctionArgs) {
  let data = await getData(request);
  let response = json<LoaderData>(data);
  return await cors(request, response);
}

您也可以在一行中执行 json 和 cors 调用。

import { cors } from "remix-utils/cors";

export async function loader({ request }: LoaderFunctionArgs) {
  let data = await getData(request);
  return await cors(request, json<LoaderData>(data));
}

并且由于 cors 会改变响应，因此您也可以调用它，然后再返回。

import { cors } from "remix-utils/cors";

export async function loader({ request }: LoaderFunctionArgs) {
  let data = await getData(request);
  let response = json<LoaderData>(data);
  await cors(request, response); // this mutates the Response object
  return response; // so you can return it here
}

如果要全局设置一次，可以在 entry.server 中这样做

import { cors } from "remix-utils/cors";

const ABORT_DELAY = 5000;

export default function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  remixContext: EntryContext
) {
  let callbackName = isbot(request.headers.get("user-agent"))
    ? "onAllReady"
    : "onShellReady";

  return new Promise((resolve, reject) => {
    let didError = false;

    let { pipe, abort } = renderToPipeableStream(
      <RemixServer context={remixContext} url={request.url} />,
      {
        [callbackName]: () => {
          let body = new PassThrough();

          responseHeaders.set("Content-Type", "text/html");

          cors(
            request,
            new Response(body, {
              headers: responseHeaders,
              status: didError ? 500 : responseStatusCode,
            })
          ).then((response) => {
            resolve(response);
          });

          pipe(body);
        },
        onShellError: (err: unknown) => {
          reject(err);
        },
        onError: (error: unknown) => {
          didError = true;

          console.error(error);
        },
      }
    );

    setTimeout(abort, ABORT_DELAY);
  });
}

export let handleDataRequest: HandleDataRequestFunction = async (
  response,
  { request }
) => {
  return await cors(request, response);
};

选项

此外，cors 函数接受一个 options 对象作为第三个可选参数。这些是选项。

origin：配置 Access-Control-Allow-Origin CORS 标头。可能的值为
- true：为任何来源启用 CORS（与“*”相同）
- false：不设置 CORS
- string：设置为特定来源，如果设置为“*”，则允许任何来源
- RegExp：设置为与来源匹配的 RegExp
- Array<string | RegExp>：设置为要与字符串或 RegExp 匹配的来源数组
- Function：设置为一个函数，该函数将使用请求来源调用，并应返回一个布尔值，指示是否允许该来源。默认值为 true。
methods：配置 Access-Control-Allow-Methods CORS 标头。默认值为 ["GET", "HEAD", "PUT", "PATCH", "POST", "DELETE"]。
allowedHeaders：配置 Access-Control-Allow-Headers CORS 标头。
exposedHeaders：配置 Access-Control-Expose-Headers CORS 标头。
credentials：配置 Access-Control-Allow-Credentials CORS 标头。
maxAge：配置 Access-Control-Max-Age CORS 标头。

CSRF

注意这取决于 react、@oslojs/crypto、@oslojs/encoding 和 React Router。

CSRF 相关函数允许您在应用程序上实现 CSRF 保护。

Remix Utils 的这部分需要 React 和服务器端代码。

首先创建一个新的 CSRF 实例。

// app/utils/csrf.server.ts
import { CSRF } from "remix-utils/csrf/server";
import { createCookie } from "react-router"; // or cloudflare/deno

export const cookie = createCookie("csrf", {
  path: "/",
  httpOnly: true,
  secure: process.env.NODE_ENV === "production",
  sameSite: "lax",
  secrets: ["s3cr3t"],
});

export const csrf = new CSRF({
  cookie,
  // what key in FormData objects will be used for the token, defaults to `csrf`
  formDataKey: "csrf",
  // an optional secret used to sign the token, recommended for extra safety
  secret: "s3cr3t",
});

然后您可以使用 csrf 生成新令牌。

import { csrf } from "~/utils/csrf.server";

export async function loader({ request }: LoaderFunctionArgs) {
  let token = csrf.generate();
}

您可以通过传递字节大小来自定义令牌大小，默认值为 32 字节，这将在编码后为您提供一个长度为 43 的字符串。

let token = csrf.generate(64); // customize token length

您需要将此令牌保存在 cookie 中，并从加载器返回它。为方便起见，您可以使用 CSRF#commitToken 助手。

import { csrf } from "~/utils/csrf.server";

export async function loader({ request }: LoaderFunctionArgs) {
  let [token, cookieHeader] = await csrf.commitToken();
  return json({ token }, { headers: { "set-cookie": cookieHeader } });
}

注意您可以在任何路由上执行此操作，但我建议您在 root 加载器上执行此操作。

现在您已经返回了令牌并将其设置在 cookie 中，您可以使用 AuthenticityTokenProvider 组件将令牌提供给您的 React 组件。

import { AuthenticityTokenProvider } from "remix-utils/csrf/react";

let { csrf } = useLoaderData<LoaderData>();
return (
  <AuthenticityTokenProvider token={csrf}>
    <Outlet />
  </AuthenticityTokenProvider>
);

在您的 root 组件中渲染它，并使用它包装 Outlet。

当您在某个路由中创建表单时，可以使用 AuthenticityTokenInput 组件将身份验证令牌添加到表单。

import { Form } from "react-router";
import { AuthenticityTokenInput } from "remix-utils/csrf/react";

export default function Component() {
  return (
    <Form method="post">
      <AuthenticityTokenInput />
      <input type="text" name="something" />
    </Form>
  );
}

请注意，身份验证令牌仅对以某种方式更改数据的表单真正需要。如果您有一个发出 GET 请求的搜索表单，则无需在此处添加身份验证令牌。

此 AuthenticityTokenInput 将从 AuthenticityTokenProvider 组件获取身份验证令牌，并将其作为名称为 csrf 的隐藏输入的值添加到表单。您可以使用 name 属性自定义字段名称。

<AuthenticityTokenInput name="customName" />

如果您还在 createAuthenticityToken 上更改了名称，则应仅自定义名称。

如果你需要使用 useFetcher (或 useSubmit) 而不是 Form，你也可以使用 useAuthenticityToken 钩子来获取 CSRF 令牌。

import { useFetcher } from "react-router";
import { useAuthenticityToken } from "remix-utils/csrf/react";

export function useMarkAsRead() {
  let fetcher = useFetcher();
  let csrf = useAuthenticityToken();
  return function submit(data) {
    fetcher.submit(
      { csrf, ...data },
      { action: "/api/mark-as-read", method: "post" }
    );
  };
}

最后，你需要在接收到请求的 action 中验证 CSRF 令牌。

import { CSRFError } from "remix-utils/csrf/server";
import { redirectBack } from "remix-utils/redirect-back";
import { csrf } from "~/utils/csrf.server";

export async function action({ request }: ActionFunctionArgs) {
  try {
    await csrf.validate(request);
  } catch (error) {
    if (error instanceof CSRFError) {
      // handle CSRF errors
    }
    // handle other possible errors
  }

  // here you know the request is valid
  return redirectBack(request, { fallback: "/fallback" });
}

如果你需要自己解析请求体为 FormData（例如，为了支持文件上传），你也可以使用 FormData 和 Headers 对象调用 CSRF#validate。

let formData = await parseMultiPartFormData(request);
try {
  await csrf.validate(formData, request.headers);
} catch (error) {
  // handle errors
}

警告如果你使用请求实例调用 CSRF#validate，但你已经读取了它的请求体，则会抛出一个错误。

如果 CSRF 验证失败，它将抛出一个 CSRFError，该错误可用于正确识别它与可能抛出的其他错误。

可能的错误消息列表如下：

missing_token_in_cookie：请求的 cookie 中缺少 CSRF 令牌。
invalid_token_in_cookie：CSRF 令牌无效（不是字符串）。
tampered_token_in_cookie：CSRF 令牌与签名不匹配。
missing_token_in_body：请求的请求体 (FormData) 中缺少 CSRF 令牌。
mismatched_token：cookie 中的 CSRF 令牌与请求体中的不匹配。

你可以使用 error.code 来检查上述的错误代码之一，并使用 error.message 来获取用户友好的描述。

警告不要将这些错误消息发送给最终用户，它们仅用于调试目的。

现有搜索参数

import { ExistingSearchParams } from "remix-utils/existing-search-params";

注意这取决于 react 和 react-router。

当你提交一个 GET 表单时，浏览器会将 URL 中的所有搜索参数替换为你的表单数据。此组件会将现有的搜索参数复制到隐藏的输入中，以便它们不会被覆盖。

exclude 属性接受一个要从隐藏输入中排除的搜索参数数组。

将此表单处理的参数添加到此列表中。
添加要提交时清除的其他表单的参数。

例如，想象一个包含用于分页、筛选和搜索的独立表单组件的数据表。更改页码不应影响搜索或筛选参数。

<Form>
  <ExistingSearchParams exclude={["page"]} />
  <button type="submit" name="page" value="1">
    1
  </button>
  <button type="submit" name="page" value="2">
    2
  </button>
  <button type="submit" name="page" value="3">
    3
  </button>
</Form>

通过从搜索表单中排除 page 参数，用户将返回到搜索结果的第一页。

<Form>
  <ExistingSearchParams exclude={["q", "page"]} />
  <input type="search" name="q" />
  <button type="submit">Search</button>
</Form>

外部脚本

注意这取决于 react 和 react-router。

如果你需要在特定路由上加载不同的外部脚本，你可以将 ExternalScripts 组件与 ExternalScriptsFunction 和 ScriptDescriptor 类型一起使用。

在你想要加载脚本的路由中，添加一个带有 scripts 方法的 handle 导出，并将 handle 的类型设置为 ExternalScriptsHandle。此接口允许你将 scripts 定义为函数或数组。

如果你想根据加载器数据定义要加载哪些脚本，你可以使用 scripts 作为函数。

import { ExternalScriptsHandle } from "remix-utils/external-scripts";

type LoaderData = SerializeFrom<typeof loader>;

export let handle: ExternalScriptsHandle<LoaderData> = {
  scripts({ id, data, params, matches, location, parentsData }) {
    return [
      {
        src: "https://unpkg.com/htmx.org@1.9.6",
        integrity: "sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni",
        crossOrigin: 'anonymous"
      }
    ];
  },
};

如果要加载的脚本列表是静态的，则可以直接将 scripts 定义为数组。

import { ExternalScriptsHandle } from "remix-utils/external-scripts";

export let handle: ExternalScriptsHandle = {
  scripts: [
    {
      src: "https://unpkg.com/htmx.org@1.9.6",
      integrity: "sha384-FhXw7b6AlE/jyjlZH5iHa/tTe9EpJ1Y55RjcgPbjeWMskSxZt1v9qkxLJWNJaGni",
      crossOrigin: 'anonymous",
      preload: true, // use it to render a <link rel="preload"> for this script
    }
  ],
};

你还可以自己导入 ExternalScriptsFunction 和 ScriptDescriptor 接口来构建自定义的 handle 类型。

import {
  ExternalScriptsFunction,
  ScriptDescriptor,
} from "remix-utils/external-scripts";

interface AppHandle<LoaderData = unknown> {
  scripts?: ExternalScriptsFunction<LoaderData> | ScriptDescriptor[];
}

export let handle: AppHandle<LoaderData> = {
  scripts, // define scripts as a function or array here
};

或者你可以扩展 ExternalScriptsHandle 接口。

import { ExternalScriptsHandle } from "remix-utils/external-scripts";

interface AppHandle<LoaderData = unknown>
  extends ExternalScriptsHandle<LoaderData> {
  // more handle properties here
}

export let handle: AppHandle<LoaderData> = {
  scripts, // define scripts as a function or array here
};

然后，在根路由中，在某处添加 ExternalScripts 组件，通常你希望将其加载到 <head> 中或 <body> 的底部，可以在 Remix 的 <Scripts> 组件之前或之后。

<ExternalScripts /> 的确切位置取决于你的应用程序，但一个安全的位置是 <body> 的末尾。

import { Links, LiveReload, Meta, Scripts, ScrollRestoration } from "remix";
import { ExternalScripts } from "remix-utils/external-scripts";

type Props = { children: React.ReactNode; title?: string };

export function Document({ children, title }: Props) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width,initial-scale=1" />
        {title ? <title>{title}</title> : null}
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        <ScrollRestoration />
        <ExternalScripts />
        <Scripts />
        <LiveReload />
      </body>
    </html>
  );
}

现在，你在 ScriptsFunction 中定义的任何脚本都将添加到 HTML 中。

你可以将此实用程序与 useShouldHydrate 一起使用，以在某些路由中禁用 Remix 脚本，但仍然为分析或需要 JS 但不需要启用完整应用程序 JS 的小型功能加载脚本。

let shouldHydrate = useShouldHydrate();

return (
  <html lang="en">
    <head>
      <meta charSet="utf-8" />
      <meta name="viewport" content="width=device-width,initial-scale=1" />
      {title ? <title>{title}</title> : null}
      <Meta />
      <Links />
    </head>
    <body>
      {children}
      <ScrollRestoration />
      {shouldHydrate ? <Scripts /> : <ExternalScripts />}
      <LiveReload />
    </body>
  </html>
);

useGlobalNavigationState

注意这取决于 react 和 react-router。

此钩子允许你读取 transition.state、应用程序中的每个 fetcher.state 和 revalidator.state 的值。

import { useGlobalNavigationState } from "remix-utils/use-global-navigation-state";

export function GlobalPendingUI() {
  let states = useGlobalNavigationState();

  if (state.includes("loading")) {
    // The app is loading.
  }

  if (state.includes("submitting")) {
    // The app is submitting.
  }

  // The app is idle
}

useGlobalNavigationState 的返回值可以是 "idle"、"loading" 或 "submitting"。

注意以下钩子使用此钩子来确定应用程序是正在加载、提交还是两者都处于（挂起）状态。

useGlobalPendingState

注意这取决于 react 和 react-router。

此钩子让你知道全局导航、任何活动的 fetcher 是否正在加载或提交，或者 revalidator 是否正在运行。

import { useGlobalPendingState } from "remix-utils/use-global-navigation-state";

export function GlobalPendingUI() {
  let globalState = useGlobalPendingState();

  if (globalState === "idle") return null;
  return <Spinner />;
}

useGlobalPendingState 的返回值是 "idle" 或 "pending"。

注意：此钩子组合了 useGlobalSubmittingState 和 useGlobalLoadingState 钩子，以确定应用程序是否处于挂起状态。

注意：pending 状态是此钩子引入的 loading 和 submitting 状态的组合。

useGlobalSubmittingState

注意这取决于 react 和 react-router。

此钩子让你知道全局转换或者任何活动的 fetcher 是否正在提交。

import { useGlobalSubmittingState } from "remix-utils/use-global-navigation-state";

export function GlobalPendingUI() {
  let globalState = useGlobalSubmittingState();

  if (globalState === "idle") return null;
  return <Spinner />;
}

useGlobalSubmittingState 的返回值是 "idle" 或 "submitting"。

useGlobalLoadingState

注意这取决于 react 和 react-router。

此钩子让你知道全局转换、任何活动的 fetcher 是否正在加载，或者 revalidator 是否正在运行。

import { useGlobalLoadingState } from "remix-utils/use-global-navigation-state";

export function GlobalPendingUI() {
  let globalState = useGlobalLoadingState();

  if (globalState === "idle") return null;
  return <Spinner />;
}

useGlobalLoadingState 的返回值是 "idle" 或 "loading"。

useHydrated

注意这取决于 react。

此钩子让你检测组件是否已水合。这意味着元素的 JS 在客户端加载并且 React 正在运行。

使用 useHydrated，你可以在服务器和客户端上渲染不同的内容，同时确保水合不会出现 HTML 不匹配的情况。

import { useHydrated } from "remix-utils/use-hydrated";

export function Component() {
  let isHydrated = useHydrated();

  if (isHydrated) {
    return <ClientOnlyComponent />;
  }

  return <ServerFallback />;
}

在执行 SSR 时，isHydrated 的值将始终为 false。第一个客户端渲染的 isHydrated 仍然为 false，然后它将变为 true。

在第一次客户端渲染之后，未来渲染的调用此钩子的组件将接收 true 作为 isHydrated 的值。这样，你的服务器回退 UI 将永远不会在路由转换时渲染。

useLocales

注意这取决于 react。

此钩子让你获取根加载器返回的区域设置。它遵循一个简单的约定，你的根加载器返回值应是一个以键 locales 为键的对象。

你可以将其与 getClientLocal 组合以获取根加载器上的区域设置并返回该区域设置。 useLocales 的返回值是一个 Locales 类型，它是 string | string[] | undefined。

import { useLocales } from "remix-utils/locales/react";
import { getClientLocales } from "remix-utils/locales/server";

// in the root loader
export async function loader({ request }: LoaderFunctionArgs) {
  let locales = getClientLocales(request);
  return json({ locales });
}

// in any route (including root!)
export default function Component() {
  let locales = useLocales();
  let date = new Date();
  let dateTime = date.toISOString;
  let formattedDate = date.toLocaleDateString(locales, options);
  return <time dateTime={dateTime}>{formattedDate}</time>;
}

useLocales 的返回类型可以与 Intl API 一起使用。

useShouldHydrate

注意这取决于 react-router 和 react。

如果你正在构建一个大多数路由都是静态的 Remix 应用程序，并且你希望避免加载客户端 JS，你可以使用此钩子，再加上一些约定，来检测一个或多个活动路由是否需要 JS，并在这种情况下仅渲染 Scripts 组件。

在你的文档组件中，你可以调用此钩子以在需要时动态渲染 Scripts 组件。

import type { ReactNode } from "react";
import { Links, LiveReload, Meta, Scripts } from "react-router";
import { useShouldHydrate } from "remix-utils/use-should-hydrate";

interface DocumentProps {
  children: ReactNode;
  title?: string;
}

export function Document({ children, title }: DocumentProps) {
  let shouldHydrate = useShouldHydrate();
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <link rel="icon" href="/favicon.png" type="image/png" />
        {title ? <title>{title}</title> : null}
        <Meta />
        <Links />
      </head>
      <body>
        {children}
        {shouldHydrate && <Scripts />}
        <LiveReload />
      </body>
    </html>
  );
}

现在，你可以导出带有 hydrate 属性为 true 的 handle 对象，在任何路由模块中导出。

export let handle = { hydrate: true };

这将把路由标记为需要 JS 水合。

在某些情况下，路由可能需要基于加载器返回的数据使用 JS。例如，如果你有一个用于购买产品的组件，但只有经过身份验证的用户才能看到它，则在用户经过身份验证之前你不需要 JS。在这种情况下，你可以将 hydrate 设置为一个接收你的加载器数据的函数。

export let handle = {
  hydrate(data: LoaderData) {
    return data.user.isAuthenticated;
  },
};

useShouldHydrate 钩子将检测 hydrate 是否为函数，并使用路由数据调用它。

getClientIPAddress

注意这取决于 is-ip。

此函数接收 Request 或 Headers 对象，并将尝试获取发起请求的客户端（用户）的 IP 地址。

import { getClientIPAddress } from "remix-utils/get-client-ip-address";

export async function loader({ request }: LoaderFunctionArgs) {
  // using the request
  let ipAddress = getClientIPAddress(request);
  // or using the headers
  let ipAddress = getClientIPAddress(request.headers);
}

如果无法找到 IP 地址，则返回值将为 null。请记住在使用之前检查是否能够找到它。

该函数使用以下标头列表，按优先级顺序排列：

X-Client-IP
X-Forwarded-For
HTTP-X-Forwarded-For
Fly-Client-IP
CF-Connecting-IP
Fastly-Client-Ip
True-Client-Ip
X-Real-IP
X-Cluster-Client-IP
X-Forwarded
Forwarded-For
Forwarded
DO-Connecting-IP
oxygen-buyer-ip

当找到包含有效 IP 地址的标头时，它将返回而不检查其他标头。

警告在本地开发中，该函数最有可能返回 null。这是因为浏览器不会发送任何上述标头，如果你想模拟这些标头，你需要将其添加到 Remix 在 HTTP 服务器中接收的请求中，或者运行一个可以为你添加它们的反向代理（如 NGINX）。

getClientLocales

注意这取决于 intl-parse-accept-language。

此函数让你获取发起请求的客户端（用户）的区域设置。

import { getClientLocales } from "remix-utils/locales/server";

export async function loader({ request }: LoaderFunctionArgs) {
  // using the request
  let locales = getClientLocales(request);
  // or using the headers
  let locales = getClientLocales(request.headers);
}

返回值是一个 Locales 类型，即 string | string[] | undefined。

返回的区域设置可以直接在格式化日期、数字等的 Intl API 上使用。

import { getClientLocales } from "remix-utils/locales/server";
export async function loader({ request }: LoaderFunctionArgs) {
  let locales = getClientLocales(request);
  let nowDate = new Date();
  let formatter = new Intl.DateTimeFormat(locales, {
    year: "numeric",
    month: "long",
    day: "numeric",
  });
  return json({ now: formatter.format(nowDate) });
}

该值也可以由加载器返回并在 UI 上使用，以确保在服务器和客户端格式化的日期上都使用用户的区域设置。

isPrefetch

此函数让你识别请求是否是由于使用 <Link prefetch="intent"> 或 <Link prefetch="render"> 触发的预取而创建的。

这将让你仅为预取请求实现短缓存，以便你避免双重数据请求。

import { isPrefetch } from "remix-utils/is-prefetch";

export async function loader({ request }: LoaderFunctionArgs) {
  let data = await getData(request);
  let headers = new Headers();

  if (isPrefetch(request)) {
    headers.set("Cache-Control", "private, max-age=5, smax-age=0");
  }

  return json(data, { headers });
}

响应

重定向返回

此函数是 Remix 中 redirect 辅助函数的包装器。与 Remix 的版本不同，此版本接收整个请求对象作为第一个值，以及一个带有响应初始化和一个回退 URL 的对象。

使用此函数创建的响应将使 Location 标头指向请求中的 Referer 标头，如果不可用，则指向第二个参数中提供的回退 URL。

import { redirectBack } from "remix-utils/redirect-back";

export async function action({ request }: ActionFunctionArgs) {
  throw redirectBack(request, { fallback: "/" });
}

此辅助函数在通用 action 中用于将用户发送到之前所在的 URL 时最有用。

未修改

辅助函数，用于创建没有主体和任何标头的未修改 (304) 响应。

import { notModified } from "remix-utils/responses";

export async function loader({ request }: LoaderFunctionArgs) {
  return notModified();
}

JavaScript

辅助函数，用于创建带有任何标头的 JavaScript 文件响应。

这在基于资源路由中的数据创建 JS 文件时很有用。

import { javascript } from "remix-utils/responses";

export async function loader({ request }: LoaderFunctionArgs) {
  return javascript("console.log('Hello World')");
}

样式表

辅助函数，用于创建带有任何标头的 CSS 文件响应。

这在基于资源路由中的数据创建 CSS 文件时很有用。

import { stylesheet } from "remix-utils/responses";

export async function loader({ request }: LoaderFunctionArgs) {
  return stylesheet("body { color: red; }");
}

PDF

辅助函数，用于创建带有任何标头的 PDF 文件响应。

这在基于资源路由中的数据创建 PDF 文件时很有用。

import { pdf } from "remix-utils/responses";

export async function loader({ request }: LoaderFunctionArgs) {
  return pdf(await generatePDF(request.formData()));
}

HTML

辅助函数，用于创建带有任何标头的 HTML 文件响应。

这在基于资源路由中的数据创建 HTML 文件时很有用。

import { html } from "remix-utils/responses";

export async function loader({ request }: LoaderFunctionArgs) {
  return html("<h1>Hello World</h1>");
}

XML

辅助函数，用于创建带有任何标头的 XML 文件响应。

这在基于资源路由中的数据创建 XML 文件时非常有用。

import { xml } from "remix-utils/responses";

export async function loader({ request }: LoaderFunctionArgs) {
  return xml("<?xml version='1.0'?><catalog></catalog>");
}

纯文本

辅助函数，用于创建带有任何标头的 TXT 文件响应。

这在基于资源路由中的数据创建 TXT 文件时非常有用。

import { txt } from "remix-utils/responses";

export async function loader({ request }: LoaderFunctionArgs) {
  return txt(`
    User-agent: *
    Allow: /
  `);
}

类型化 Cookies

注意这依赖于 zod 和 React Router。

Remix 中的 Cookie 对象允许任何类型，Remix Utils 中的类型化 cookie 允许您使用 Zod 解析 cookie 值并确保它们符合模式。

import { createCookie } from "react-router";
import { createTypedCookie } from "remix-utils/typed-cookie";
import { z } from "zod";

let cookie = createCookie("returnTo", cookieOptions);
// I recommend you to always add `nullable` to your schema, if a cookie didn't
// come with the request Cookie header Remix will return null, and it can be
// useful to remove it later when clearing the cookie
let schema = z.string().url().nullable();

// pass the cookie and the schema
let typedCookie = createTypedCookie({ cookie, schema });

// this will be a string and also a URL
let returnTo = await typedCookie.parse(request.headers.get("Cookie"));

// this will not pass the schema validation and throw a ZodError
await typedCookie.serialize("a random string that's not a URL");
// this will make TS yell because it's not a string, if you ignore it it will
// throw a ZodError
await typedCookie.serialize(123);

您还可以将类型化 cookie 与 Remix 的任何 sessionStorage 机制一起使用。

let cookie = createCookie("session", cookieOptions);
let schema = z.object({ token: z.string() }).nullable();

let sessionStorage = createCookieSessionStorage({
  cookie: createTypedCookie({ cookie, schema }),
});

// if this works then the correct data is stored in the session
let session = sessionStorage.getSession(request.headers.get("Cookie"));

session.unset("token"); // remove a required key from the session

// this will throw a ZodError because the session is missing the required key
await sessionStorage.commitSession(session);

现在 Zod 将确保您尝试保存到会话中的数据是有效的，删除任何额外的字段，并且如果您未在会话中设置正确的数据，则会抛出错误。

注意会话对象实际上没有类型，因此执行 session.get 不会返回正确的类型，您可以执行 schema.parse(session.data) 以获取会话数据的类型化版本。

您还可以在模式中使用异步细化，因为类型化 cookie 使用 Zod 的 parseAsync 方法。

let cookie = createCookie("session", cookieOptions);

let schema = z
  .object({
    token: z.string().refine(async (token) => {
      let user = await getUserByToken(token);
      return user !== null;
    }, "INVALID_TOKEN"),
  })
  .nullable();

let sessionTypedCookie = createTypedCookie({ cookie, schema });

// this will throw if the token stored in the cookie is not valid anymore
sessionTypedCookie.parse(request.headers.get("Cookie"));

最后，为了能够删除 cookie，您可以将 .nullable() 添加到模式中，并使用 null 作为值进行序列化。

// Set the value as null and expires as current date - 1 second so the browser expires the cookie
await typedCookie.serialize(null, { expires: new Date(Date.now() - 1) });

如果您没有将 .nullable() 添加到您的模式中，则需要提供一个模拟值并将过期日期设置为过去。

let cookie = createCookie("returnTo", cookieOptions);
let schema = z.string().url().nullable();

let typedCookie = createTypedCookie({ cookie, schema });

await typedCookie.serialize("some fake url to pass schema validation", {
  expires: new Date(Date.now() - 1),
});

类型化会话

注意这依赖于 zod 和 React Router。

Remix 中的会话对象允许任何类型，Remix Utils 中的类型化会话允许您使用 Zod 解析会话数据并确保它们符合模式。

import { createCookieSessionStorage } from "react-router";
import { createTypedSessionStorage } from "remix-utils/typed-session";
import { z } from "zod";

let schema = z.object({
  token: z.string().optional(),
  count: z.number().default(1),
});

// you can use a Remix's Cookie container or a Remix Utils' Typed Cookie container
let sessionStorage = createCookieSessionStorage({ cookie });

// pass the session storage and the schema
let typedSessionStorage = createTypedSessionStorage({ sessionStorage, schema });

现在，您可以将 typedSessionStorage 作为普通 sessionStorage 的直接替代品使用。

let session = typedSessionStorage.getSession(request.headers.get("Cookie"));

session.get("token"); // this will be a string or undefined
session.get("count"); // this will be a number
session.get("random"); // this will make TS yell because it's not in the schema

session.has("token"); // this will be a boolean
session.has("count"); // this will be a boolean

// this will make TS yell because it's not a string, if you ignore it it will
// throw a ZodError
session.set("token", 123);

现在，Zod 将通过不允许您获取、设置或取消设置数据来确保您尝试保存到会话中的数据是有效的。

注意请记住，您需要在模式中将字段标记为可选或设置默认值，否则将无法调用 getSession 来获取新的会话对象。

您还可以在模式中使用异步细化，因为类型化会话使用 Zod 的 parseAsync 方法。

let schema = z.object({
  token: z
    .string()
    .optional()
    .refine(async (token) => {
      if (!token) return true; // handle optionallity
      let user = await getUserByToken(token);
      return user !== null;
    }, "INVALID_TOKEN"),
});

let typedSessionStorage = createTypedSessionStorage({ sessionStorage, schema });

// this will throw if the token stored in the session is not valid anymore
typedSessionStorage.getSession(request.headers.get("Cookie"));

服务器发送事件

注意这取决于 react。

服务器发送事件是一种无需客户端请求即可将数据从服务器发送到客户端的方式。这对于聊天应用程序、实时更新等非常有用。

提供了两个实用程序来帮助在 Remix 中使用

eventStream
useEventSource

eventStream 函数用于创建将事件发送到客户端所需的新事件流响应。这必须位于资源路由中。

// app/routes/sse.time.ts
import { eventStream } from "remix-utils/sse/server";
import { interval } from "remix-utils/timers";

export async function loader({ request }: LoaderFunctionArgs) {
  return eventStream(request.signal, function setup(send) {
    async function run() {
      for await (let _ of interval(1000, { signal: request.signal })) {
        send({ event: "time", data: new Date().toISOString() });
      }
    }

    run();
  });
}

然后，在任何组件内部，您可以使用 useEventSource 钩子连接到事件流。

// app/components/counter.ts
import { useEventSource } from "remix-utils/sse/react";

function Counter() {
  // Here `/sse/time` is the resource route returning an eventStream response
  let time = useEventSource("/sse/time", { event: "time" });

  if (!time) return null;

  return (
    <time dateTime={time}>
      {new Date(time).toLocaleTimeString("en", {
        minute: "2-digit",
        second: "2-digit",
        hour: "2-digit",
      })}
    </time>
  );
}

事件流和钩子中的 event 名称是可选的，在这种情况下，它将默认为 message，如果已定义，则必须在两侧使用相同的事件名称，这也允许您从同一事件流发出不同的事件。

为了使服务器发送事件正常工作，您的服务器必须支持 HTTP 流。如果您无法使 SSE 工作，请检查您的部署平台是否支持它。

由于 SSE 计入每个域的 HTTP 连接限制，useEventSource 钩子会根据提供的 URL 和选项保留连接的全局映射。只要它们相同，钩子就会打开一个 SSE 连接并在钩子的实例之间共享它。

一旦没有更多钩子实例重用连接，它将被关闭并从映射中删除。

您可以使用 <EventSourceProvider /> 组件来控制映射。

let map: EventSourceMap = new Map();
return (
  <EventSourceProvider value={map}>
    <YourAppOrPartOfIt />
  </EventSourceProvider>
);

这样，您可以为应用程序的特定部分使用新的映射覆盖该映射。请注意，此提供程序是可选的，如果您不提供提供程序，则将使用默认映射。

滚动 Cookies

注意这依赖于 zod 和 React Router。

滚动 cookie 允许您通过更新每个 cookie 的过期日期来延长 cookie 的过期时间。

rollingCookie 函数已准备好在 entry.server 导出的函数中使用，以便在没有加载器设置的情况下更新 cookie 的过期日期。

对于文档请求，您可以在 handleRequest 函数中使用它

import { rollingCookie } from "remix-utils/rolling-cookie";

import { sessionCookie } from "~/session.server";

export default function handleRequest(
  request: Request,
  responseStatusCode: number,
  responseHeaders: Headers,
  remixContext: EntryContext
) {
  await rollingCookie(sessionCookie, request, responseHeaders);

  return isbot(request.headers.get("user-agent"))
    ? handleBotRequest(
        request,
        responseStatusCode,
        responseHeaders,
        remixContext
      )
    : handleBrowserRequest(
        request,
        responseStatusCode,
        responseHeaders,
        remixContext
      );
}

对于数据请求，您可以在 handleDataRequest 函数中使用它

import { rollingCookie } from "remix-utils/rolling-cookie";

export let handleDataRequest: HandleDataRequestFunction = async (
  response: Response,
  { request }
) => {
  let cookieValue = await sessionCookie.parse(
    responseHeaders.get("set-cookie")
  );
  if (!cookieValue) {
    cookieValue = await sessionCookie.parse(request.headers.get("cookie"));
    responseHeaders.append(
      "Set-Cookie",
      await sessionCookie.serialize(cookieValue)
    );
  }

  return response;
};

注意 > 阅读有关 Remix 中滚动 cookie 的更多信息。

命名操作

注意这依赖于 React Router。

通常需要在同一路由中处理多个操作，这里有很多选项，例如将表单发送到资源路由或使用操作 reducer，namedAction 函数使用一些约定来实现操作 reducer 模式。

import { namedAction } from "remix-utils/named-action";

export async function action({ request }: ActionFunctionArgs) {
  return namedAction(await request.formData(), {
    async create() {
      // do create
    },
    async update() {
      // do update
    },
    async delete() {
      // do delete
    },
  });
}

export default function Component() {
  return (
    <>
      <Form method="post">
        <input type="hidden" name="intent" value="create" />
        ...
      </Form>

      <Form method="post">
        <input type="hidden" name="intent" value="update" />
        ...
      </Form>

      <Form method="post">
        <input type="hidden" name="intent" value="delete" />
        ...
      </Form>
    </>
  );
}

此函数可以遵循以下约定

您可以将 FormData 对象传递给 namedAction，然后它将尝试查找名为 intent 的字段，并将该值用作操作名称。

如果无论如何都找不到操作名称，则 actionName，然后库将尝试调用名为 default 的操作，类似于 JavaScript 中的 switch。

如果未定义 default，它将抛出一个带有消息 Action "${name}" not found 的 ReferenceError。

如果库根本找不到名称，它将抛出一个带有消息 Action name not found 的 ReferenceError

预加载路由资产

[!CAUTION] 这可能会创建巨大的 Link 标头，并可能导致难以调试的问题。一些提供商的负载均衡器为解析传出响应的标头设置了特定的缓冲区，并且由于 preloadRouteAssets，您可以在中等规模的应用程序中轻松达到该缓冲区。您的负载均衡器可能会随机停止响应或开始抛出 502 错误。为了克服这个问题，请不要使用 preloadRouteAssets，如果您拥有负载均衡器，请为处理响应标头设置更大的缓冲区，或在 Vite 配置中使用 experimentalMinChunkSize 选项（这不能永久解决问题，只会延迟它）

Link 标头允许响应将文档所需的资产推送到浏览器，这对于通过更早地发送这些资产来提高应用程序的性能非常有用。

一旦支持 Early Hints，这也将允许您在文档准备好之前发送资产，但目前您可以受益于在浏览器解析 HTML 之前发送要预加载的资产。

您可以使用函数 preloadRouteAssets、preloadLinkedAssets 和 preloadModuleAssets 来执行此操作。

所有函数都遵循相同的签名

import { preloadRouteAssets, preloadLinkedAssets, preloadModuleAssets } from "remix-utils/preload-route-assets";

// entry.server.tsx
export default function handleRequest(
  request: Request,
  statusCode: number,
  headers: Headers,
  context: EntryContext,
) {
  let markup = renderToString(
    <RemixServer context={context} url={request.url} />,
  );
  headers.set("Content-Type", "text/html");

  preloadRouteAssets(context, headers); // add this line
  // preloadLinkedAssets(context, headers);
  // preloadModuleAssets(context, headers);

  return new Response("<!DOCTYPE html>" + markup, {
    status: statusCode,
    headers: headers,
  });
}

preloadRouteAssets 是 preloadLinkedAssets 和 preloadModuleAssets 的组合，因此您可以使用它来预加载路由的所有资产，如果您使用此函数，则不需要其他两个函数

preloadLinkedAssets 函数将预加载使用 Remix 的 LinkFunction 添加的任何带有 rel: "preload" 的链接，因此您可以在路由中配置要预加载的资产，并在标头中自动发送它们。它还将额外预加载任何链接的样式表文件（带有 rel: "stylesheet"），即使未预加载，它也会加载得更快。

preloadModuleAssets 函数将预加载 Remix 在水合时添加到页面的所有 JS 文件，Remix 已经在用于启动应用程序的 <script type="module"> 之前为每个文件呈现 <link rel="modulepreload">，这将使用 Link 标头来预加载这些资产。

安全重定向

执行重定向时，如果 URL 是用户提供的，我们不能信任它，如果您这样做，您将通过允许不良行为者将用户重定向到恶意网站来打开网络钓鱼诈骗的漏洞。

https://remix.utills/?redirectTo=https://malicious.app

为了帮助您防止这种情况，Remix Utils 为您提供了一个 safeRedirect 函数，该函数可用于检查 URL 是否“安全”。

注意在这种情况下，安全意味着 URL 以 / 开头，但不以 // 开头，这意味着 URL 是同一应用程序内的路径名，而不是外部链接。

import { safeRedirect } from "remix-utils/safe-redirect";

export async function loader({ request }: LoaderFunctionArgs) {
  let { searchParams } = new URL(request.url);
  let redirectTo = searchParams.get("redirectTo");
  return redirect(safeRedirect(redirectTo, "/home"));
}

safeRedirect 的第二个参数是默认重定向，如果未配置，则为 /，这使您可以告诉 safeRedirect 如果该值不安全，则将用户重定向到何处。

JSON 哈希响应

当从 loader 函数返回 json 时，您可能需要从不同的数据库查询或 API 请求中获取数据，通常您会执行以下操作

export async function loader({ params }: LoaderData) {
  let postId = z.string().parse(params.postId);
  let [post, comments] = await Promise.all([getPost(), getComments()]);
  return json({ post, comments });

  async function getPost() {
    /* … */
  }
  async function getComments() {
    /* … */
  }
}

jsonHash 函数允许您直接在 json 中定义这些函数，从而减少创建额外函数和变量的需要。

import { jsonHash } from "remix-utils/json-hash";

export async function loader({ params }: LoaderData) {
  let postId = z.string().parse(params.postId);
  return jsonHash({
    async post() {
      // Implement me
    },
    async comments() {
      // Implement me
    },
  });
}

它还使用 Promise.all 调用您的函数，因此您可以确保并行检索数据。

此外，您可以传递非异步函数、值和 Promise。

import { jsonHash } from "remix-utils/json-hash";

export async function loader({ params }: LoaderData) {
  let postId = z.string().parse(params.postId);
  return jsonHash({
    postId, // value
    comments: getComments(), // Promise
    slug() {
      // Non-async function
      return postId.split("-").at(1); // get slug from postId param
    },
    async post() {
      // Async function
      return await getPost(postId);
    },
  });

  async function getComments() {
    /* … */
  }
}

jsonHash 的结果是 TypedResponse，并且正确类型化，因此将其与 typeof loader 一起使用可以完美运行。

export default function Component() {
  // all correctly typed
  let { postId, comments, slug, post } = useLoaderData<typeof loader>();

  // more code…
}

将锚点委托给 Remix

使用 Remix 时，您可以使用 <Link> 组件在页面之间导航。但是，如果您有一个链接到应用程序中页面的 <a href>，它将导致页面完全刷新。这可能是您想要的，但有时您希望在此处使用客户端导航。

useDelegatedAnchors 钩子允许您将客户端导航添加到应用程序一部分中的锚标记。这在处理来自 CMS 的动态内容（如 HTML 或 Markdown）时特别有用。

import { useDelegatedAnchors } from "remix-utils/use-delegated-anchors";

export async function loader() {
  let content = await fetchContentFromCMS();
  return json({ content });
}

export default function Component() {
  let { content } = useLoaderData<typeof loader>();

  let ref = useRef<HTMLDivElement>(null);
  useDelegatedAnchors(ref);

  return <article ref={ref} dangerouslySetInnerHTML={{ __html: content }} />;
}

预取锚点

如果此外，您希望能够预取锚点，则可以使用 PrefetchPageAnchors 组件。

此组件使用锚点包装您的内容，它会检测任何悬停的锚点以预取它，并将其委托给 Remix。

import { PrefetchPageAnchors } from "remix-utils/use-delegated-anchors";

export async function loader() {
  let content = await fetchContentFromCMS();
  return json({ content });
}

export default function Component() {
  let { content } = useLoaderData<typeof loader>();

  return (
    <PrefetchPageAnchors>
      <article ref={ref} dangerouslySetInnerHTML={{ __html: content }} />
    </PrefetchPageAnchors>
  );
}

现在您可以在 DevTools 中看到，当用户悬停一个锚点时，它会预取该锚点，当用户单击它时，它将执行客户端导航。

防抖 Fetcher 和提交

注意这取决于 react 和 react-router。

useDebounceFetcher 和 useDebounceSubmit 是 useFetcher 和 useSubmit 的包装器，它们添加了防抖支持。

这些钩子基于 @JacobParis 的文章。

import { useDebounceFetcher } from "remix-utils/use-debounce-fetcher";

export function Component({ data }) {
  let fetcher = useDebounceFetcher<Type>();

  function handleClick() {
    fetcher.submit(data, { debounceTimeout: 1000 });
  }

  return (
    <button type="button" onClick={handleClick}>
      Do Something
    </button>
  );
}

与 useDebounceSubmit 的用法类似。

import { useDebounceSubmit } from "remix-utils/use-debounce-submit";

export function Component({ name }) {
  let submit = useDebounceSubmit();

  return (
    <input
      name={name}
      type="text"
      onChange={(event) => {
        submit(event.target.form, {
          navigate: false, // use a fetcher instead of a page navigation
          fetcherKey: name, // cancel any previous fetcher with the same key
          debounceTimeout: 1000,
        });
      }}
      onBlur={() => {
        submit(event.target.form, {
          navigate: false,
          fetcherKey: name,
          debounceTimeout: 0, // submit immediately, canceling any pending fetcher
        });
      }}
    />
  );
}

派生 Fetcher 类型

注意这依赖于 @remix-route/react。

从 fetcher 和导航数据中派生已弃用的 fetcher.type 的值。

import { getFetcherType } from "remix-utils/fetcher-type";

function Component() {
  let fetcher = useFetcher();
  let navigation = useNavigation();
  let fetcherType = getFetcherType(fetcher, navigation);
  useEffect(() => {
    if (fetcherType === "done") {
      // do something once the fetcher is done submitting the data
    }
  }, [fetcherType]);
}

您还可以使用 React Hook API，该 API 可让您避免调用 useNavigation。

import { useFetcherType } from "remix-utils/fetcher-type";

function Component() {
  let fetcher = useFetcher();
  let fetcherType = useFetcherType(fetcher);
  useEffect(() => {
    if (fetcherType === "done") {
      // do something once the fetcher is done submitting the data
    }
  }, [fetcherType]);
}

如果您需要在周围传递 fetcher 类型，您还可以导入 FetcherType 类型。

import { type FetcherType } from "remix-utils/fetcher-type";

function useCallbackOnDone(type: FetcherType, cb) {
  useEffect(() => {
    if (type === "done") cb();
  }, [type, cb]);
}

用于内容协商的 respondTo

如果您正在构建资源路由并希望根据客户端请求的内容类型发送不同的响应（例如，以 PDF 或 XML 或 JSON 格式发送相同的数据），您将需要实现内容协商，这可以使用 respondTo 标头完成。

import { respondTo } from "remix-utils/respond-to";

export async function loader({ request }: LoaderFunctionArgs) {
  // do any work independent of the response type before respondTo
  let data = await getData(request);

  let headers = new Headers({ vary: "accept" });

  // Here we will decide how to respond to different content types
  return respondTo(request, {
    // The handler can be a subtype handler, in `text/html` html is the subtype
    html() {
      // We can call any function only really need to respond to this
      // content-type
      let body = ReactDOMServer.renderToString(<UI {...data} />);
      headers.append("content-type", "text/html");
      return new Response(body, { headers });
    },
    // It can also be a highly specific type
    async "application/rss+xml"() {
      // we can do more async work inside this code if needed
      let body = await generateRSSFeed(data);
      headers.append("content-type", "application/rss+xml");
      return new Response(body, { headers });
    },
    // Or a generic type
    async text() {
      // To respond to any text type, e.g. text/plain, text/csv, etc.
      let body = generatePlain(data);
      headers.append("content-type", "text/plain");
      return new Response(body, { headers });
    },
    // The default will be used if the accept header doesn't match any of the
    // other handlers
    default() {
      // Here we could have a default type of response, e.g. use json by
      // default, or we can return a 406 which means the server can't respond
      // with any of the requested content types
      return new Response("Not Acceptable", { status: 406 });
    },
  });
}

现在，respondTo 函数将检查 Accept 标头并调用正确的处理程序，为了知道要调用哪个处理程序，它将使用也从 Remix Utils 导出的 parseAcceptHeader 函数

import { parseAcceptHeader } from "remix-utils/parse-accept-header";

let parsed = parseAcceptHeader(
  "text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, image/*, */*;q=0.8"
);

结果是一个包含类型、子类型和额外参数（例如 q 值）的数组。顺序与在标头中遇到的顺序相同，在上面的示例中，text/html 将是第一个，其次是 application/xhtml+xml。

这意味着 respondTo 助手将优先处理任何匹配 text/html 的处理程序。在上面的示例中，这将是 html 处理程序，但如果我们删除它，则将调用 text 处理程序。67

表单蜜罐

注意这依赖于 react、@oslojs/crypto 和 @oslojs/encoding。

蜜罐是一种简单的技术，用于防止垃圾邮件机器人提交表单。它的工作原理是在表单中添加一个隐藏字段，机器人会填写该字段，但人类不会。

Remix Utils 中有一对实用工具可以帮助你实现此功能。

首先，创建一个 honeypot.server.ts 文件，你将在其中实例化并配置你的蜜罐。

import { Honeypot } from "remix-utils/honeypot/server";

// Create a new Honeypot instance, the values here are the defaults, you can
// customize them
export const honeypot = new Honeypot({
  randomizeNameFieldName: false,
  nameFieldName: "name__confirm",
  validFromFieldName: "from__confirm", // null to disable it
  encryptionSeed: undefined, // Ideally it should be unique even between processes
});

然后，在你的 app/root 加载器中，调用 honeypot.getInputProps() 并返回它。

// app/root.tsx
import { honeypot } from "~/honeypot.server";

export async function loader() {
  // more code here
  return json({ honeypotInputProps: honeypot.getInputProps() });
}

在 app/root 组件中，渲染 HoneypotProvider 组件，并将其包裹在 UI 的其余部分之外。

import { HoneypotProvider } from "remix-utils/honeypot/react";

export default function Component() {
  // more code here
  return (
    // some JSX
    <HoneypotProvider {...honeypotInputProps}>
      <Outlet />
    </HoneypotProvider>
    // end that JSX
  );
}

现在，在每个你想防止垃圾邮件的公共表单中（例如登录表单），渲染 HoneypotInputs 组件。

import { HoneypotInputs } from "remix-utils/honeypot/react";

function SomePublicForm() {
  return (
    <Form method="post">
      <HoneypotInputs label="Please leave this field blank" />
      {/* more inputs and some buttons */}
    </Form>
  );
}

注意上面的标签值是默认值，可以使用它来本地化标签，或者如果你不想更改它，则将其删除。

最后，在表单提交到的 action 中，你可以调用 honeypot.check。

import { SpamError } from "remix-utils/honeypot/server";
import { honeypot } from "~/honeypot.server";

export async function action({ request }) {
  let formData = await request.formData();
  try {
    honeypot.check(formData);
  } catch (error) {
    if (error instanceof SpamError) {
      // handle spam requests here
    }
    // handle any other possible error here, e.g. re-throw since nothing else
    // should be thrown
  }
  // the rest of your action
}

Sec-Fetch 解析器

注意这依赖于 zod。

Sec-Fetch 标头包含有关请求的信息，例如，数据将用于何处，或者是否由用户发起。

你可以使用 remix-utils/sec-fetch 实用程序来解析这些标头并获取你需要的信息。

import {
  fetchDest,
  fetchMode,
  fetchSite,
  isUserInitiated,
} from "remix-utils/sec-fetch";

Sec-Fetch-Dest

Sec-Fetch-Dest 标头指示请求的目标，例如 document、image、script 等。

如果值为 empty，则表示它将由 fetch 调用使用，这意味着你可以通过检查它是 document （无 JS）还是 empty （启用 JS）来区分使用和不使用 JS 发出的请求。

import { fetchDest } from "remix-utils/sec-fetch";

export async function action({ request }: ActionFunctionArgs) {
  let data = await getDataSomehow();

  // if the request was made with JS, we can just return json
  if (fetchDest(request) === "empty") return json(data);
  // otherwise we redirect to avoid a reload to trigger a new submission
  return redirect(destination);
}

Sec-Fetch-Mode

Sec-Fetch-Mode 标头指示请求是如何发起的，例如，如果该值为 navigate，则表示由用户加载页面触发；如果该值为 no-cors，则可能是正在加载的图像。

import { fetchMode } from "remix-utils/sec-fetch";

export async function loader({ request }: LoaderFunctionArgs) {
  let mode = fetchMode(request);
  // do something based on the mode value
}

Sec-Fetch-Site

Sec-Fetch-Site 标头指示请求是在哪里发出的，例如，same-origin 表示请求是向同一域发出的，cross-site 表示请求是向不同域发出的。

import { fetchSite } from "remix-utils/sec-fetch";

export async function loader({ request }: LoaderFunctionArgs) {
  let site = fetchSite(request);
  // do something based on the site value
}

Sec-Fetch-User

Sec-Fetch-User 标头指示请求是否由用户发起，这可以用来区分用户发起的请求和浏览器发起的请求，例如，浏览器加载图像的请求。

import { isUserInitiated } from "remix-utils/sec-fetch";

export async function loader({ request }: LoaderFunctionArgs) {
  let userInitiated = isUserInitiated(request);
  // do something based on the userInitiated value
}

定时器

定时器实用程序提供了一种方法，可以在执行某些操作之前等待一定的时间，或者每隔一定的时间运行一些代码。

使用 interval 与 eventStream 结合使用，我们可以每隔一定的时间向客户端发送一个值。并确保在连接关闭时取消间隔。

import { eventStream } from "remix-utils/sse/server";
import { interval } from "remix-utils/timers";

export async function loader({ request }: LoaderFunctionArgs) {
  return eventStream(request.signal, function setup(send) {
    async function run() {
      for await (let _ of interval(1000, { signal: request.signal })) {
        send({ event: "time", data: new Date().toISOString() });
      }
    }

    run();
  });
}

作者

Sergio Xalambrí

许可证

MIT 许可证