# @bridgeline-digital/hawk-app-ui 中文文档

规范地址：https://npmcn.com/package/%40bridgeline-digital/hawk-app-ui/

版本：0\.1\.7
npm 元数据更新时间：2026-11-09T03:50:07.806Z
中文译文更新时间：2026-11-09T06:46:31.612Z
软件包许可：UNLICENSED

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

原始 npm 页面：https://www.npmjs.com/package/%40bridgeline-digital/hawk-app-ui
原文对照：https://npmcn.com/package/%40bridgeline-digital/hawk-app-ui/?lang=original
项目主页：https://bitbucket.org/bridgelinedigital/hawk-apps/src/master/packages/ui/
源码仓库：https://bitbucket.org/bridgelinedigital/hawk-apps

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

- 包体积（解压后）：292 kB，69 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：react ^19\.1\.0，react-dom ^19\.1\.0，@mui/material ^9\.3\.1，@emotion/react ^11\.14\.0，@emotion/styled ^11\.14\.1，@mui/x-data-grid ^9\.11\.0，@bridgeline-digital/hawk-app-bridge \>=0\.1\.0 \<1\.0\.0
- 首次发布：2026-10-20T20:30:55.573Z
- 最新版本发布：2026-11-09T03:50:07.648Z
- 近 30 天下载量：4542（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 36 个）

## 中文简介

对于 Bridgeline 开发者: Spark look for Hawk Apps: for React + MUI,主题(遵循主机的颜色和模式),应用程序提供者和共享组件;对于任何应用程序(vanilla,Preact,React,Next),一个样式表和自定义元素.

## 安装

```sh
npm install @bridgeline-digital/hawk-app-ui
```

也可以使用：`pnpm add @bridgeline-digital/hawk-app-ui`、`yarn add @bridgeline-digital/hawk-app-ui`、`bun add @bridgeline-digital/hawk-app-ui`

## README

# @bitchline-digital/hawk-app-ui (英语)

