跳到主要内容

Hooks API

本节为库中可用的自定义 React Hooks 提供了详细参考。这些 hooks 旨在封装和复用有状态逻辑，从而简化 Blocklet 环境中的常见任务和交互。

useComponentInstalled

此 hook 检查一个或多个指定的可选组件（通过其 DID 识别）是否已安装。它对于实现依赖其他 Blocklet 的功能至关重要。该 hook 提供安装状态和必要的 URL，以便在需要时提示用户进行安装。

参数

该 hook 接受一个包含以下属性的对象：

  • did string | string[] (required) — 要检查的组件的去中心化标识符（DID）或 DID 数组。单个字符串可包含多个由 ;; 分隔的 DID。
  • onInstalled function — 一个可选的回调函数，当所有指定组件都已安装时触发。
  • onError function — 一个可选的回调函数，当一个或多个指定组件未安装时触发。

返回值

它返回一个包含安装状态和相关数据的对象：

  • optComponents array — 一个包含未安装组件对象的数组。每个对象都包含元数据，如 meta.did、storeUrl 和 installUrl。
  • installed boolean — 一个布尔值，如果所有指定组件都已安装并在 blocklet.yml 中定义，则为 true，否则为 false。
  • installStatus object — 一个对象，其中键是组件的 DID，值是其当前的安装状态（例如，'waiting'、'installing'）。此状态通过 window.postMessage 事件更新。
  • setInstallStatus function — 用于手动更新 installStatus 对象的状态设置函数。
  • definedInBlockletYML boolean — 一个布尔值，指示组件是否在 blocklet 的配置（blocklet.yml）中定义。

示例用法

以下示例演示了如何在缺少依赖项时，使用 useComponentInstalled 来条件性地渲染一个功能或一个 ComponentInstaller 组件。

"ComponentFeature.js"

javascript
import React from 'react';
import { useComponentInstalled, ComponentInstaller } from '@blocklet/ui-react';

const REQUIRED_DID = 'z8ia24z55nve2TSF5m1aZ5322d9f48a43D4a'; // 示例 DID

function ComponentFeature() {
  const { installed, optComponents } = useComponentInstalled({ did: REQUIRED_DID });

  if (!installed) {
    // 如果组件不存在，则渲染安装器界面
    return <ComponentInstaller components={optComponents} />;
  }

  // 渲染依赖于已安装组件的功能
  return (
    <div>
      <h2>My Feature</h2>
      <p>This feature requires the component with DID: {REQUIRED_DID}</p>
      {/* ... 功能实现 ... */}
    </div>
  );
}

export default ComponentFeature;

useFollow

此 hook 管理当前认证用户与另一位由其 DID 指定的用户之间的关注关系。它处理关注和取消关注的 API 调用，并提供当前的关注状态。

参数

  • userDid string (required) — 要检查关注状态的用户配置文件的 DID。
  • t function (required) — 用于显示成功或错误消息的翻译函数（例如，来自 react-i18next）。
  • isMySelf boolean (required) — 一个布尔值，如果 userDid 属于当前登录的用户，则应设置为 true。

返回值

返回一个包含以下属性的对象：

  • followed boolean — 指示当前用户是否正在关注由 userDid 指定的用户。如果正在关注，则为 true，否则为 false。
  • followUser function — 一个稳定的函数，用于调用以关注用户。它处理 API 请求并在成功后更新 followed 状态。
  • unfollowUser function — 一个稳定的函数，用于调用以取消关注用户。它处理 API 请求并在成功后更新 followed 状态。

示例用法

此示例展示了如何创建一个 FollowButton 组件，该组件根据关系状态显示“关注”或“取消关注”操作。

"FollowButton.js"

javascript
import React from 'react';
import Button from '@mui/material/Button';
import { useTranslation } from 'react-i18next';
import { useFollow } from '@blocklet/ui-react/hooks';
import { useSession } from '@blocklet/did-connect-react';

function FollowButton({ profileDid }) {
  const { session } = useSession();
  const { t } = useTranslation();
  const isMySelf = session?.user?.did === profileDid;

  const { followed, followUser, unfollowUser } = useFollow({
    userDid: profileDid,
    t,
    isMySelf,
  });

  if (isMySelf) {
    return null; // 不在自己的个人资料页显示按钮
  }

  const handleClick = () => {
    if (followed) {
      unfollowUser();
    } else {
      followUser();
    }
  };

  return (
    <Button variant="contained" onClick={handleClick}>
      {followed ? t('profile.unfollow') : t('profile.follow')}
    </Button>
  );
}

export default FollowButton;

useMobile

一个用于创建响应式组件的简单实用工具 hook。它利用 Material-UI 的 useMediaQuery 来确定当前视口宽度是否低于指定的断点。

参数

  • key number | Breakpoint (default: 'sm') — Material-UI 断点键（例如，'xs'、'sm'、'md'）或用于比较的像素值。如果屏幕宽度小于此值，该 hook 返回 true。

返回值

返回一个 boolean 值：如果视口小于指定的断点，则为 true，否则为 false。

示例用法

此 hook 必须在由 Material-UI ThemeProvider 包裹的组件树中使用。

"ResponsiveComponent.js"

javascript
import React from 'react';
import Typography from '@mui/material/Typography';
import { ThemeProvider, createTheme } from '@mui/material/styles';
import { useMobile } from '@blocklet/ui-react/hooks';

// 一个使用该 hook 的组件
function ResponsiveComponent() {
  const isMobile = useMobile({ key: 'md' }); // 根据 'md' 断点进行检查

  return (
    <div>
      {isMobile ? (
        <Typography variant="h6">Mobile View</Typography>
      ) : (
        <Typography variant="h4">Desktop View</Typography>
      )}
      <p>Resize your browser window to see the content change.</p>
    </div>
  );
}

// 该组件必须被包裹在 ThemeProvider 中
const theme = createTheme();

function App() {
  return (
    <ThemeProvider theme={theme}>
      <ResponsiveComponent />
    </ThemeProvider>
  );
}

export default App;

通过使用这些 hooks，您可以用最少的样板代码高效地实现复杂功能。有关可能使用这些 hooks 的组件的更多信息，请参阅 组件 文档。