# @iyulab/desktop-patterns 中文文档
规范地址：https://npmcn.com/package/%40iyulab/desktop-patterns/
版本：0\.13\.0
npm 元数据更新时间：2026-11-01T11:54:37.146Z
中文译文更新时间：2026-11-01T12:42:47.245Z
软件包许可：MIT
本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40iyulab/desktop-patterns
原文对照：https://npmcn.com/package/%40iyulab/desktop-patterns/?lang=original
项目主页：https://github.com/iyulab/desktop-patterns#readme
源码仓库：https://github.com/iyulab/desktop-patterns
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：72.9 kB，25 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：1 个
- peer 依赖：@iyulab/desktop-compact ^0\.15\.1 \|\| ^0\.16\.0
- 首次发布：2026-09-03T02:46:27.093Z
- 最新版本发布：2026-11-01T11:54:36.812Z
- 已发布版本数：29（近 12 个月 29 个）
## 中文简介
应用程序外壳和结构布局模式组装在上面 [`desktop-compact`](https://github.com/iyulab/desktop-compact)原语。框架无关的自定义元素([点燃](https://lit.dev/))，零内置字符串，每个内容区域都有一个槽。
## 安装
```sh
npm install @iyulab/desktop-patterns
```
也可以使用：`pnpm add @iyulab/desktop-patterns`、`yarn add @iyulab/desktop-patterns`、`bun add @iyulab/desktop-patterns`
## README
# desktop-patterns
应用程序外壳和结构布局模式组装在上面 [`desktop-compact`](https://github.com/iyulab/desktop-compact)原语。体系的中立者自定义 元素([点燃](https://lit.dev/))，零内置字符串，每个内容区域都有一个槽。
仅结构-原子控件（按钮，输入，对话框）属于 `desktop-compact`;本地的 平台集成（文件对话框、托盘、窗口控制）属于桌面运行时本身 适配器层，无论应用使用哪个运行时。这个包本身不调用任何平台API， 并且对任何特定的消费应用程序一无所知。
## 安装
要求节点≥22。
```bash
npm install @iyulab/desktop-patterns @iyulab/desktop-compact
```
只导入你使用的组件——每个船都是它自己的树摇子路径：
```ts
import '@iyulab/desktop-patterns/shell'
import '@iyulab/desktop-patterns/sidebar'
```
或者进口一切通过桶：
```ts
import '@iyulab/desktop-patterns'
```
## 使用
```html
Overview
Main content.
```
`items`/`bottomItems` 是数组，所以它们被设置为JS属性（不是普通的HTML属性）-相同 作为任何Lit自定义元素：
```ts
document.querySelector('#nav')!.items = [
{ id: 'overview', icon: '■', label: 'Overview' },
]
import { desktopMinWidth } from '@iyulab/desktop-patterns/breakpoints' // no elements registered
const shell = document.querySelector('dp-shell')!
const sidebar = document.querySelector('dp-sidebar')!
const toolbar = document.querySelector('dp-toolbar')!
const wide = matchMedia(`(min-width: ${desktopMinWidth}px)`)
let collapsed = false // the consumer's own state: a wide window's sidebar folded to its rail
function sync() {
sidebar.collapsed = collapsed && wide.matches // a drawer always shows the whole sidebar
toolbar.expanded = wide.matches ? !collapsed : shell.sidebarOpen
}
wide.addEventListener('change', sync)
sidebar.addEventListener('dp-sidebar-select', () => {
// consumer owns activeId / routing
})
sidebar.addEventListener('dp-sidebar-activate', () => {
shell.sidebarOpen = false // a drawer gives way to what was picked — the place already shown included
sync()
})
toolbar.addEventListener('dp-toolbar-toggle', () => {
if (wide.matches) collapsed = !collapsed
else shell.sidebarOpen = !shell.sidebarOpen
sync()
})
shell.addEventListener('dp-shell-sidebar-close', () => { shell.sidebarOpen = false; sync() }) // backdrop, Escape
```
在桌面断点(`desktopMinWidth`， 1024px - `desktopMedia` （对于组件的样式） 侧边栏是内容上方的一个抽屉，打开时打开 `sidebar-open` 设置;在它上面 侧边栏位于内容和旁边 `sidebar-open` 改变不了什么。使用相同的工具栏开关 两种宽度：在窄窗中打开抽屉，在宽窗中折叠侧边栏 铁轨倒塌(`dp-sidebar` `collapsed`）. 打开开关 `expanded` 所以辅助技术听到了 它处于哪个状态。消费者拥有两种状态——启动时抽屉关闭，关闭时抽屉关闭 shell问（背景点击，逃离），当一个地方被选中，或一个狭窄的窗口保持覆盖。
外壳控制着窗口的高度，所以文档永远不会滚动——主内容框会滚动。 任何保存和恢复用户正在阅读的位置的操作都会到达该框 `shell.mainElement`;与 `@iyulab/router`，把它交给路由器的滚动恢复： `scrollRestoration: { container: () => document.querySelector('dp-shell')?.mainElement }`.
### 被选中的项目旁边的列表
```html
…the person picked…
```
`dp-list-detail` 把 `list` 槽位旁边默认槽位，各自滚动，列表 `--dp-list-detail-list-width` 宽度(默认情况下侧边栏的宽度——导航、列表和项目读取为 1:1:休息)。在桌面断点下面有一个窗格的空间：项目while `detail-open` 是 设置，否则列表。消费者拥有 `detail-open` -当一个项目被选中时设置它，并给予 该项目返回清除它的方式，如下所示 `desktopMinWidth`.
### 侧边栏项：链接、组、图标、动作
```ts
nav.items = [
{ id: 'overview', icon: '■', label: 'Overview', href: '/overview' }, // href → rendered as
{
id: 'work', label: 'Work', collapsed: false, // a group: a disclosure over its items
items: [{ id: 'runs', icon: '▶', label: 'Runs', href: '/runs' }],
},
]
nav.pinnedItems = [{ id: 'settings', icon: '⚙', label: 'Settings' }] // places kept at the foot of the rail
nav.bottomItems = [
{ id: 'dense', icon: '▤', label: 'Dense mode', pressed: false }, // a toggle: aria-pressed, owned by you
{ id: 'sign-out', icon: '⎋', label: 'Sign out' }, // actions, not places
]
nav.setAttribute('nav-label', 'Main') // names the navigation landmark
```
- **`href`** 将项目呈现为链接，这样路由器的链接拦截器（或浏览器）就会进行导航。 `dp-sidebar-select` 仍然可以发射并且可以取消 `preventDefault()` 取消导航并保留 活动项目。修改后的单击（Ctrl/⌘/Shift/Alt，中间按钮）会在其他地方打开链接，但不选择任何内容。 项目没有 `href` 停留按钮和用户导航 `dp-sidebar-select`.
- **组** （`{ id, label, items, icon?, collapsed? }`)渲染为一个命名的 `role="group"` 根据披露 按钮(`aria-expanded`）. 持有活动项的组始终处于打开状态。在倒塌的铁轨上，每一组 项目显示，由规则分隔。
- **图标**：每个物品的图标是一个插槽，命名为 `icon-` 项目的退路是谁的 `icon` 文本槽任何图标 元素(`