"Spark"寻找"Hawk Apps",以主机的颜色和模式. 为 Bridgeline 开发者. 在光线下看到每个部分 阴暗: [UI 工具包画廊](https://npmcn.com/package/%40bridgeline-digital/hawk-app-ui/GALLERY.md) (关于开发商网站).

-   **反应 + MUI 应用程序** (单位:千美元) `next-mui` 模板 : Spark的MUI主题,连接应用程序与其主机的提供者, 和组件应用 继续需要: 区域、 KPI 瓦片、 表格、 小图表、 确认对话框、 侧抽屉, 土司和格式化. 需要鹰Apps桥.
-   **其他应用程序** (单位:千美元) `react`, (中文(简体) ), `preact`, (中文(简体) ), `next` 财务报告和审定财务报表 `vanilla` 模板:样式表和一些自定义元素, 不需要反应或MUI。 见 [没有反应和MUI](https://npmcn.com/package/%40bridgeline-digital/hawk-app-ui/#readme-without-react-and-mui)。 。 。 .

```bash
npm install @bridgeline-digital/hawk-app-ui @mui/material@^9 @emotion/react @emotion/styled   # React + MUI
npm install @bridgeline-digital/hawk-app-ui                                                    # any other app
```

## 用这个

```tsx
// app/layout.tsx (once): Montserrat, Spark's font, bundled with the app
import '@bridgeline-digital/hawk-app-ui/fonts';

// app/providers.tsx
'use client';
import { HawkAppProvider } from '@bridgeline-digital/hawk-app-ui';

export default function Providers({ children }: { children: React.ReactNode }) {
    return <HawkAppProvider>{children}</HawkAppProvider>;
}

// any page or component inside it
import { useHawk } from '@bridgeline-digital/hawk-app-ui';

export function Page() {
    const { app, context } = useHawk(); // the connected app and its context (client, engine, dates, theme)
    // …app.data.query(...), app.analytics.report(...)
}
```

-   **`HawkAppProvider`** 连接到主机( n)`createApp({ autoResize: true })`,修改后 `options`),显示a 同时回旋器和当应用程序在主机外打开时的解释(`connecting` 财务报告和审定财务报表 `error` 代替他们, 然后让孩子成为主题 它跟随主机在主题改变时. 旋转和解释 为 a `<main>` 所以访问检查在每个州都能找到一个.
-   **`useHawk()`** 返回时 `{ app, context }`,总是互相连接(提供方只让孩子在那时). `useHawkAppState()` 这是下面的钩子, 对于一个应用 想要使国家本身.
-   **`<HawkComments target label?>`** (单位:千美元) `comments` 范围)是一个带有“!”的注释图标,当有注释时(其工具提示中的计数);单击打开 抽屉中的线程,客户端的每个人都会读取并添加评论(作者编辑并删除自己的评论). 这个 页面的徽章共享一个计数请求. 见"通桥指南""评论".
-   **`usePdfExport(options | false)`** 让用户在挂载时导出该页面为 PDF: 主机显示 PDF 图标,单击后下载整个页面. `usePdfExport({ fileName: 'Zero results' })`,或 `false` 在装入时. 删除按钮和过滤器 `data-hawk-pdf-ignore`. 见"桥梁指南""输出一页作为PDF".
-   **`useSavedState(initial)`** 实值 `useState` 对于保存的视图( 过滤器、 范围、 标签、 排序) : 值是 页面对主机“视图”菜单的状态,打开已保存的视图或其链接将其放回. `const [filters, setFilters] = useSavedState({ range: 'l13', target: null })`一个小JSON对象,每页一次. 见"通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通通.
-   **`useRoute()`** 是该应用的深链接和回路 : `const [route, setRoute] = useRoute()`页面 路线名称,以及 `setRoute('/widgets/12')` 当用户打开一个( w)`{ replace: true }` 没有退后一步。 这个 主机将它保存在它的URL中,所以重新加载或链接打开同一个页面. 在预览( 没有主机) 中, 路由在 页 次 见"通桥指南""深通与后通".
-   **`useScreen(name | null)`** 计算路线不显示的屏幕, 如标签, 每次显示时: `useScreen('Logs')` 在标签的组件中。 路由和视图在桥边计数,点击也 `data-hawk-usage="Export CSV"` 要素。 见 `hawk-app usage --screens` 和桥导"错误与用".
-   **`usePageContext(object | null)`** 说页面显示的,为主机 **解释此页面** 按钮(及其 助理人员: `usePageContext(rows ? { page: 'Zero-result searches', dateRange, top10 } : null)`。普通名称和 数字,最多50 KB; 变化后不久发送, 当组件卸载时清除。 见桥指向 "说出页面显示的".
-   **`useTour()`** 是一个"Take the tour"按钮: `{ available, active, start }`。桥显示巡演 (单位:千美元)`tour` 在鹰app.json,卡由 `data-hawk-tour` (b) 单靠首次开放; `start()` 显示每个步骤 再说一遍, `available` 一旦该版本有步骤, `active` 在它显示。 没有预览 看桥 指南"图".
-   **您自己增加的主题 :** `<HawkAppProvider theme={{ components: { … } }}>`最后合并.

## 构成部分

```tsx
import { ConfirmDialog, DataTable, EmptyState, KpiRow, KpiTile, LoadingSection, Notice, Section, SideDrawer, useFormat, useToast } from '@bridgeline-digital/hawk-app-ui';
import { BarList, ColumnChart, Sparkline, StackedColumnChart } from '@bridgeline-digital/hawk-app-ui/charts';
import { DataGrid } from '@bridgeline-digital/hawk-app-ui/data-grid'; // needs @mui/x-data-grid@^9

const f = useFormat(); // in the host's locale
<KpiRow>
    <KpiTile highlight label="Revenue" value={f.money(rev)} change={rev / prevRev - 1} trend={weekly} />
    <KpiTile label="No-result searches" value={f.integer(zero)} change={zero / prevZero - 1} goodWhen="down" />
</KpiRow>
<Section title="Searches per day" subtitle="UTC days" action={<Button>Refresh</Button>}>
    <ColumnChart label="Searches per day" columns={days.map((d) => ({ label: f.date(d.date, { year: false }), value: d.searches }))} />
</Section>
<DataTable rows={terms} columns={[{ key: 'term', label: 'Term' }, { key: 'searches', label: 'Searches', align: 'right' }]}
    defaultSort={{ key: 'searches', direction: 'desc' }} totals={{ term: 'Total', searches: f.integer(total) }} download="terms.csv" />
```

| 构成部分 | 对于 |
| --- | --- |
| `Section` | 一个有标题的卡片(Spark的卡片头和贴纸),可选字幕和动作 |
| `KpiTile`, (中文(简体) ), `KpiRow` | 其变化与前一时期(绿色当良好时: `goodWhen`),一种可选趋势;并列瓦片 |
| `DataTable` | 最多几百行:可分类列,总行,粘取头(`maxHeight`),CSV下载其显示的内容(文本,电子表格将作为一个公式运行,例如从 `=`,以文本打开) |
| `DataGrid` (单位:千美元)`/data-grid`(中文(简体) ) | 上千行, 呼出并过滤: MUI X 的社区网格带有 Spark 的默认值 |
| `BarList`, (中文(简体) ), `ColumnChart`, (中文(简体) ), `StackedColumnChart`, (中文(简体) ), `Sparkline` (单位:千美元)`/charts`(中文(简体) ) | 主题颜色中的小图表,没有图表库;每个图都有 `label` 用于屏幕阅读器和带有值的工具提示 |
| `EmptyState`, (中文(简体) ), `LoadingSection`, (中文(简体) ), `Notice` | 无可显示; 一节仍在装入; 有信件(`onRetry` 添加 再试一次) |
| `ConfirmDialog` | 在行动前询问; `destructive` 让它红; 承诺从 `onConfirm` 用旋转器打开 |
| `SideDrawer` | 一个项目的细节, 从右边, 有标题, 关闭按钮和动作 |
| `useToast()` | `toast(message, severity)`:主持人的祝酒词在全方位的应用中,一个小吃栏在一景中 |
| `useFormat()` 编号 : `createFormat(locale)` | `integer`, (中文(简体) ), `number`, (中文(简体) ), `compact`, (中文(简体) ), `percent`, (中文(简体) ), `change` (+12.3%), `money`, (中文(简体) ), `date` (a"2026-10-03"日期停留当天), `dateTime`日期: a `Date` 或 ISO / Athena 字符串; 其它任何显示“ -” 的字符串 |

主机在打开一个对话框或抽屉时会在整个页面上显示框架,所以它们总是完全可见.

每个部件,光和暗,都是在 [UI 工具包画廊](https://npmcn.com/package/%40bridgeline-digital/hawk-app-ui/GALLERY.md) 在开发者网站(仓库) 画廊应用, `examples/ui-kit`页:1. `<HawkAppProvider preview={{ mode: 'dark' }}>` 在没有主机的情况下制作,并带有样本上下文 (单位:千美元)`previewContext()`),用于画廊,文档和截图. 新的应用程序从CLI那里得到工具箱 `next-mui` 模板 (单位:千美元)`hawk-app create my-app --template next-mui`); 已有的下一条 mui 应用程序得到它 `hawk-app upgrade`。 。 。 .

## 主题

`createHawkTheme(context.theme, ...overrides)` (亦见 `@bridgeline-digital/hawk-app-ui/theme`:

| 编 | 从 |
| --- | --- |
| 字法 (Montserrat, 14 px base, h1–h3, 14 px base, 14 px base, h1–h3), `featuredValue`),断点(`sm` 640号.. `2xl` 1536),间距,卡片和列表覆盖 | 斯派克的主题( S)`sparkThemeOptions`(中文(简体) ) |
| 主颜色及其文本、背景、文本颜色、分隔符、边框半径、光或暗 | 主机主题符号( Q)`color-button-accent-background`, (中文(简体) ), `color-background`, (中文(简体) ), `color-background-container`, (中文(简体) ), `color-text-default`, (中文(简体) ), `color-text-secondary`, (中文(简体) ), `color-border-default`, (中文(简体) ), `border-radius`, (中文(简体) ), `mode`),否则Spark's. A 类 `color-border-default` 在主机表面太微弱无法看见(在1.2下相接,如HawkSearch's `#f5f7fa` 在白色上)被忽略,所以分隔符,表格行和被概括的卡片保留了MUI的分隔符 |
| 框架部分的对话框和小吃栏 | 工具包`frameThemeOptions`从桥的 `--hawk-visible-*` 变量) |
| 菜单和选择不锁定帧滚动(一个锁会调整帧和页面闪存) | 工具包`frameThemeOptions`(中文(简体) ) |
| 表格行和页眉(分页颜色的边框,页上背景的页眉行,上下行为10px,其他行为有色;样式表的 `.hawk-table` 都一样) | 工具包`tableThemeOptions`(中文(简体) ) |

