# @hanzogui/shell 中文文档

规范地址：https://npmcn.com/package/%40hanzogui/shell/

版本：8\.4\.4
npm 元数据更新时间：2026-10-30T17:32:12.978Z
中文译文更新时间：2026-11-17T08:39:10.193Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40hanzogui/shell
原文对照：https://npmcn.com/package/%40hanzogui/shell/?lang=original
项目主页：https://github.com/hanzoai/gui#readme
源码仓库：https://github.com/hanzoai/gui

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

- 包体积（解压后）：2.2 MB，271 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \>=19\.2\.8，react-dom \>=19\.2\.8，@hanzo/i18n \>=0\.4\.0
- 首次发布：2026-06-08T19:30:07.962Z
- 最新版本发布：2026-10-30T17:32:12.821Z
- 近 30 天下载量：9403（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：100（近 12 个月 100 个）

## 中文简介

统一汉佐外壳 — Frame (一个签名的应用软件穿行的工作空间: rail, Workspace switcher, 帐号菜单), Hanzoheader (一个公共酒吧: Hanzo 巨型菜单, QQK搜索, CTA 避孕药, IAM 身份), Orgheader (签名的栏目), UserOrgDropdown (

## 安装

```sh
npm install @hanzogui/shell
```

也可以使用：`pnpm add @hanzogui/shell`、`yarn add @hanzogui/shell`、`bun add @hanzogui/shell`

## README

# @hanzogui/ shell (韩语)

韩佐-斯塔克应用软件的导航外壳——一个公共头,一个签入 头,一个跨应用程序切换器.

共有铬的单一真菌源(Canonical, 单一真菌源)`HanzoHeader`, (中文(简体) ), `OrgHeader`, (中文(简体) ), `HanzoAppLauncher`, (中文(简体) ), `UserOrgDropdown`, (中文(简体) ), `OrgCommandPalette`, (中文(简体) ), `HanzoMark`, (中文(简体) ), `BeamAvatar`, (中文(简体) ), `UserAvatar`交叉计费、控制台、聊天和 平台.

奥特来自 `@hanzo/iam/react` (canonic IAM客户端)——一秒也没有 这里的会话计划 .

## 使用量

```tsx
import { IamProvider, useIam, useOrganizations } from '@hanzo/iam/react'
import { OrgHeader } from '@hanzogui/shell'

export function App() {
  return (
    <IamProvider
      config={{
        serverUrl: 'https://iam.hanzo.ai',
        clientId: 'my-app',
        redirectUri: `${window.location.origin}/auth/callback`,
      }}
    >
      <Shell />
    </IamProvider>
  )
}

function Shell() {
  const { user, logout } = useIam()
  const { organizations, currentOrg, switchOrg } = useOrganizations()
  return (
    <OrgHeader
      currentApp="MyApp"
      currentAppId="myapp"
      user={user ?? undefined}
      organizations={organizations}
      currentOrgId={currentOrg?.id}
      onOrgSwitch={switchOrg}
      onSignOut={logout}
    />
  )
}
```

## 公共头版——丰富的特大型产品(7.5.0+)

`HanzoHeader` 是一个公共/营销标题。 默认是平地 `localNav` + 通用"遇见汉藏"菜单. 过 `productsTaxonomy` 选择加入 大型云产品(旗舰Hanzo.ai UX)——a "出品"触发器出现在"遇见汉藏"旁边并打开 `<ProductsMegaMenu>`。 。 。 . Omit it and the header 行为与以前完全一样(完全后向相容).

```tsx
import { HanzoHeader, HANZO_PRODUCT_CATEGORIES } from '@hanzogui/shell'

// Shared default taxonomy:
<HanzoHeader surface="ai" productsTaxonomy={HANZO_PRODUCT_CATEGORIES} />

// A surface that owns the taxonomy locally passes its own (mapped to
// ProductCategory[]) so its /products/<slug> pages + routes never drift, and
// supplies its own wordmark + identity control via the slots:
<HanzoHeader
  surface="ai"
  productsTaxonomy={myCategories}     // ProductCategory[]
  currentCategoryId="ai"              // highlight the current category header
  currentHref="/models"              // highlight the current leaf
  brandSlot={<MyAnimatedWordmark />}  // replaces the default mark + name
  identitySlot={<MyAccountMenu />}    // far-right identity control
/>
```

`ProductsMegaMenu` 还被单独导出( 控制) `open`编号 :`onClose`编号 : `anchor`,键盘可访问). `HANZO_PRODUCT_CATEGORIES` (+ 数) `productCategorySlug`(中文(简体) ) 是共享默认分类; `ProductCategory` 是分类学的类型.

