# jg-personal-react-ui 中文文档

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

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

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

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

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

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

## 中文简介

jg品牌的React组件和样式，与没有品牌的jg-react-ui实现共享来自moldea的api。

## 安装

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

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

## README

# jg-personal-react-ui

jg品牌的React组件由共享的jg-react-ui实现支持。

## 安装

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

## 用法

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

那么，进口一次顺风吧 `jg-personal-react-ui/styles.css`。

按钮、徽章、IconTile、警报、它们的组合槽、变体和公共契约都是直接再导出的 `jg-react-ui`。 `JgMark` 是装饰的JG标志，用的 `className` 用于布局和与Astro相同的固定艺术品。从根目录或 `jg-personal-react-ui/components/jg-mark`;在识别品牌链接时，将其与可见文本配对。

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.3/errors/README.md)。

## 控件、窗体和纯文本

表单、菜单、选项卡、工具提示、复制命令、进度、空状态、排版、表格、链接和内联代码都是的直接导出 `jg-react-ui`． 它们的refs、本机属性、插槽、事件别名和取消行为共享相同的实现和上下文。JG样式绑定字段、代码、菜单和反向暗主题角色；集 `font-sans bg-background text-foreground` 在应用程序根目录下。在相关的标签行中保持至少44px的紧凑选择符号，并为溢出表提供一个标记的、可聚焦的可见焦点区域。请参阅合成配方。

## 对话框、抽屉和布局

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保留了本地的语义道具和共享的几何形状。JG将通用表面阴影角色绑定到共享基础。样式表提供源页行距和抽屉行距挂钩；它不会重置文档的调色板或排版。

## 路由和查询恢复

`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`）; 选择和聚焦发挥了它的主要作用。查询客户机、网络适配器、分页限制、应用程序代码映射和路由历史记录仍然是主机所有的。

## 文件上传和音频输入

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

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

`transcribe` 接收捕获的记录并返回文本。用户可以直接发送或先编辑抄本；发送失败会重试已编写的文本，而不会再次转录。提供者操作仍然是调用者所有的，并且应该有自己的截止日期/取消策略。记录/转录错误回调接收诊断异常，而可见反馈使用最近的作用域解析器。七个拥有的音频代码和稳定消息列在 `errors/README.md`;编码提供程序异常保留其诊断标识。取消的许可/转录工作保持沉默，可以重新启动；诊断回调仍在运行。可选的结果回调仍然是可选的。独立审查仍然是默认的。供应 `onTranscriptionApply` 用于主输入 `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` 合同。

## 减价的编辑

`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-personal-react-ui@0.3.3/API.md)，应用程序端示例为 [RECIPES.md](https://unpkg.com/jg-personal-react-ui@0.3.3/RECIPES.md)． 这些个人使用的包裹没有在公共包裹网站上列出。

## 许可证

麻省理工学院。

## 源比较

`CodeDiff`， `CODE_DIFF_LANGUAGES`，而它们的公共类型是直接转口的 `jg-react-ui/components/code-diff`． JG标记提供颜色、排版和表面样式。base会发送检查过的补丁查看器和lazy worker块，因此消费者不需要配置补丁。私人画廊 `/diff` 在两种配色方案中，Route练习折叠、偏好、修订更新、长路径和一个单独的消费者拥有的基础主题。

## 常见问题

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

jg品牌的React组件和样式，与没有品牌的jg-react-ui实现共享来自moldea的api。

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

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

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

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

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

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

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

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

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

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

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

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