字体总是Spark's的,无论主机使用什么,所以应用在HawkSearch和Spark中看起来都是一样的.

## 没有反应和MUI

对于香草, Preact, React 或 Next apps 不使用 MUI : 与样式表相同的外观, 以及一些自定义的元素 CSS一个人办不到的. 没有依附关系:没有反应,没有MUI,没有桥.

```ts
// With a bundler (Vite, Next): once, where the app starts (Next: the css in app/layout.tsx).
import '@bridgeline-digital/hawk-app-ui/css';
import '@bridgeline-digital/hawk-app-ui/elements';
```

```html
<!-- Without a build step: from the CDN, at the bridge's version (the vanilla template does this). -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@bridgeline-digital/hawk-app-ui@0.1/dist/css/hawk.css" />
<script type="module" src="https://cdn.jsdelivr.net/npm/@bridgeline-digital/hawk-app-ui@0.1/dist/elements/index.js"></script>
```

**样式表** (单位:千美元)`/css`, (中文(简体) ), `dist/css/hawk.css`)携带蒙特塞拉特(不向Google字体提出要求)并绘制东道主地图 主题符号,桥架设置为 `--hawk-*` 变量和 `<html data-hawk-theme>`,作为 `createHawkTheme` 是否为: 口音,背景,文字,边框,半径和暗模式, 否则Spark's. 用它来 `--hawk-ui-*` 变量 (单位:千美元)`--hawk-ui-accent`, (中文(简体) ), `--hawk-ui-surface`, (中文(简体) ), `--hawk-ui-text`, (中文(简体) ), `--hawk-ui-text-secondary`, (中文(简体) ), `--hawk-ui-border`, (中文(简体) ), `--hawk-ui-radius`,... 为你自己的风格。 视图的一页`<html data-hawk-view>`保持透明.

