# @asteby/metacore-app-providers 中文文档

规范地址：https://npmcn.com/package/%40asteby/metacore-app-providers/

版本：153\.1\.0
npm 元数据更新时间：2026-10-21T20:45:45.662Z
中文译文更新时间：2026-11-07T00:42:37.754Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40asteby/metacore-app-providers
原文对照：https://npmcn.com/package/%40asteby/metacore-app-providers/?lang=original
源码仓库：https://github.com/asteby/metacore-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：167 kB，51 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=18，sonner \>=1\.7，react-dom \>=18，@asteby/metacore-ui \>=2\.28\.0，@asteby/metacore-pwa \>=0\.9\.3，@tanstack/react-query \>=5，@radix-ui/react-direction ^1\.1\.0，@asteby/metacore-runtime-react \>=53\.0\.0
- 首次发布：2026-04-20T23:40:49.900Z
- 最新版本发布：2026-10-21T20:45:45.404Z
- 近 30 天下载量：3895（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：173（近 12 个月 173 个）

## 中文简介

供应商 genéricos reutilizables para apps metacore(方向、字体、布局、搜索、平台配置)

## 安装

```sh
npm install @asteby/metacore-app-providers
```

也可以使用：`pnpm add @asteby/metacore-app-providers`、`yarn add @asteby/metacore-app-providers`、`bun add @asteby/metacore-app-providers`

## README

# @asteby/metacore-app- professors (帮助)

用于元核心主机应用程序的通用,可重复使用的 React 提供者. 一个 套接字将交叉关注 每一个元核心应用股份—— 方向,字体,布局,搜索,平台品牌——外加可选 "满包" `<MetacoreAppShell>` 将API + PWA + 烤面包机装入 单标签.

## 稳定

稳定到1.0级。 以下出口品如下: 持久性密钥 (cookie 名称, 本地Storage 密钥) 和提供者上下文形状不会 改变在少校内部。 可选择的同伴融合`@asteby/metacore-pwa`, (中文(简体) ), `@asteby/metacore-runtime-react`, (中文(简体) ), `@asteby/metacore-ui`, (中文(简体) ), `sonner`移动 - 贝壳能容忍兼容的版本 已声明对等区域 `package.json`。 。 。 .

## 安装

```bash
pnpm add @asteby/metacore-app-providers @radix-ui/react-direction
# transports / kits used by MetacoreAppShell + PlatformConfigProvider
pnpm add @tanstack/react-query sonner
# optional, only if you mount MetacoreAppShell:
pnpm add @asteby/metacore-pwa @asteby/metacore-runtime-react @asteby/metacore-ui
```

## 出口概况

| 导出 | 目的 |
| --- | --- |
| `DirectionProvider`, (中文(简体) ), `useDirection` | 具有饼干持久性的LTR/RTL(`dir`) (中文(简体) ). |
| `FontProvider`, (中文(简体) ), `useFont` | 打开字体类 `<html>`,有饼干味`font`) (中文(简体) ). 要求数 `fonts` 道具 (英语). |
| `LayoutProvider`, (中文(简体) ), `useLayout` | 侧边栏变体+相撞模式. 饼干: `layout_variant`, (中文(简体) ), `layout_collapsible`。 。 。 . |
| `SearchProvider`, (中文(简体) ), `useSearch` | Cmd/Ctrl+K 热键+ `open`编号 :`setOpen` 用于命令调色板. |
| `PlatformConfigProvider`, (中文(简体) ), `usePlatformConfig` | 租户品牌(名称,标志,主/角颜色,支持URL)-交通-不可知. |
| `useAgentSuggestions`, (中文(简体) ), `resolveAgentSuggestions`, (中文(简体) ), `DEFAULT_AGENT_SUGGESTIONS` | 副驾驶启动提示从 `PlatformBranding.agent_suggestions` (空白被忽略,中性倒置). |
| `applyBranding`, (中文(简体) ), `applyCachedBranding` | 用于预反应颜料和SW更新的必要帮助. |
| `FALLBACK_BRANDING` | 空的默认消费者可以分散. |
| `usePublishMascotFace`, (中文(简体) ), `useMascotFace`, (中文(简体) ), `mascotFaceStore` | 一个共享的吉祥物面相跨聊天表面; 最活跃的 `MascotState` 赢( r)`error` > 翻译: `speaking` > 翻译: `processing` > 翻译: `thinking` > 翻译: `listening` > 翻译: `happy` > 翻译: `idle`) (中文(简体) ). |
| `MetacoreAppShell` | 全装:ApiProvider + QueryClient + PWA + Toaster + addon-install桥. |
| `getCookie`, (中文(简体) ), `setCookie`, (中文(简体) ), `removeCookie` | 提供商共享的小饼干助手. |

