# jg-react-ui 中文文档

规范地址：https://npmcn.com/package/jg-react-ui/

版本：0\.4\.0
npm 元数据更新时间：2026-11-03T22:16:27.695Z
中文译文更新时间：2026-11-03T23:14:17.813Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/jg-react-ui
原文对照：https://npmcn.com/package/jg-react-ui/?lang=original
项目主页：https://github.com/jesusgraterol/jg-packages/tree/main/packages/jg-react-ui#readme
源码仓库：https://github.com/jesusgraterol/jg-packages

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

- 包体积（解压后）：2 MB，531 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.17\.0
- 运行依赖：28 个
- peer 依赖：react ^19\.2\.4，react-dom ^19\.2\.4，tailwindcss ^4\.3\.3，react-router ^7\.14\.2
- 首次发布：2026-10-30T13:08:26.826Z
- 最新版本发布：2026-11-03T22:16:27.289Z
- 已发布版本数：10（近 12 个月 10 个）

## 中文简介

以消费者为主题的React组件，带有源自moldea的api、显式的样式契约和可重用的应用程序行为。

## 安装

```sh
npm install jg-react-ui
```

也可以使用：`pnpm add jg-react-ui`、`yarn add jg-react-ui`、`bun add jg-react-ui`

## README

# jg-react-ui

以消费者为主题的React组件，保留了源自moldea的api。

## 安装

```bash
pnpm add jg-react-ui
```

## 用法

```ts
import { createElement } from 'react';
import { Button } from 'jg-react-ui/components/button';
const saveAction = createElement(Button, { size: 'touch' }, 'Save changes');
```

那么，进口一次顺风吧 `jg-react-ui/styles.css`． 供应 `--background`， `--foreground`， `--primary`， `--primary-foreground`， `--secondary`， `--secondary-foreground`， `--destructive`， `--chart-1` (成功), `--chart-2` (警告) `--border`， `--radius`， `--jg-ui-font-sans`， `--jg-ui-font-mono`， `--jg-ui-shadow-inset`， `--jg-ui-shadow-surface`， `--code`， `--code-foreground`， `--jg-ui-shadow-raised`, `--jg-ui-inverse-color-scheme` 在你自己的主题里。颜色必须是完整的CSS颜色值。 `.dark` 选择暗效用变量；这个包不提供品牌调色板。对于JG调色板和字体，使用 `jg-personal-react-ui` 代替。

Button, Badge， IconTile和Alert在提交时保留Moldea的api `2920a7b0a6e814e95872fcdd6dd8746ae422c038`，包括变体，大小，refs，徽章，和 `asChild` 支持的地方。导出的 `badgeVariants`， `iconTileVariants`, `alertVariants` 保留它们的源签名。Badge默认为span；IconTile是装饰性的，除非 `aria-hidden={false}` 提供;静态警报使用 `role="alert"`，带有短语内容标题和描述槽。在粗糙的指针下，按钮的触摸大小至少保持44px，包括在平板电脑上。按钮的 `asChild` 只需要一个元素，并保留Base UI的按钮语义，包括当该元素是锚点时。使用孩子的显式 `role="link"` 当它表示导航时。

在服务器呈现期间导入所有JavaScript条目都是安全的。样式仍然是显式的CSS导入。UI首选项模式保留完整的主题、diff布局、包装和安装-卸载记录；解散时间戳是一个ISO日期时间字符串或 `null`． 提供程序为每个挂载的树创建存储，并且在渲染期间不执行浏览器存储I/O。

首选项、主题和通知都来自同一个固定的Moldea提交。包适应将全局存储和私有应用程序注册中心替换为提供者本地ssr安全存储和限定范围的错误反馈，根据jg-storage的规则验证捕获的名称空间，保留取消，并允许显式 `null` 解雇重置。主题效果使用React的浏览器生命周期，通知主机保留配置的字体，并融入正文门户。

警徽和警报 `asChild` 也只需要一个元素，否则会抛出 `Error("asChild requires exactly one valid React element child.")`． 为 `interaction="redirect"`，开锚；为 `interaction="action"`，插入本地按钮。交互选项提供样式，而本机子选项提供键盘语义。继续补充 `AlertAction` 控件，远离交互式父按钮或锚。默认情况下，链接的Badge保持紧凑；当它是一个独立的触摸目标时，添加粗指针最小尺寸。

ErrorFeedbackProvider将应用程序拥有的错误拷贝和访问丢失分类作用到一个React树中。传递解析器 `createErrorFeedback` 在 `jg-exception`； `useErrorFeedbackResolver` 读取最近的政策。如果没有提供程序，未知的诊断和代码将保持在通用副本之后的私有状态。取消保持可识别性，抛出应用程序策略安全返回。

