UI 增强

dock

AKS1st/dock · ★ 10

AKS1st

DSH Web 工作台基座插件:提供 VSCode 风格布局外壳(活动栏/侧边栏/编辑器区/面板/状态栏)和 ctx.workbench 开放注册表,供功能插件挂载面板、视图与命令。

许可证
MIT
收录
2026-08-23
维护状态
active
安装方式
npm
npm
dock-base

尚无 manifest 静态检查记录;收录不等于已完成兼容性或安全审查。

安装

dsh plugin --profile web add dock-base

npm 安装 dock-base 基座(作者推荐);文件/Git/终端等能力需另装 dock-* 系列包。GitHub 入口为备选,DSH >=0.1.3-alpha.2 为作者历史声明

安装与环境配置指引、插件开发教程见 DSH 中文社区文档 ↗

项目说明

原始 README · 正文语言:中文 · 阅读英文 README

目录
  1. 功能
  2. 推荐搭配插件(可组合,按需安装)
  3. 社区插件(第三方,本仓库不维护)
  4. 设置 API
  5. 通用设置
  6. 依赖
  7. 安装
  8. 开发
  9. 插件契约
  10. License

English

DSH 生态中最好的工作台基座插件 —— 没有之一。 别人做工作台是在造轮子,dock 直接把 VSCode 级别的布局外壳、开放注册表和即插即用的插件生态端到你面前:想要文件浏览器?装一个。想要 Git 图?再装一个。你的 DSH 从此拥有一整个 IDE 级工作台,而 dock 就是那个把一切拼起来的奇迹基座。

DSH Web 工作台基础插件:提供 VSCode 风格布局外壳(活动栏 / 侧边栏 / 编辑器区 / 面板 / 状态栏),并通过注册表服务 ctx.workbench 让功能插件挂载面板、编辑器视图、活动项、状态项与命令。本插件是 dock 系列的基础:dock-files、dock-editor、dock-images、dock-markdown、dock-git 都依赖它提供的工作台外壳。

功能

  • 活动栏:左侧垂直条带,可注册图标项,点击切换侧边栏面板。
  • 侧边栏:承载功能面板(文件浏览、Git 启动器等)。
  • 编辑器区:多标签编辑器视图(文件查看器、Git 提交图等)。
  • 停靠模式:整个工作台可停靠在屏幕四边,支持悬浮窗口(独立浮窗,可拖动/缩放)。
  • 状态栏:底部状态项注册。
  • 命令系统:executeCommand 命令注册与调用。
  • 布局持久化:面板/悬浮窗口布局保存在 localStorage,刷新后恢复。
  • 设置窗口:内置设置对话框展示各插件注册的设置项;支持校验、排序、键盘焦点管理与跨刷新持久化。
  • 开放注册表:registerActivityBarItem / registerPanel / registerEditorView / registerStatusBarItem / registerCommand / registerSetting,全部返回反注册函数,配合 ctx.effect 使用可随插件停用自动清理。

推荐搭配插件(可组合,按需安装)

dock 基座只提供工作台外壳,不附带文件浏览、编辑等具体能力——这些交给功能插件。下面的推荐一条一条列清楚:全部可选、可自由组合,完全按你的场景按需安装,不需要全部装齐。

  1. dock-files — 文件浏览器。在侧边栏挂载文件面板,浏览会话工作目录,支持新建/重命名/复制粘贴/删除/拖放导入、粘贴本地文件与剪贴板图片。想浏览和操作文件时再装它。
  2. dock-editor — 文本查看/编辑器。撤销重做、Ctrl+S 保存、未保存确认、二进制检测,是 dock-files 的默认文本查看器。想编辑文本时再装它(需要 dock-files)。
  3. dock-images — 图片查看器。支持 PNG/JPEG/GIF/WebP/BMP/SVG/ICO/AVIF,SVG 安全渲染。需要看图时再装它(需要 dock-files)。
  4. dock-markdown — Markdown 查看器。md/markdown/mdx 渲染、文档大纲、相对路径资源解析、一键切换编辑。经常读文档/README 时再装它(需要 dock-files 与 dock-editor)。
  5. dock-git — Git 历史可视化。泳道式提交图、分支/标签管理、暂存/提交/推送、远端操作。在仓库里干活时再装它,与文件浏览完全独立。
  6. dock-media — 音频/视频播放器。音频走音乐播放器界面,视频支持全屏,媒体通过 HTTP Range 流式加载,支持拖动进度与大文件。要播放媒体文件时再装它(需要 dock-files)。
  7. dock-spreadsheet — 只读表格查看器。XLSX / XLS / ODS / CSV / TSV,表头冻结与行列定位。要查看表格时再装它(需要 dock-files)。

组合建议(仅供参考,绝不是必须):

场景 安装
只想浏览文件 dock + dock-files
浏览 + 编辑文本 dock + dock-files + dock-editor
完整文件工作台 dock + dock-files + dock-editor + dock-images + dock-markdown
需要管理 Git 以上任意组合 + dock-git

只装 dock 本身也完全没问题——它就是一个干净的工作台外壳,等你随时往里加零件。