## 持有链接的导航条目( 8. 1. 14+)

A 类 `localNav` 条目(`HanzoNav`与 `items` 打开它们而不是导航—— 桌面上标签下的卡片,工作表自己在电话中披露. 它会保持它的 `href`因此,标签是水合前和无水化前的真正链接 JavaScript,以及QQ调色板索引它持有的而不是条目.

```tsx
localNav: [
  { id: 'solutions', label: 'Solutions', href: '/solutions' },
  {
    id: 'resources',
    label: 'Resources',
    href: '/learn',
    items: [
      { id: 'learn', label: 'Learn', href: '/learn', hint: 'Guides and documentation' },
      { id: 'blog', label: 'Blog', href: '/blog', hint: 'News and deep dives' },
    ],
  },
]
```

## 一个头,每个表面经过的东西

`HanzoHeader` 是一个公共酒吧。 它使铬; 表面只经过 自己的数据。 品牌触发器说 **汉三** 打开同一个特大菜单 \* 安装资源,预测来自 `HANZO_PRODUCTS` 内 `hanzo-registry.ts`。菜单在每一个表面都是一样的 建筑;没有关于它的表面.

```tsx
<HanzoHeader
  surface="ai" // id · hostname · or a HanzoSurface object
  productsTaxonomy={HANZO_PRODUCT_CATEGORIES} // opt into the rich Products menu
  tryMenu // primary action opens the menu
  auth={{ user, onSignIn, onSignOut }} // the identity cluster
  commands={myPages} // what ⌘K should also find
/>
```

| 表面 | `surface` | 二级导航(其数据) | 初级避孕药 |
| --- | --- | --- | --- |
| 韩佐·艾 | `"ai"` | 模型 代理 解决方案 开发者 定价 企业 | **试试半藏** |
| 韩佐. app | `"app"` | 特征 模板 定价 业务 | **\+ 新项目** |
| 书名: | `"docs"` | API-CLI-MCP-SDKs | **获取 API 密钥** |
| 控制台.hanzo.ai | `"console"` | API 状态 | 无(签署) |

拥有导航的地表经过 `HanzoSurface` 对象而不是标识。 这个 主要动作的LABEL是表面的;它的STYLE从不改变——一个白色 药丸,半径999, `rgb(250,250,250)`,34高,13px/600,来自 `cta(true)`。 。 。 .

## 身份——一个行动,一个提供者

Hanzo IAM是唯一的身份提供商,这个软件包从未运行过会话. 通过映射的用户和您的 `@hanzo/iam` 客户端的呼叫; 集群生成 签了字就签了 签了帐单就签了 有一个 这里没有密码字段,没有提供者按钮,也没有邮件故意掉回—— 每种方法都生活在IAM登录页面上,这是唯一知道的地方 已启用.

```tsx
const { user, startLogin, logout } = useIam()
<HanzoHeader surface="docs" auth={{ user, onSignIn: startLogin, onSignOut: logout }} />
```

## 访客聊天

一个聊天,两个码头. `corner` 将小型发射器挂在右下角; 没有它,同一个聊天是一个右侧抽屉。 模型默认为 `enso-free`。 。 。 .

```tsx
<AskHanzo corner authToken={bearer} />          // signed in — meters to the user
<AskHanzo corner auth={{ onSignIn }} />         // signed out — invites sign-in
<AskHanzo corner onSubmit={myTransport} />      // the host owns the transport
```

**从设计上讲,没有签字证书.** 可公布的密钥( E)`pk-`)为 仅读并拒绝补全; 密钥(`sk-`)是可花的,所以设置 一个共享的铬 将一个可花掉的秘密 传递给每一页 挂上它. 匿名推论需要SERVER手持密钥——绝不是浏览器.

所以没有 `authToken` 没有 `onSubmit`,卡片并不使作曲家 这将被拒绝:它显示针对同一供应商的一次登录行动: 标题。 给我 `auth` (单位:千美元) `HanzoAuth` 形状 ) 动作运行主机的 IAM 登录; 省略它和与网站本身的动作链接 `/login`。 。 。 .

