# @g9tm/lynxcontrols-progress-overlay 中文文档

规范地址：https://npmcn.com/package/%40g9tm/lynxcontrols-progress-overlay/

版本：1\.7\.3
npm 元数据更新时间：2026-11-15T21:58:08.237Z
中文译文更新时间：2026-11-15T22:45:13.828Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40g9tm/lynxcontrols-progress-overlay
原文对照：https://npmcn.com/package/%40g9tm/lynxcontrols-progress-overlay/?lang=original

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

- 包体积（解压后）：181 kB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：@lynx-js/react \>=0\.129\.1 \<0\.130\.0
- 首次发布：2026-10-06T18:29:15.534Z
- 最新版本发布：2026-11-15T21:58:08.053Z
- 近 30 天下载量：2053（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

G9 进展监督:通过租赁、取消、尽量减少和重试实现长期运行进展.

## 安装

```sh
npm install @g9tm/lynxcontrols-progress-overlay
```

也可以使用：`pnpm add @g9tm/lynxcontrols-progress-overlay`、`yarn add @g9tm/lynxcontrols-progress-overlay`、`bun add @g9tm/lynxcontrols-progress-overlay`

## README

# @g9tm/lynxcontrols - 进度覆盖

一个用于长期业务的共享重叠 `G9MAUIControls.ProgressOverlay`租赁、进度、取消、, 最小化到可拖动的气泡、成功和失败终端。 取决于 `@g9tm/lynxcontrols-foundation` 财务报告和审定财务报表 `@g9tm/lynxcontrols` 只有这个 移徙表: [`docs/migration/ProgressOverlay.md`](https://npmcn.com/package/%40g9tm/lynxcontrols-progress-overlay/docs/migration/ProgressOverlay.md)。 。 。 .

```tsx
import { g9ProgressReport, useG9ProgressOverlay } from '@g9tm/lynxcontrols-progress-overlay';

const progress = useG9ProgressOverlay();          // or g9ProgressOverlay() outside components (active host)
const lease = await progress.show('Uploading samples', 'bottom');
try {
  progress.report(0.048, 'Uploading', '12 of 250');
  progress.report(g9ProgressReport.indeterminate('Connecting'));
  progress.reportQueued(3);                       // "+3 waiting"
  await upload();
  await progress.tryShowCurrentSuccess('250 samples uploaded');
} catch (error) {
  await progress.tryShowCurrentFailure('Server unreachable', 'Retry', () => upload());
} finally {
  await lease.dispose();                          // the last lease waits until the terminal state was seen
}

const off = progress.onCancelRequested(() => uploader.cancel());

// The host decides where an overlay shown without a position sits (MAUI 1.3.0), and moves a live one on a screen change.
progress.placementProvider = () => (mapTabShown ? { position: 'top', offset: mapTopBarHeight } : null);
onTabChanged(() => void progress.refreshPlacement());
```

## 行为

-   **租赁.** 并行操作每个都有一个可视化的租赁;最古老的是运行中的(其上下文文本) 显示),其余部分被排队. 将正在运行的租借权将视图交到下一个; 上一个时, 覆盖关闭 租借是在看到其终点状态后解除的.
-   **报告** 被连接到 ~ 10 Hz , 并且只驱动运行状态; 不确定的报告不会移动栏.
-   **取消** (a44×44目标) 立即切换到取消和广播到 `onCancelRequested` 听众 A 类 取消绝不是一个错误: 当运行停止时, 覆盖关闭, 并且中立的“ 取消” 土司显示; 如果 步骤不能被中断,通知出现在 5 s 之后.
-   **终端** 总是强迫满卡。 成功记录为2.2 s(倒计时栏)。 失败等待用户: 重试 重排为运行并运行一次动作( 第二次水龙头加入它); 关闭确认. `showStandaloneFailure` 显示一个没有运行的失败 .
-   **尽量减少.** 把运行中的卡片压到72×72泡(Lynx-ui) `Draggable`); 敲打气泡声 复还之.
-   **放置.** 下( 默认) 或上, 位于主机下方的内置值上方( O)`bottomWithTabBar`或在其顶部内置, 14 px入;土司起于下方上方. 打电话 `refreshBottomInset()` 在标签栏隐藏或返回(它)之后 滑翔机220毫秒).
-   **主机放置** (马来语: 1.3.0). 正确的位置取决于屏幕,而不是谁开始工作:设置 服务 `placementProvider` (它接收主机并返回) `{ position, offset }`,边缘加额外距离 从那个边缘的陷入,或 `null` 默认 `g9ProgressOverlayPlacement.default`) (中文(简体) ). 显示覆盖 **无** 后面有一个位置:在覆盖上架时会读取提供者,以及 `refreshPlacement()` 移动活页 当它下面的屏幕改变时(一个标签开关,一个全屏幕工作表). 同一边滑翔的相抵变化 边缘变化在旧边缘和新边缘逐渐消失(滑翔会把牌扫到整个屏幕上); `refreshPlacement(false)` 跳跃。 显示覆盖 **与** 一个能维持生命的姿势 一个最小的气泡 永远不会移动。 抛出提供者倒回默认值(带有控制台警告).

桌面上泡泡拖曳是一个设备检查(ledger N-047);放置运动为N-060.

## 常见问题

### @g9tm/lynxcontrols-progress-overlay 是什么？

G9 进展监督:通过租赁、取消、尽量减少和重试实现长期运行进展\.

### 如何安装 @g9tm/lynxcontrols-progress-overlay？

在项目目录运行 npm install @g9tm/lynxcontrols-progress-overlay，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@lynx-js/react（\>=0\.129\.1 \<0\.130\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @g9tm/lynxcontrols-progress-overlay 支持 TypeScript 吗？

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

### @g9tm/lynxcontrols-progress-overlay 支持 ESM 还是 CommonJS？

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

### @g9tm/lynxcontrols-progress-overlay 可以商用吗？

@g9tm/lynxcontrols-progress-overlay 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @g9tm/lynxcontrols-progress-overlay 的下载量有多少？

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

### @g9tm/lynxcontrols-progress-overlay 还在维护吗？

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