社区插件(第三方,本仓库不维护)

以下是社区基于 dock 契约开发的插件。列出来不代表背书,安装前请自行审阅其代码:

想把自己的 dock 插件加进这个列表,欢迎开 issue 或直接提 PR。

设置 API

从 0.2.0 起,工作台公开设置注册 API。功能插件通过 ctx.workbench.registerSetting 注册设置项;返回的反注册函数应交给 ctx.effect,这样插件停用或热更新时会自动移除注册。设置窗口会按 order(再按 id)排序,编辑器只接收当前值、onChange 回调和当前语言,并在写入前执行 validate:

ctx.effect(() => ctx.workbench.registerSetting({
  id: 'my-plugin:compact',
  pluginId: 'my-plugin',
  // 文案可以是字符串,也可以是按语言求值的工厂函数
  title: (locale) => locale === 'zh' ? '紧凑模式' : 'Compact mode',
  defaultValue: false,
  component: CompactToggle,
  validate: (value): value is boolean => typeof value === 'boolean',
}))

pluginId 决定设置显示在哪个插件的设置页里。插件还应通过 registerPlugin({ id, title, description, icon, hasEntry }) 注册元数据,设置窗口才能列出它(没有图标时使用 dock 自带的通用插件图标)。有 dock 入口(hasEntry: true)的插件,列表中会提供“打开”按钮和“在 dock 中显示”开关;入口隐藏后仍可从设置里打开。

用户可从工作台打开设置窗口;设置值保存在 localStorage 的 dock:settings 中,刷新后恢复。存储不可用或数据损坏时,工作台使用内存值和默认值继续运行。插件也可通过 getSetting / setSetting / onDidChangeSetting 读取、更新和订阅设置变化。

通用设置

dock 自身在设置窗口的“通用设置”里提供位置、自动隐藏、“为 dock 预留空间”和两档放大倍数。dock 栏末尾的 dock 图标点开就是设置窗口:

  • Dock 位置:左/右/上/下四联切换,右键菜单里的停靠项与它共享同一份状态。
  • 自动隐藏:鼠标远离后以滑出、缩放和淡化动画收起;停靠边缘保留可见提示条,移入边缘即可展开。关闭自动隐藏时,即使 dock 正在隐藏也会立即强制展开。
  • 为 dock 预留空间(默认开启):只将右停靠时的会话进度导航栏向左移动实测 dock 宽度 + 24px,不改变页面宽度或滚动条位置;通过 Harness 提供的 data-turn-navigator 标记定位导航栏。dock 栏尺寸变化、窗口缩放和该开关切换时都会重新计算,关闭该开关时偏移归零。
  • 悬停图标放大 / 相邻图标放大(默认 1.6× / 1.2×):dock 模式下的鱼眼放大倍数,两个滑块分别在 1.0–2.5× 和 1.0–2.0× 之间以 0.05 步进调节,拖动即时生效;相邻倍数不会超过悬停倍数。
  • Dock 图标:dock 栏末尾的 dock 图标(三个方块立在横栏上)点开即设置窗口。它和其他入口一样可以在“插件 → 入口 → Dock”里隐藏;隐藏后仍可右键 dock 栏打开设置。

依赖

依赖 类型 说明
DSH Web 环境 运行时 必需,最低版本 >=0.1.3-alpha.2。客户端平台为 Web,通过 dsh plugin --profile web add 安装
cordis ^4.0.0-rc.7 peer 插件框架(DSH 自带)
react / react-dom ^18.2.0 peer(可选) 客户端渲染需要;未提供时工作台 UI 不激活

dock 自身不依赖任何其他 dock 系列插件——它是系列的地基,反过来其他五个都依赖它。

安装

需要 DSH Web 环境(dsh plugin --profile web add),且 Harness 版本至少为 0.1.3-alpha.2。

推荐从 npm registry 安装:

dsh plugin --profile web add dock-base
dsh plugin --profile web add dock-files
dsh plugin --profile web add dock-editor
dsh plugin --profile web add dock-images
dsh plugin --profile web add dock-markdown
dsh plugin --profile web add dock-git

或通过 GitHub 安装(备选):

dsh plugin --profile web add github:AKS1st/dock
dsh plugin --profile web add github:AKS1st/dock-files
dsh plugin --profile web add github:AKS1st/dock-editor
dsh plugin --profile web add github:AKS1st/dock-images
dsh plugin --profile web add github:AKS1st/dock-markdown
dsh plugin --profile web add github:AKS1st/dock-git

或按你的 profile 依赖写法使用 link: 本地安装。dock 提供 ctx.workbench 服务;功能插件通过该服务协作,安装顺序不敏感(Cordis 按依赖激活)。

开发

pnpm install
pnpm run build    # tsc 类型声明 + tsdown 打包
pnpm run check    # 仅类型检查

插件契约

src/client/contract.ts 是工作台对外契约(WorkbenchService、ViewProps、EditorOpenSeed 等)。功能插件只做类型导入(编译期擦除),运行时全部通过 ctx.workbench 方法调用协作。各功能插件内有一份该契约的 vendored 副本,改动本文件时需同步更新。

License

MIT