# @jsenv/navi 中文文档 规范地址：https://npmcn.com/package/%40jsenv/navi/ 版本：0\.29\.509 npm 元数据更新时间：2026-11-01T14:15:52.494Z 中文译文更新时间：2026-11-01T14:27:53.078Z 软件包许可：MIT 本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40jsenv/navi 原文对照：https://npmcn.com/package/%40jsenv/navi/?lang=original 项目主页：https://github.com/jsenv/core#readme 源码仓库：https://github.com/jsenv/core ## 关键信息（来自 npm 元数据） - 包体积（解压后）：23.4 MB，46 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - 运行依赖：3 个 - peer 依赖：preact ^11\.0\.0-rc\.2，@preact/signals ^2\.11\.2 - 首次发布：2025-07-29T12:54:29.845Z - 最新版本发布：2026-11-01T14:15:52.048Z - 已发布版本数：883（近 12 个月 847 个） ## 中文简介 组件库，包括用于创建前端应用程序的导航 ## 安装 ```sh npm install @jsenv/navi ``` 也可以使用：`pnpm add @jsenv/navi`、`yarn add @jsenv/navi`、`bun add @jsenv/navi` ## README # @jsenv /纳 构建web应用程序的Preact框架：路由、异步数据、REST状态、控件和表单、弹出窗口、手势、布局和文本。每个导出都可以单独使用，但它们被设计成一起工作，一个应用程序通过在任何时候使用它的原语来最大限度地利用navi。 这个页面按区域命名navi提供的内容。每个领域背后的推理都存在 [文档/](https://npmcn.com/package/%40jsenv/navi/docs/), [文档/ AI\_INSTRUCTIONS.md](https://npmcn.com/package/%40jsenv/navi/docs/AI_INSTRUCTIONS.md) 列出每一份文件和阅读它的时间。 ## 路由 路由是基于信号的，这意味着URL状态（包括搜索参数）可以绑定到具有双向同步的信号。更改一个信号，URL更新。导航到一个URL，信号更新。还可以对搜索参数进行验证和键入，因此您总是使用正确的数据形状。 路由是灵活的：您可以创建路由组，以便在多条路由上共享逻辑、状态或UI。支持嵌套路由，其结构自然映射到应用程序的组织方式。 `routeFallback()` 命名未找到的页面。 `Link` 知道它是否指向用户所在的位置，并且 `Nav` 将链接转换为选项卡行，其指示器在选项卡之间移动。一个链接通过它的片段(`#id`): navi等待元素呈现，滚动到它并标记它(`:target`， `data-url-target`）。 `Binder` 将选项卡及其打开的页面绘制为一个形状。 `RouteTravel` 让拇指从一个URL拖到下一个，而不会挂载不匹配的路由。看到 [文档/ navigation.md](https://npmcn.com/package/%40jsenv/navi/docs/navigation.md). ## 转换 导航可以被动画为一个关系，用户可以把它当作地图来读： `defineRouteTransition` 声明一个页面如何让位于另一个页面（幻灯片、封面），浏览器的后退按钮以另一种方式播放。看到 [文档/ route\_transitions.md](https://npmcn.com/package/%40jsenv/navi/docs/route_transitions.md), [文档/ view\_transitions.md](https://npmcn.com/package/%40jsenv/navi/docs/view_transitions.md) 在开始自己的视图转换之前。 `UITransition` 动画显示框内的变化——一个内容取代另一个内容，或者一个加载状态让位于结果——当框从一个大小调整到另一个大小时。 ## 状态 `stateSignal` 信号是否知道更多关于其值的信息：类型、默认值（可能是另一个信号）、约束，例如 `oneOf` 或者 `min`/`max`它生活的地方——记忆， `localStorage` （`persists`)，或者被路由绑定时的URL。 状态导航显示是被绑定的，而不是被回调复制回来的：一个控件，一个弹出窗口，一个选项卡行 `signal` 自己去读和写。看到 [文档/ state\_binding.md](https://npmcn.com/package/%40jsenv/navi/docs/state_binding.md). ## 行动 动作是具有生命周期管理的异步操作——挂起、成功、错误。你可以声明在导航到路由时运行的动作，任何组件都可以通过 `useAsyncData` 反映正在发生的事情：加载状态、结果、错误。无需手动接线。看到 [文档/ actions.md](https://npmcn.com/package/%40jsenv/navi/docs/actions.md), [文档/ data\_states.md](https://npmcn.com/package/%40jsenv/navi/docs/data_states.md) 对于绘制骨架，同一动作的结果和错误。 按需加载的代码是一样的：一个页面的代码 `import()` 是一个路由操作，从url更改时的页面数据开始，并在指向它的链接悬停或聚焦时预取；页面中驻留的组件读取自己的 `useAsyncData(() => import(…))`． 一次等待，一次失败，没有惰性API。看到 [文档/ dynamic\_import.md](https://npmcn.com/package/%40jsenv/navi/docs/dynamic_import.md). 错误分为两种——请求被拒绝和错误——每一种都在自己的地方显示； `ErrorBoundary` 和 `Loading` 是界限。看到 [文档/ error\_handling.md](https://npmcn.com/package/%40jsenv/navi/docs/error_handling.md). ## 其他国家 `resource()` 将REST端点转换为响应式存储：每个谓词一个操作 共享信号存储每个组件读取的数据，并自动失效 在相关操作之间。父/子关系是一流的 `.one`， `.many`， `.scopedOne`， `.scopedMany` 为后端子资源建模，例如 `/games/:id/candidates` 而不是让你手卷。与 `persist`， 最后一个答案在重新加载之后，在网络启动之前再次绘制 的答案。看到 [文档/ resource.md](https://npmcn.com/package/%40jsenv/navi/docs/resource.md). `setNetworkPolicy` 决定请求是否可以全部发出-脱机或 应用程序的任何原因：写操作被搁置，读取操作被商店应答，或者被允许 通过，与它们绑定的控制告诉我们为什么。看到 [文档/ network\_policy.md](https://npmcn.com/package/%40jsenv/navi/docs/network_policy.md). ## 字段和表单 现场组件(`Input` 每种类型，包括复选框和单选， `Select`， `Textarea`， `Picker`)保持自身的价值。在一个 `Form` 它们不需要任何连接：表单在发送时通过相同的操作系统读取它们，当没有任何更改时不发送任何内容。当应用程序需要一个值时，a `signal` 双向绑定。一个 `action` 运行可能失败或需要时间的更改必须引起的更改；这是一种选择，而不是一个领域的连接方式。看到 [文档/ control\_value.md](https://npmcn.com/package/%40jsenv/navi/docs/control_value.md) 和 [文档/ form\_changed.md](https://npmcn.com/package/%40jsenv/navi/docs/form_changed.md). `Picker` 在弹出窗口中选择其值的控件：选项列表、确认或组成一个对象值的多个控件。它的触发器消耗了等待和选择运行的错误。看到 [文档/ control\_object.md](https://npmcn.com/package/%40jsenv/navi/docs/control_object.md). 验证超越了本地浏览器的限制：自定义规则，更好的错误定位，实时反馈，以及在用户完成输入之前不会惩罚用户的用户体验。看到 [文档/ field\_validation.md](https://npmcn.com/package/%40jsenv/navi/docs/field_validation.md). 有些值被移动而不是输入： `Spin` 一次一步地在一个值周围放回和放上路径，然后 `SpinGroup` 使它们中的几个读起来像一个 `TimeSpin` (“07 h30”) `TimeRangeSpin` （“de 7h 21h”，end after start）就是这样构建的。 `Wheel` 滚动选择器是一个手机显示相同的工作，与 `TimeWheel` 和 `TimeRangeWheel` 以此为基础。 `Group` 将多个控件读取为一个框架对象(参见 [文档/ group.md](https://npmcn.com/package/%40jsenv/navi/docs/group.md))， `Editable` 在适当的位置编辑值，即写入值的位置。 ## 列表 `List` 显示一个集合：可以选择、搜索(`createSearch`)，分组和分开，当第一个答案出来时，有一个骨架，当它失败时，错误在它的位置。成千上万行通过 `` 还有一个渲染窗口，当用户回来时，一个列表会记住它在哪里滚动。看到 [文档/ scroll.md](https://npmcn.com/package/%40jsenv/navi/docs/scroll.md)， [文档/ list\_refresh.md](https://npmcn.com/package/%40jsenv/navi/docs/list_refresh.md) 和 [文档/ list\_action.md](https://npmcn.com/package/%40jsenv/navi/docs/list_action.md). ## 表格 一、 `Table` 对于类似电子表格的屏幕：通过拖动重新排序列，调整列和行大小，粘贴前导行和列，以及使用键盘快捷键选择单元格，行和列。 ## 弹出窗口 `Dialog`， `Popover` 和 `SidePanel` 拥有他们是否开放；不同的是触发器——一个按钮(`command` + `commandFor`)，一个手势，一个应用程序状态。弹出窗口可以将压在前面的卡片提起来(`animation="lifting"`)，停靠在一个小触摸屏的边缘，并选择它后面的页面后退多远。弹出窗口，互相移交-得分单元格，菜单栏-站在一个 `PopupGroup`：墙围绕着页面的那个框，按下另一个的触发器关闭打开的弹出框，并在相同的按下打开那个。 `Expandable` 在适当的地方打开，将内容推到下面；几个人共用一个 `signal`，各有千秋 `value`，都是手风琴。 `createSlot` 呈现在另一个地方声明的内容 `SidePanel` 对于整个板，绑定到命名它所显示的状态。看到 [文档/ popup\_open.md](https://npmcn.com/package/%40jsenv/navi/docs/popup_open.md)， [文档/ popup\_backdrop.md](https://npmcn.com/package/%40jsenv/navi/docs/popup_backdrop.md)， [文档/ popup\_lift.md](https://npmcn.com/package/%40jsenv/navi/docs/popup_lift.md) 和 [文档/ dialog\_shape.md](https://npmcn.com/package/%40jsenv/navi/docs/dialog_shape.md). 一个标注(`openCallout`)指向一个元素来说明它的一些东西——一个验证消息，一个被拒绝的按。 ## 手势 一个手势是命名的，而不是用手读的：手势 `interactions` Prop在每个组件上都可用，可以通过一个动作回答滑动、按住、双击和键盘快捷键。元素带 `move`， `reorder`， `land`， `toss` 和 `leave`，然后对一个表面进行平移和缩放 `pan`/`zoom`． 触控、鼠标和笔共享一种谁拥有一台印刷机的模式。看到 [文档/ interactions.md](https://npmcn.com/package/%40jsenv/navi/docs/interactions.md)， [文档/ drag\_interactions.md](https://npmcn.com/package/%40jsenv/navi/docs/drag_interactions.md)， [文档/ pan\_zoom.md](https://npmcn.com/package/%40jsenv/navi/docs/pan_zoom.md) 和 [文档/ drag\_to\_travel.md](https://npmcn.com/package/%40jsenv/navi/docs/drag_to_travel.md). 谁握着键盘，焦点环是否显示，这些都是在每个组件的一个地方决定的。看到 [文档/ autofocus.md](https://npmcn.com/package/%40jsenv/navi/docs/autofocus.md). ## 布局 **`Box`** 是主布局原语。它用一个更友好的API包装了CSS Flexbox： `flex` 对于水平布局， `flex="y"` 对于垂直(轴上的东西排列，而不是猜测什么 `flex-direction: column` 视觉上)。支持 `grid`， `inline`，对齐via `alignX`/`alignY`，以及间距道具。 `FixedBar` 在窗口的边缘钉上一条线，给内容留出空间，清除缺口和虚拟键盘(见 [文档/ safe\_area.md](https://npmcn.com/package/%40jsenv/navi/docs/safe_area.md)）。 `SlideContainer` 用于保存在一个方框中相互替换、拖动或绑定到URL的幻灯片。 `CardLayout`， `StepList` 和 `Separator` 覆盖屏幕通常形状的其余部分；孩子之间的规矩是 `separator` 在一个 `Box` （节点，或间隙索引的函数）或 `List` （`true` 对于默认行也是如此)。 组件的样式来自 `@layer navi` 和 `--navi-*` 令牌，所以一个应用程序主题和一个简单的CSS规则毫不费力地获胜。看到 [文档/ css\_architecture.md](https://npmcn.com/package/%40jsenv/navi/docs/css_architecture.md). ## 文本& i18n **`Text`** 以及相关成分(`Title`， `Paragraph`， `Code`， `Caption`)在整个应用程序中一致地处理排版-包括行中非文本的部分：图标，计数，截断(`maxLines`)、骨架以及线条可能断掉的地方。价值观有自己的组成部分： `Time`， `TimeRange`， `Quantity`， `Unit`， `Meter`， `Badge`， `BadgeList`, `BadgeCount` 为了一个单词旁边的计数。看到 [文档/ typography.md](https://npmcn.com/package/%40jsenv/navi/docs/typography.md). 在web项目中，图标是一个经常缺失或令人痛苦的部分。这个 `Icon` 组件使图标表现得像文本一样——它们随字体大小缩放，继承颜色，并在任何布局中自然对齐。没有大小技巧，没有SVG争论。 `interpolateText`/`Interpolate` 保持包含值的句子可读为一个字符串，并且 `createI18n` 给应用程序一个单独的地方来保存它的措辞——即使只有一种语言也值得。 `naviI18n` 是navi自己的文本（验证消息、按钮标签、相对时间）可以被覆盖或翻译的地方。这个 `format*` 助手为用户的语言编写日期、时间、持续时间和数字。看到 [文档/ i18n.md](https://npmcn.com/package/%40jsenv/navi/docs/i18n.md). * * * 以《塞尔达传说》中的精灵向导Navi命名——它可以帮助你浏览构建现代web应用程序的复杂性。 ## 常见问题 ### @jsenv/navi 是什么？ 组件库，包括用于创建前端应用程序的导航 ### 如何安装 @jsenv/navi？ 在项目目录运行 npm install @jsenv/navi，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：preact（^11\.0\.0-rc\.2）、@preact/signals（^2\.11\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @jsenv/navi 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/jsenv\_\_navi 是否存在。 ### @jsenv/navi 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @jsenv/navi 可以商用吗？ @jsenv/navi 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @jsenv/navi 还在维护吗？ 最新版本 0\.29\.509 发布于 2026/11/01（1 天前）；至今共发布 883 个版本，其中过去 12 个月发布了 847 个；首次发布于 2025/07/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。