| 类 | 对于 |
| --- | --- |
| `hawk-section` (单位:千美元)`hawk-section-header`, (中文(简体) ), `-title`, (中文(简体) ), `-subtitle`(中文(简体) ) | 一张名片, Spark's |
| `hawk-kpi-row`, (中文(简体) ), `hawk-stack`, (中文(简体) ), `hawk-row`, (中文(简体) ), `hawk-spacer` | 并排; 列或行块 |
| `hawk-button` (单位:千美元)`is-outlined`, (中文(简体) ), `is-text`, (中文(简体) ), `is-small`(中文(简体) ) | 主机口音中的按钮 |
| `hawk-field`, (中文(简体) ), `hawk-input`, (中文(简体) ), `hawk-select` | 窗体字段 |
| `hawk-notice` (单位:千美元)`is-error`, (中文(简体) ), `is-warning`, (中文(简体) ), `is-success`(中文(简体) ) | 一个消息 |
| `hawk-chip` (单位:千美元)`is-accent`, (中文(简体) ), `hawk-empty`, (中文(简体) ), `hawk-spinner`, (中文(简体) ), `hawk-skeleton` | 标签, 没有要显示的, 装入 |
| `hawk-table` (单位:千美元) `hawk-table-wrap`(中文(简体) ) | 普通表格(或使用) `<hawk-data-table>`(中文(简体) ) |
| `hawk-h1`. `hawk-h3`, (中文(简体) ), `hawk-value`, (中文(简体) ), `hawk-muted`, (中文(简体) ), `hawk-caption`, (中文(简体) ), `hawk-num` | 类型:标题、标题编号、次要文本 |