## 奥尔格切换,然后通过自己的奥尔格

`UserOrgDropdown` 是 ONE 切换器( Orgheader 挂载它)。 你自己的角质 立即切换,没有变化。 供应 `findOrgs` 它得到一个 搜索字段:服务器过滤器,类型和页面;客户端只询问.

```tsx
<OrgHeader
  organizations={mine} // instant, no round trip
  onOrgSwitch={switchOrg}
  findOrgs={({ q, cursor }) => api.orgs({ q, cursor })}
  onMasquerade={startMasquerade} // only reachable for reach rows
  masquerade={actingAs} // renders the persistent sign
  onMasqueradeStop={stopMasquerade}
/>
```

服务器标记的一页 `reach: true` 列表中超出呼叫者的字符串 成员——"超级Admin"到达. 客户从不计算特权:否 到达页面,没有区域,没有方法要求。 切换你自己的 Org 电话 `onOrgSwitch`;充当别人的电话 `onMasquerade`因为他们是 不同的行为。 跑步的时候, `<Masquerade>` 在栏中用 一击出局,它与切换器一起运行——你通过起重机得到它.

`ORG_DOMAINS` 将每个圆块都映射到其品牌域上 — Hanzo / Lux / Zoo / Pars 被烤入——被签入的铬读取为账和计费链接.

## 克罗姆很黑,到处都是

条子、菜单、发射器和调色板都是一种材料:60px的玻璃 (单位:千美元)`rgba(9,9,11,0.72)` 结束 `blur(20px) saturate(1.8)`没有发线) 有黑暗 菜单挂起它——在每个表面,在每个主机主题。 所附菜单 铬穿 `PANEL` 并保持淡色主题下黑暗 页面正文为内容并遵循主题。 这里没有地面 `--background` 或任何其它倒置的标志, 这就是保持这个真理。 借着摩擦取来 组件; 如果您必须构建一个带铬的菜单, 我们不运送, 散开 `PANEL` 而不是用手来匹配颜色.

## 工作空间框架(8.3.19+)

`Frame` 汉佐应用软件的外壳 汉佐应用软件 戴着一个框环绕聊天和代码.

```tsx
import { Frame, Account, Scope, useScope, Beside, useFrame } from '@hanzogui/shell'

<Frame
  sections={[{ id: 'chat', label: 'Chat', icon: MessageSquare, href: '/chat' }, …]}
  active="chat"
  navigate={(href) => router.push(href)}
  back={router.back}
  forward={router.forward}
  workspace={<OrgProjectSwitcher … />}          // top of the sidebar: the ONE switcher
  scope={<Scope projects={…} project={…} onProject={…} environments={…} />} // the bar
  find={{ label: 'hanzo', open: () => setFinding(true) }}                   // ⌘K too
  list={<WhatTheSectionHolds />}
  account={<Account name={…} email={…} onProfile={…} onNotifications={…}
                    onAppearance={…} onSecurity={…} onSignOut={logout} />}
  settings={() => showSettings()}
  side={{ open, close, toggles }}
>
  {room}
</Frame>
```