类型 : `Direction`, (中文(简体) ), `Collapsible`, (中文(简体) ), `Variant`, (中文(简体) ), `FontProviderProps`, (中文(简体) ), `SearchProviderProps`, (中文(简体) ), `PlatformBranding`, (中文(简体) ), `BrandingFetcher`, (中文(简体) ), `PlatformConfigProviderProps`, (中文(简体) ), `MetacoreAppShellProps`, (中文(简体) ), `MetacoreInstallRequest`。 。 。 .

## 基本提供者

```tsx
import {
  DirectionProvider,
  FontProvider,
  LayoutProvider,
  SearchProvider,
} from '@asteby/metacore-app-providers'
import { fonts } from '@asteby/metacore-starter-config/fonts'

<DirectionProvider>
  <FontProvider fonts={fonts}>
    <LayoutProvider>
      <SearchProvider>
        <App />
      </SearchProvider>
    </LayoutProvider>
  </FontProvider>
</DirectionProvider>
```

-   `FontProvider` 需求 `fonts` (第一个条目是默认).
-   `SearchProvider` 接受 `hotkey` (默认) `'k'`,带有Cmd/Ctrl). 这个 消费者使用 `useSearch().open` 编号 : `setOpen()`。 。 。 .
-   所有四个持续状态在饼干 这样SSR/前沿运行时间可以恢复 初始帧.

## 平台设计——租户品牌

任何元核心应用软件的品牌集中化. Apps拿租户的 来自后端的品牌( 名称、 标志、 主要颜色、 支持 URL) 他们拥有的终点; 此提供者缓存它, 应用 CSS 变量 (单位:千美元)`--primary`, (中文(简体) ), `--background`, (中文(简体) ), `--sidebar-*`,(...)改为 `<html>`,持续 有效载荷在 `localStorage` 因此,随后的负载画 正确的品牌 **在此之前** 反应挂载,并在暗/光切换上重新应用.

提供商为运输-不可知:呼叫者通过Aync `fetcher`。无 HTTP 客户端为硬接线- 任意轴/ 取取/ 切/ 手卷 工作时.

```tsx
import {
  PlatformConfigProvider,
  applyCachedBranding,
  type PlatformBranding,
} from '@asteby/metacore-app-providers'
import { api } from './lib/api'

// Paint the cached brand BEFORE React mounts.
applyCachedBranding()

const defaults: PlatformBranding = {
  platform_name: 'Acme Hub',
  platform_logo: '/logo.svg',
  primary_color: '#84cc16',
  accent_color: '#22d3ee',
  favicon_url: '/favicon.ico',
  support_email: 'support@acme.test',
  support_url: 'https://acme.test/support',
}

<PlatformConfigProvider
  fetcher={async () => (await api.get('/platform/branding')).data}
  defaults={defaults}
>
  <App />
</PlatformConfigProvider>
```

在树上:

```tsx
const { platform_name, primary_color, refetch } = usePlatformConfig()
```

`refetch()` 如果主机只知道品牌, 查询无效 更改(例如在设置保存后).

### 合同

-   `fetcher` 决定: `Partial<PlatformBranding>`。供应商合并 结束了 `defaults`因此,缺失的字段倒回 而不是空白 乌伊 UI.
-   十六进制颜色( H)`#rrggbb`改为 `oklch()` 并推倒在 `<html>` 元素作为 CSS 变量。 暗/光变体是衍生出来的 读取 `document.documentElement.classList`; 提供者观察 类更改并重新应用到切换上.
-   持久性键是 `platform-branding` 内 `localStorage`通过 `storageKey`。 。 。 . `applyCachedBranding(storageKey?)` 为主机导出 在他们的预反应启动脚本中需要一个非默认密钥.
-   第一个框架:如果 `window.__BRAND__` 存在(服务器通过 `/api/brand/boot.js`,与 `PlatformBranding`, (中文(简体) ), `applyCachedBranding` 绘制并重写存储密钥 存储值仅在 `__BRAND__` 不在(离线)。 每个真实的 获取器响应 REPLACES 存储字段( 不与旧值合并) . 颜色必须是 `#RRGGBB`; 在绘画或存储之前, 任何其它东西都会被丢弃 (单位:千美元)`sanitizeBranding`, (中文(简体) ), `persistBranding`, (中文(简体) ), `readWindowBranding` ) .
-   `staleTime` 默认为5分钟(TanStack Query). 提供者保留 每个查询 `storageKey`。 。 。 .