**要点** (单位:千美元)`/elements`使标记。 数据作为属性输入( E)`el.rows = [...]`,设置为 属性。 导入定义它们( 在浏览器中; 在服务器上导入是安全的, 例如在 Next) .

| 元素 | 使用 |
| --- | --- |
| `<hawk-kpi label value hint change good-when highlight loading>` | 其变化与前一个时期的比较`change` 作为一个分数, `none` 用于“没有先前的数据”; 绿色当良好时) |
| `<hawk-data-table>` | `columns` (单位:千美元)`{ key, label, align?, format?, value?, sortable?, csvLabel? }`· ; `format`数字 : `integer`, (中文(简体) ), `number`, (中文(简体) ), `compact`, (中文(简体) ), `percent`, (中文(简体) ), `money`, (中文(简体) ), `date`, (中文(简体) ), `dateTime` 或职能, `rows`, (中文(简体) ), `totals`, (中文(简体) ), `sort`; 属性 `download="file.csv"`, (中文(简体) ), `max-height`, (中文(简体) ), `clickable` (单位:千美元)`hawk-row-click` 事件, `empty`可排序标题, CSV 以排序方式下载行( 公式制成的文本) |
| `<hawk-bar-list>` | `items` (单位:千美元)`{ label, value }`(三); `selectable` (单位:千美元)`hawk-select` 事件, `value-format`, (中文(简体) ), `color`, (中文(简体) ), `label` |
| `<hawk-column-chart>` | `columns` (单位:千美元)`{ label, value, tooltip? }`(三); `height`, (中文(简体) ), `value-format`, (中文(简体) ), `color`, (中文(简体) ), `label` |

```js
const table = document.querySelector('hawk-data-table');
table.columns = [{ key: 'keyword', label: 'Keyword' }, { key: 'search_count', label: 'Searches', format: 'integer' }];
table.rows = report.data;
table.setAttribute('download', 'searches.csv');
```

`createFormat(locale)` (从) `/elements` 格式数字、钱和日期 `useFormat()`在反应或预告中 使用 TypeScript 键入 JSX 中的元素 `HawkElementTags` (模板有: `src/hawk-elements.d.ts`:

```ts
import type { HawkElementTags } from '@bridgeline-digital/hawk-app-ui/elements';
declare module 'react' { namespace JSX { interface IntrinsicElements extends HawkElementTags {} } } // Preact: 'preact'
```

敬酒: `app.toast(message, severity)` 从桥上看主人自己.

## 版本数

与"桥"和"CLI"一并发布(三个版本各一). 反应 + MUI 部分的对等依赖性: 反应 19, MUI 9,"情感11"(样式表和元素的选择),和桥.

## 常见问题

### @bridgeline-digital/hawk-app-ui 是什么？

对于 Bridgeline 开发者: Spark look for Hawk Apps: for React \+ MUI,主题\(遵循主机的颜色和模式\),应用程序提供者和共享组件;对于任何应用程序\(vanilla,Preact,React,Next\),一个样式表和自定义元素\.

### 如何安装 @bridgeline-digital/hawk-app-ui？

在项目目录运行 npm install @bridgeline-digital/hawk-app-ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@bridgeline-digital/hawk-app-bridge（\>=0\.1\.0 \<1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @bridgeline-digital/hawk-app-ui 支持 TypeScript 吗？

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

### @bridgeline-digital/hawk-app-ui 支持 ESM 还是 CommonJS？

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

### @bridgeline-digital/hawk-app-ui 可以商用吗？

@bridgeline-digital/hawk-app-ui 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @bridgeline-digital/hawk-app-ui 的下载量有多少？

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

### @bridgeline-digital/hawk-app-ui 还在维护吗？

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