-   **铁路**:作为标记的路段——手提电脑上的侧边栏-SHUT(一个明确的, 每设备切换; 在通过指针下不打开) 和标签栏 沿着电话的底部,四个部分和更多.
-   **脱去, 选入**: 通过 `strip` 铁路站在旁边 开口的边栏,头部有那个标记, 汉佐的方式。 团队画它。 关闭 默认:没有它,就没有最左边的条.
-   **边栏**: 顶部的工作空间切换器, 区块, 什么 节所持(`list`),主持人行行`foot`),脚下的账户. 以它的边缘和手机的床单为重 在它内部, `useFrame().pick` 选择一行后将工作表放出.
-   **账户**: 配置、通知、外观、安全、签名,其中 和没有余额 —— 贷记是工作空间, 根据比林。 一行来 主机无处可去 .
-   **范围**:项目与环境,栏目中的一个资源范围. `useScope(org)` 每个工作空间保留最后一个工程,并在一个工作空间恢复 切换,或明显回落到所有项目中;没有绘制环境 平台没有命名。 其键`hanzo:scope:*`)是每个工作空间,而不是 每人:主机在人变后,作为hanzo.ai和 韩佐 App 每一个都做 `hanzo*` 键.
-   **节** 指向应用程序的路径( w)`/…`或一个 `https://` 地址: 另一个主机,它被绘制为一个链接。 其他的都画不出来.
-   **还有**:一个房间将内容放入旁边的一栏;框架拥有 房间拥有里面的东西.
-   **通知**: 读者自己(`/v1/team/inbox`,读取 主办单位 `call` - 包裹没有证书.

框架遵循了主机主题(`FRAME` 内 `theme.ts` 读取gui's和 @hanzo/design's 梯子),与色素不同的是,色素到处是暗色.

## 一个应用程序列表

`HANZO_APPS` 是唯一的应用程序注册. `HanzoAppLauncher` 制作; `OrgHeader` 装上发射器; `OrgCommandPalette` 从 这个 过 `apps` 三者中的任何一人将推翻.

## 出口

-   `HanzoHeader` - 一个公共标题
-   `HanzoIdentity`, (中文(简体) ), `HanzoAuth` ——身份集群(IAM,一项行动)
-   `AskHanzo` 参观者聊天(`corner` 为右下方发射器)
-   `Masquerade` - 化妆舞会正在运行的标志 及其出道
-   `OrgHeader`, (中文(简体) ), `OrgHeaderProps`, (中文(简体) ), `OrgSearch` - 签入的酒吧:发射器, 面包屑 中心搜索 org 切换器 + 用户菜单, `headerLeft` 联 合 国 表面自有主控器
-   `HanzoAppLauncher` ——跨应用程序切换器
-   `UserOrgDropdown`, (中文(简体) ), `UserOrgDropdownProps` ——一角切换器
-   `OrgQuery`, (中文(简体) ), `OrgPage` 切换器询问服务器的内容及其答案
-   `OrgCommandPalette`, (中文(简体) ), `OrgCommandItem` 调色板
-   `HanzoMark`, (中文(简体) ), `HanzoWordmark` ——品牌标识(`brandMenu` 选择进入 右键点击品牌菜单)
-   `Frame`, (中文(简体) ), `Beside`, (中文(简体) ), `useFrame`, (中文(简体) ), `Section`, (中文(简体) ), `Side`, (中文(简体) ), `Find` - 工作空间框架
-   `Account` 边栏脚下的帐卡和菜单
-   `Scope`, (中文(简体) ), `useScope` - 酒吧的项目和环境
-   `Notifications`, (中文(简体) ), `Notice` ——读者通知页
-   `BeamAvatar`, (中文(简体) ), `UserAvatar` -阿凡达人
-   `HANZO_APPS`, (中文(简体) ), `ORG_DOMAINS` ——应用程序注册和每组域图
-   `HanzoApp`, (中文(简体) ), `HanzoUser`, (中文(简体) ), `HanzoOrg`, (中文(简体) ), `OrgDomains` - 类型

## 语言

贝壳所画的每一字都经过 `@hanzo/i18n`: 挂载 `I18nProvider` 一次和菜单、调色板、相框和账户 控件用读者语言读取。 没有供应商,他们读到 英语。 何等为主机传入——调色板命令,区段,人或人 org的名字——按给定的来画.

## 同伴依赖关系

-   `react`, (中文(简体) ), `react-dom`
-   `@hanzo/i18n` (>=0.4.0)——一个提供商上下文,主机上下文

## 常见问题

### @hanzogui/shell 是什么？

统一汉佐外壳 — Frame \(一个签名的应用软件穿行的工作空间: rail, Workspace switcher, 帐号菜单\), Hanzoheader \(一个公共酒吧: Hanzo 巨型菜单, QQK搜索, CTA 避孕药, IAM 身份\), Orgheader \(签名的栏目\), UserOrgDropdown \(

### 如何安装 @hanzogui/shell？

在项目目录运行 npm install @hanzogui/shell，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.2\.8）、react-dom（\>=19\.2\.8）、@hanzo/i18n（\>=0\.4\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @hanzogui/shell 支持 TypeScript 吗？

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

### @hanzogui/shell 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @hanzogui/shell 可以商用吗？

@hanzogui/shell 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @hanzogui/shell 的下载量有多少？

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

### @hanzogui/shell 还在维护吗？

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