## 首选项、主题和通知

组成 `UiPreferencesProvider`， `ThemeProvider`，还有一个 `Toastr` 宿主按这个顺序。 `ThemeToggleButton` 保留源按钮道具和请求回调。文档主题和Sonner通知通道是文档范围的；即使挂载了独立的首选项根，也要为每个文档保留一个主题所有者和一个通知主机。

Sonner在其浏览器模块加载时注入其基本通知CSS。包主题样式仍然是显式导入。所有JavaScript条目都是可导入的，服务器上没有浏览器全局变量。

首选项提供程序支持显式 `local`， `read-only`, `remote` 模式。本地模式读取和写入最努力的浏览器存储，并遵循匹配的跨选项卡事件。只读模式只公开快照，不允许更新。远程模式需要完成 `initialPreferences` 还有async `persistPreferences` 适配器：更新是乐观的，保存顺序运行并合并更新的快照，被拒绝的保存回滚到最新的权威道具。应用程序拥有网络请求和缓存无效。挂起的请求在卸载后无法更新存储或显示通知。

可选 `storageId` 默认为 `jg-ui-preferences`． 只能包含ASCII字母、数字、“\_”和“-”，不能为空。 `getUiPreferencesStorageKey` 返回原始数据 `jg-storage:` 关键。在提供程序生命周期内捕获id；使用键重挂载来更改名称空间。无效id在存储访问或初始化脚本创建之前失败。