## Metacore AppShell —— 全套工具包

`<MetacoreAppShell>` 给每个供应商电线 一个应用程序需要运行在 metacore平台:API上下文,查询客户端,PWA安装+更新 提示、 离线指示器、 声纳烤面包机、 附加安装桥 嵌入式枢纽iframes, 以及 stale- while- revalidate 元数据缓存 应用服务员更新时无效 .

```tsx
import { MetacoreAppShell } from '@asteby/metacore-app-providers/shell'
import { QueryClient } from '@tanstack/react-query'
import { api } from './lib/api'

const queryClient = new QueryClient()

<MetacoreAppShell api={api} queryClient={queryClient}>
  <RouterProvider router={router} />
</MetacoreAppShell>
```

可选旗帜( 所有默认启用) :

| Prop | 效果 |
| --- | --- |
| `hideToaster` | 跳过捆绑 `<Toaster />`。 。 。 . |
| `hidePWAInstall` | 跳过 `<PWAInstallPrompt />`。 。 。 . |
| `hidePWAUpdate` | 跳过 `<PWAUpdatePrompt />`。 。 。 . |
| `hideOfflineIndicator` | 跳过 `<OfflineIndicator />`。 。 。 . |
| `disableMetadataInvalidate` | 不要在 SW 更新中放弃运行时间元数据缓存. |
| `onAddonInstall` | 自定义处理器 `metacore:install` 后Message来自嵌入式Hub iframe. 设定为 `null` 以禁用听众. |
| `toasterPosition` | `'top-right'` (a) 默认. |

外壳会拉同龄人`@asteby/metacore-pwa`, (中文(简体) ), `@asteby/metacore-runtime-react`, (中文(简体) ), `@asteby/metacore-ui`, (中文(简体) ), `sonner`当 安装。 只想要子集线的应用程序 单个提供者和 跳过外壳.

### Addon 安装桥

当被安装在(或与)元核枢纽一起时,外壳会听 页:1 `window.postMessage({ type: 'metacore:install', addonKey, ... })` 事件,或者:

1.  引用 `onAddonInstall(req, source)` 如果你提供了一个,或
2.  职位 `req` 改为 `/marketplace/install` 在捆绑的API客户端.

如果成功,它显示一个音速烤面包, 放弃运行时间元数据缓存, 发件人a `metacore:metadata-changed` `CustomEvent` 打开 `window` (这样) 侧边栏和命令菜单在不重新装入的情况下进行反切),和回复 内框 `metacore:installed`失败时,它答复 `metacore:install-failed` 并显示错误.

## 持久性摘要

| Cookie/ 密钥 | 拥有者 |
| --- | --- |
| `dir` | `DirectionProvider` |
| `font` | `FontProvider` |
| `layout_variant` | `LayoutProvider` |
| `layout_collapsible` | `LayoutProvider` |
| `platform-branding` | `PlatformConfigProvider` (当地费用) |

## 许可证

阿帕奇 - 2.0

## 常见问题

### @asteby/metacore-app-providers 是什么？

供应商 genéricos reutilizables para apps metacore\(方向、字体、布局、搜索、平台配置\)

### 如何安装 @asteby/metacore-app-providers？

在项目目录运行 npm install @asteby/metacore-app-providers，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=18）、sonner（\>=1\.7）、react-dom（\>=18）、@tanstack/react-query（\>=5）、@radix-ui/react-direction（^1\.1\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @asteby/metacore-app-providers 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @asteby/metacore-app-providers 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @asteby/metacore-app-providers 可以商用吗？

@asteby/metacore-app-providers 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @asteby/metacore-app-providers 的下载量有多少？

根据 npm 官方下载统计，@asteby/metacore-app-providers 在 2026/10/07 – 2026/11/05 这 30 天内被下载 3,895 次，日均约 130 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @asteby/metacore-app-providers 还在维护吗？

最新版本 153\.1\.0 发布于 2026/10/22（17 天前）；至今共发布 173 个版本，其中过去 12 个月发布了 173 个；首次发布于 2026/04/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。