渲染 `ThemeInitializationScript` 在应用程序JavaScript之前的文档头部，使用相同的 `storageId` 作为提供商和您的CSP `nonce` 在需要时。服务器快照使用初始道具或默认值，然后存储在聚合后同步。请参阅配方的组成和共享 [自有错误契约](https://unpkg.com/jg-react-ui@0.3.4/errors/README.md)。

## 控件、窗体和纯文本

表单、选择/选择控件、选项卡、下拉菜单、工具提示、复制反馈、进度、分隔符、空状态、链接、内联代码和普通的排版/表原语保留相同的固定的Moldea api。应用程序拥有表单验证和关联。设置应用的根目录 `font-sans bg-background text-foreground` 类，同时提供阴影角色和代码颜色角色，并围绕紧凑的复选框/单选/开关符号组成标记的触摸行。字段在粗指针下使用至少16px的文本；触摸选项卡和菜单行保留44px目标。 `tw-animate-css` 通过显式的包样式表提供保留的进入/退出动画实用程序。

`TabsList` 需要 `overflowBehavior: 'scroll' | 'truncate'`;截断列表中的复合标签需要 `title` 或 `aria-label`． 选择并菜单取消别名，以尊重有意取消。Select保持源的接受 `forceMount`/`sticky` 别名，没有额外的基本UI行为。插槽控件需要一个有效的元素，并保留其特定于组件的本机错误保护。菜单和工具提示保留了它们的门户和定位api。

`CopyButton` 在初始化手势期间写入准确的文本，阻止重叠的写入，并在完成后开始反馈。它的反馈持续时间保持毫秒级。 `copyLabel` 提供一个作用域的就绪名称，可见 `label`/`copiedLabel` 并且保留本地命名覆盖，失败使用最近的错误策略，取消保持沉默。它清除计时器并忽略卸载后的延迟反馈。TextLink增加了安全的rel令牌和一个新标签公告；TableContainer接受键盘可滚动表的本地区域/名称/焦点道具。

## 对话框、抽屉和布局

Dialog、AlertDialog、Drawer、ConfirmationDialog和page/layout原语保留了固定的复合api。DialogContent需要一个大小和直接的DialogHeader， DialogBody和可选的DialogFooter子元素；asChild接受一个包含这些区域的面板元素。使用允许对话框角色的元素，例如div；在主体中放置一个表单，并将固定的提交操作与其表单ID关联起来。 抽屉需要一个边，它的内容需要一个大小，它的直接区域顺序是页眉，正文，可选页脚。AlertDialogContent需要直接的页眉和页脚。无效的组合和无效的槽子保留本地错误保护。

中型和大型对话框成为手机上的全屏页面，具有生成的后退和桌面关闭控件。正文区域拥有滚动，而标题和操作保持固定。紧凑模态关闭控件保留其精细指针外观，并在粗指针下具有实际的44px目标。默认的初始焦点会跳过不可用的控件；initialFocus和生成的控件图标/标签仍然可配置。默认情况下，对话框的覆盖解除是禁用的。 isDismissalDisabled阻止页面上的解雇；已提交导航仍然会取消过时的对话框。

DialogNavigationProvider、DialogNavigationObserver和usedialognavigation解雇直接重用了js -react-router的实现和上下文。将观察者放置在路由器中，并在同一个提供商下使用持久的对话框主机。取消导航不会创建历史记录项。宿主应用程序拥有路由历史记录及其导航UI；drawer通过显式的drawclose组合或应用程序状态关闭路由操作。

每个文档挂载一个ConfirmationDialog并使用useConfirmationDialogStore.getState(). openconfirmationdialog （options）。这个命令式存储保留了源文件范围的会话API；在服务器呈现时不要改变它。Completion在调用应用程序回调之前重置会话，在确认时接收true，在取消时接收undefined。应用程序拥有异步工作和回调错误。 受控对话子框通过关闭过渡保持不变，然后在完成时释放。移动返回快照忽略陈旧的回调，并在运动减少或不支持的浏览器中跳过。

PageShell, PageHeader, PageHeaderRow, PageHeaderTitleGroup, PageHeaderMetadata, PageTitle, PageDescription, Stack， Inline和Surface保留了本地的语义道具和共享的几何形状。Supply -jg-ui-shadow-surface以及其他通用主题角色。样式表提供源页行距和抽屉行距挂钩；它不会重置文档的调色板或排版。

## 路由和查询恢复

`RouterRoot` 保留源数据-路由器出口、挂起的进程和共享对话观察器。它需要React Router的数据路由器和共享路由器peer。路线进度尊重顶部安全区域的插入。它不添加历史条目或更改页面焦点/滚动策略；组成 `jg-react-router`的 `PageOutlet` 当主人想要那样做的时候。 `GlobalErrorBoundary` 读取抛出的路由错误，将其标记为recovery main，保留本地refs，并取消过时的对话会话； `GlobalErrorBoundaryView` 接受不带路由器上下文的显式错误。恢复默认为 `jg-sw`的 `updateApp`，带有可选的 `onRefreshClick`． 未知错误和恢复失败使用范围安全反馈。挂起的刷新和重试操作忽略重叠的单击。

`QueryBoundary`， `QueryLoader`， `LoadMoreButton`， `QueryErrorAlert`, `QueryErrorToastr` 保留结构化查询api。边界将初始解析委托给 `jg-tanstack-query`的共享钩子：陈旧的未经批准的数据等待，当前的数据在后台故障中幸存下来，一个新的 `resolutionKey` 重新开始，访问丢失会立即隐藏数据。访问丢失后，调用方审批无法恢复数据，直到每个查询都成功解决当前数据。最近的 `ErrorFeedbackProvider` 拥有访问丢失分类和可见副本；这些包中没有应用程序注册表。

默认的错误槽是内联阻塞/保留警报。自定义渲染器可以使用持久化 `QueryErrorToastr` 对于保留的内容。提供独一无二的马厩 `toastId` 每个活动故障所有者和一个 `Toastr` 每个文件的主机。Toast发布遵循提交效果，因此后安装的主机接收初始失败，并且取消过时的排队反馈。重试读取最新提交的查询和策略，忽略活动读取/重叠重试，并保持故障可操作，直到恢复；卸载清理保留相同id的替换。重试解决每个失败的查询，包括被拒绝或同步抛出的适配器。取消的错误不会产生中断警报或吐司。 Load-more click回调先运行，并可能取消请求 `preventDefault`。

默认的紧凑分页和恢复操作保留了它们的精细指针几何形状，并且在粗指针下至少有44px的目标。JG的全球恢复表面在两个主题中都使用了基础的反向调色板。通用消费者集 `--jg-ui-inverse-color-scheme` 来匹配它们的恢复面(`dark` 或 `light`）; 选择和聚焦发挥了它的主要作用。查询客户机、网络适配器、分页限制、应用程序代码映射和路由历史记录仍然是主机所有的。

## 文件上传和音频输入

`FileUpload`， `FileUploadDialog`， `ImageUploadField`, `AudioInput` 保留固定的源道具和回调。文件上传重用 `jg-react`允许、并发、进度、取消和重试队列。调用方提供验证和传输回调；不包括端点、授权策略、存储服务或转录提供程序。上传适配器必须遵守其中止信号。image字段显示调用者的当前图像，并在预览失败时安全返回；调用者拥有对象URL的创建和撤销。

上传对话框通过完成成功的结果 `onSubmit`重试结束而不重新加载，并通过报告放弃的成功项目 `onDiscard`． 调用方拥有远程清理和回调失败。音频输入拥有麦克风轨道、记录器处理程序、波形上下文、间隔和延迟命令。废弃的权限/转录结果在卸载后无法更新替换会话或调用完成。记录复位是即时的；关闭保留了源的短视觉复位延迟。

`transcribe` 接收捕获的记录并返回文本。用户可以直接发送或先编辑抄本；发送失败会重试已编写的文本，而不会再次转录。提供者操作仍然是调用者所有的，并且应该有自己的截止日期/取消策略。记录/转录错误回调接收诊断异常，而可见反馈使用最近的作用域解析器。七个拥有的音频代码和稳定消息列在 `errors/README.md`;编码提供程序异常保留其诊断标识。取消的许可/转录工作保持沉默，可以重新启动；诊断回调仍在运行。可选的结果回调仍然是可选的。独立审查仍然是默认的。供应 `onTranscriptionApply` 将转录结果直接放在主输入while中 `onTranscriptionResult` 句柄分别发送； `isResultActionVisible={false}` 使用转录作为唯一的结果操作。进度保持在活动按钮上，屏幕阅读器提示。待处理的工作阻止解雇和重新启动。

## 降价和编码

`Markdown` 保留GFM表/任务列表，标题和散文渲染，大写模板变量高亮，图像宽度提示(`title="width=560"`)，渲染器/插件覆盖，以及独立的YouTube链接。默认情况下跳过原始HTML。默认情况下，HTTP(S)和相关文档链接在安全的新选项卡中打开，并附有可访问的公告；片段和非web链接保留在当前选项卡中。集 `shouldOpenLinksInNewTab={false}` 或者为应用程序路由提供一个锚呈现器。应用程序拥有自定义插件、URL转换和呈现器的信任策略。

消息列需要 `min-width: 0`;网格轨道使用 `minmax(0, 1fr)`． Markdown和InlineCode包装了长路径和不间断的令牌。InlineCode保留首选分隔符而不更改复制的文本。代码块和表包含它们自己的水平滚动；标记表有标记，键盘可聚焦的滚动组。未标记的栏仍然是带有精确空格的预格式化代码块。

`CodeBlock` 和 `CodeFileHeader` 保留元数据/状态/操作槽、别名、语法高亮、文字纯模式、自定义复制文本和包装控件。声明的散文语言或散文文件扩展名自动包装。 `prefersWrappedCode` 优先于 `shouldWrapContent`，然后是自动散文包装和作用域保存首选项。显式覆盖和只读提供程序隐藏了突变控制。 `diff` 和 `diff-<language>` 栅栏保留源代码结尾、补丁标记和多行语法。 `CodePreferencesControls` 还公开源表面的拆分/统一首选项菜单。紧凑动作保持源精细指针几何形状，并使用44px粗指针目标。

个人适配器将语法和文件状态角色映射到 `jg-personal-ui`现有的主题令牌。泛型语法使用无标记的One-theme回调；供应 `--syntax-foreground` 和 `--syntax-token-{keyword,string,string-expression,comment,function,constant,parameter,punctuation,link}` 来推翻他们。在呈现过程中重用令牌映射，并且记住未更改的Markdown解析器输入。每个语法/样式导入都为它的JavaScript文件命名，因此Node导入不需要更改消费者解析器。

`parseYouTubeVideoUrl` 验证支持的HTTPS单视频链接并返回一个标记标识符。 `YouTubeVideo` 使用固定的隐私增强源，剥离授权的播放参数，并仅通过其显式prop启用自动播放。URL验证/构建重用 `jg-utilities`，保留UI的更窄的路由策略。伪造的无效标识符将导致依赖项的文档化 `INVALID_YOUTUBE_VIDEO_ID` 合同。

## 代码差别

`CodeDiff` 运行下 `UiPreferencesProvider` 和 `ThemeProvider`． 它保留了源元数据、上游查看器控件、样式覆盖、折叠渲染器和响应式统一/拆分首选项。它的运行时是包的捆绑、补丁 `react-diff-viewer-continued@4.2.2`;消费者不配置补丁或安装脚本。上游依赖项提供声明，而运行时导入使用绑定的适配器。React和React DOM仍然是外部的。

有界摘录（最多8192个组合字符和128个组合行）同步呈现，包括在服务器呈现和修订更改期间。较大的比较保留了懒惰的Web Worker路径；显式的 `disableWorker` 保持原意。Worker支持和Blob-worker权限取决于主机环境。 `styles`， `loadingElement`， `infiniteLoading`， `alwaysShowLines`、线偏移、沟渲染器和其他保留的查看器道具仍然可用。分屏视图从 `lg` 默认情况下;较窄的布局使用统一的行。代码包装在固定宽度的单元格内。可选 `tabIndex` 属于固定文件头下面的内容。

被检查的构建在绑定之前验证原始和修补的ESM文件标识，拒绝过时的块，并保留worker的单独动态块。Moldea的补丁没有改变。本地可访问性调整使摘要成为标记组，并为all-lines按钮提供显式名称和展开状态。折叠控件具有本地键盘行为和至少44px的粗指针目标。完整的捆绑许可证发货 `THIRD-PARTY-NOTICES.md`； `pnpm build:viewer --write-notices` 重新生成该文件，普通构建检查它是否过期。构建工具和补丁源位于tarball之外。Turbo的包本地单元和浏览器任务依赖于包构建，因此测试集合总是接收编译后的补丁查看器。在从新签出运行这些任务时使用Turbo。

大差异结果仅为当前查看器输入缓存，与同步路径的单一修订所有权相匹配。一份想念在真正的工作者中重新计算；返回到较旧的版本不会在内存中保留其旧的源/结果。对过时输入的回复不能清除当前版本的加载状态。控制 `alwaysShowLines` 和 `extraLinesSurroundingDiff` 更改重新计算大型比较；运行时行引用使用 `L-1` 和 `R-1` 形式。已检查的构建在验证未更改的源补丁后应用这些本地更正；实际工人回归在修正之前重现了这两种失败。工作保持在查看器的本地，没有跨根缓存或额外的持久性。

## 减价的编辑

`MarkdownEditor` 保留控制 `value`/`onChange`， `supportedTools`，可访问性道具，以及 `auto`/`compact`/`wide` 布局。自动测量所属容器并选择宽度为640px。 `CompactMarkdownEditor` 和 `WideMarkdownEditor` 暴露相同的道具 `layout`． 一个改变 `value` 使用文本末尾的插入符号将文档替换为保持编辑器焦点的一个编辑，并且不返回报告 `onChange`． 导出的所有工具、创作和散文策略保留源命令集；当创作工具受到约束时，现有文档仍然是可读的。

`ChatMarkdownEditor` 保留段落、H1-H3、项目符号/编号列表、粗体/斜体和安全链接格式。HTML被删除，不支持的块变成可读的散文，而图像替代仍然是文本。Paste在解析之前检查绑定的原始输入，在替换草稿之前检查序列化的结果。拒收的浆料原封不动；格式反馈保留到下次编辑。

提供一个正安全整数 `maxLength`，它对不包含Markdown结束的换行符的消息进行计数。 `maxEditorHeight` 默认为256px，必须是正的和有限的，并且被样式表限制为50dvh。 `controlsRef` 公开 `getMarkdown()`， `focus()`, `appendLiteralText(text)`． 文字插入逃避Markdown，通常在准备就绪之前或草稿太长时返回false。通过 `{ allowOverLimit: true }` 保留完整的听写，包括在初始化期间，以便在主输入中进行编辑。只读编辑器拒绝插入。当超过限制时，用户必须阻止按钮和键盘提交。按草稿身份键输入编辑器，以清除内容并在成功提交后撤消历史记录。初始快照保留受控草稿，焦点等待初始化编辑器。使用这些控件组合呼叫者拥有的上传和听写流。

`formattingContainer` 省略时使用内联位置，保留外部位置为null，并将格式化菜单传送到提供的HTMLElement中。现有的 `styles.css` 条目包括在编辑器覆盖之前的Milkdown的通用/帧样式。个人包直接重新导出通用实现并提供共享的JG令牌。

无效配置保留了这些本地错误消息：

-   `ChatMarkdownEditor maxLength must be a positive safe integer.`
-   `ChatMarkdownEditor maxEditorHeight must be a positive finite number.`

## 文档

API引用作为 [API.md](https://unpkg.com/jg-react-ui@0.3.4/API.md)，应用程序端示例为 [RECIPES.md](https://unpkg.com/jg-react-ui@0.3.4/RECIPES.md)． 这些个人使用的包裹没有在公共包裹网站上列出。

## 许可证

麻省理工学院。

## 常见问题

### jg-react-ui 是什么？

以消费者为主题的React组件，带有源自moldea的api、显式的样式契约和可重用的应用程序行为。

### 如何安装 jg-react-ui？

在项目目录运行 npm install jg-react-ui，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19\.2\.4）、react-dom（^19\.2\.4）、tailwindcss（^4\.3\.3）、react-router（^7\.14\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### jg-react-ui 支持 TypeScript 吗？

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

### jg-react-ui 支持 ESM 还是 CommonJS？

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

### jg-react-ui 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.17\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### jg-react-ui 可以商用吗？

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

### jg-react-ui 还在维护吗？

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