newbie
/
slot.nvim
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

rename: QQdock.nvim → slot.nvim 

Module: require('QQdock') → require('slot')
Class:  QdockTerm → SlotTerm
Plugin: plugin/QQdock.lua → plugin/slot.lua
Help:   :help QQdock → :help slot
Debug:  'QQdock:' prefix → 'slot:'
This commit is contained in:
QQ 2026-06-17 16:56:37 +08:00
parent 45baf3c996
commit 17b917fb53
4 changed files with 68 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
README.md
View File

@ -1,7 +1,9 @@
# QQdock.nvim # slot.nvim
持久化自适应终端 Dock — 无外部依赖，基于 Neovim 原生终端。 持久化自适应终端 Dock — 无外部依赖，基于 Neovim 原生终端。
像电脑扩展槽一样：每个命令（shell、reasonix、lazygit、codex…）占用一个 slot，toggle 切换显隐，进程不中断。
横屏自动右侧分屏，竖屏自动下方分屏。没打开文件时直接占用主窗口。`<C-\><C-\>` 隐藏，对话还在。 横屏自动右侧分屏，竖屏自动下方分屏。没打开文件时直接占用主窗口。`<C-\><C-\>` 隐藏，对话还在。
## 安装 ## 安装
@ -9,10 +11,10 @@
```lua ```lua
-- lazy.nvim -- lazy.nvim
{ {
'newbie/QQdock.nvim', 'newbie/slot.nvim',
url = 'https://github.com/newbie/QQdock.nvim', url = 'https://github.com/newbie/slot.nvim',
config = function() config = function()
require('QQdock').setup({ require('slot').setup({
size = { size = {
horizontal = 10, -- 竖屏下方终端高度（行数，nil = 自动） horizontal = 10, -- 竖屏下方终端高度（行数，nil = 自动）
vertical = 40, -- 横屏右侧终端宽度（列数，nil = 自动） vertical = 40, -- 横屏右侧终端宽度（列数，nil = 自动）
@ -37,7 +39,7 @@
添加新工具只需在 `commands` 和 `keymaps` 各加一行，键名一致即可： 添加新工具只需在 `commands` 和 `keymaps` 各加一行，键名一致即可：
```lua ```lua
require('QQdock').setup({ require('slot').setup({
commands = { commands = {
reasonix = 'reasonix', reasonix = 'reasonix',
lazygit = 'lazygit', lazygit = 'lazygit',
@ -68,10 +70,10 @@ commands = {
不想用某个功能就不写对应字段。完全不传 `keymaps` 则不注册任何快捷键，可手动绑定： 不想用某个功能就不写对应字段。完全不传 `keymaps` 则不注册任何快捷键，可手动绑定：
```lua ```lua
local Q = require('QQdock') local S = require('slot')
vim.keymap.set('n', '<leader>s', Q.shell, { noremap = true }) vim.keymap.set('n', '<leader>s', S.shell, { noremap = true })
vim.keymap.set('n', '<leader>r', function() Q.open('reasonix') end) vim.keymap.set('n', '<leader>r', function() S.open('reasonix') end)
vim.keymap.set('n', '<leader>cx', function() Q.open('codex') end) vim.keymap.set('n', '<leader>cx', function() S.open('codex') end)
``` ```
## 终端内隐藏键 ## 终端内隐藏键
@ -93,9 +95,9 @@ vim.keymap.set('n', '<leader>cx', function() Q.open('codex') end)
| 函数 | 参数 | 作用 | | 函数 | 参数 | 作用 |
|------|------|------| |------|------|------|
| `Q.setup(opts)` | opts | 配置尺寸、快捷键、命令映射 | | `S.setup(opts)` | opts | 配置尺寸、快捷键、命令映射 |
| `Q.shell()` | — | 打开/关闭持久 shell | | `S.shell()` | — | 打开/关闭持久 shell |
| `Q.open(cmd)` | cmd | 打开/关闭指定命令的持久终端 | | `S.open(cmd)` | cmd | 打开/关闭指定命令的持久终端 |
### setup 参数 ### setup 参数
@ -114,7 +116,7 @@ vim.keymap.set('n', '<leader>cx', function() Q.open('codex') end)
- **零外部依赖** — 基于 `vim.fn.termopen` 原生终端 - **零外部依赖** — 基于 `vim.fn.termopen` 原生终端
- **持久化** — toggle 显隐，终端进程不中断 - **持久化** — toggle 显隐，终端进程不中断
- **自适应布局** — 横屏右分、竖屏下分、无文件占主窗 - **自适应布局** — 横屏右分、竖屏下分、无文件占主窗
- **单文件** — `lua/QQdock/init.lua` ~220 行 - **单文件** — `lua/slot/init.lua` ~220 行
## 协议 ## 协议

88
doc/QQdock.txt → doc/slot.txt
View File

@ -1,26 +1,30 @@
*QQdock.nvim.txt* Persistent Adaptive Terminal Dock *slot.nvim.txt* Persistent Adaptive Terminal Dock
Author: newbie <https://git.qyhhh.top/newbie/QQdock.nvim> Author: newbie <https://github.com/newbie/slot.nvim>
License: MIT License: MIT
============================================================================== ==============================================================================
CONTENTS *QQdock-contents* CONTENTS *slot-contents*
1. Introduction .............................. |QQdock-intro| 1. Introduction .............................. |slot-intro|
2. Installation .............................. |QQdock-install| 2. Installation .............................. |slot-install|
3. Configuration ............................. |QQdock-config| 3. Configuration ............................. |slot-config|
4. Usage ..................................... |QQdock-usage| 4. Usage ..................................... |slot-usage|
5. API ....................................... |QQdock-api| 5. API ....................................... |slot-api|
6. Layout Logic .............................. |QQdock-layout| 6. Layout Logic .............................. |slot-layout|
7. Keymaps ................................... |QQdock-keymaps| 7. Keymaps ................................... |slot-keymaps|
============================================================================== ==============================================================================
INTRODUCTION *QQdock-intro* INTRODUCTION *slot-intro*
QQdock.nvim is a zero-dependency, persistent terminal dock for Neovim. It uses slot.nvim is a zero-dependency, persistent terminal dock for Neovim. It uses
Neovim's native `vim.fn.termopen()` — no external plugins required. Neovim's native `vim.fn.termopen()` — no external plugins required.
Think of it like expansion slots in a computer: each command (shell, reasonix,
lazygit, codex, btop, …) gets its own dedicated slot. Toggle a slot to bring
its terminal panel in/out of view; the process keeps running in the background.
Key features: Key features:
- **Persistent** — toggle hide/show, terminal process keeps running. - **Persistent** — toggle hide/show, terminal process keeps running.
@ -33,25 +37,25 @@ Key features:
- **Single file** — ~220 lines of Lua. - **Single file** — ~220 lines of Lua.
============================================================================== ==============================================================================
INSTALLATION *QQdock-install* INSTALLATION *slot-install*
Using lazy.nvim >~ Using lazy.nvim >~
{ {
'newbie/QQdock.nvim', 'newbie/slot.nvim',
url = 'https://github.com/newbie/QQdock.nvim', url = 'https://github.com/newbie/slot.nvim',
config = function() config = function()
require('QQdock').setup({}) require('slot').setup({})
end, end,
} }
No dependencies required. No dependencies required.
============================================================================== ==============================================================================
CONFIGURATION *QQdock-config* CONFIGURATION *slot-config*
QQdock.setup({opts}) accepts the following options: slot.setup({opts}) accepts the following options:
require('QQdock').setup({ require('slot').setup({
size = { size = {
horizontal = nil, -- terminal height in rows (nil = auto) horizontal = nil, -- terminal height in rows (nil = auto)
vertical = nil, -- terminal width in columns (nil = auto) vertical = nil, -- terminal width in columns (nil = auto)
@ -77,49 +81,49 @@ If `keymaps` is empty or omitted, no keymaps are registered. You can bind
everything manually via the API. everything manually via the API.
============================================================================== ==============================================================================
USAGE *QQdock-usage* USAGE *slot-usage*
*QQdock.shell* *slot.shell*
QQdock.shell()~ slot.shell()~
Open/close a persistent plain shell. Equivalent to `QQdock.open(nil)`. Open/close a persistent plain shell. Equivalent to `slot.open(nil)`.
*QQdock.open* *slot.open*
QQdock.open({cmd})~ slot.open({cmd})~
Open/close a persistent terminal running the given command. Each unique Open/close a persistent terminal running the given command. Each unique
{cmd} gets its own cached terminal instance. {cmd} gets its own cached terminal instance.
Examples: > Examples: >
local Q = require('QQdock') local S = require('slot')
Q.shell() S.shell()
Q.open('reasonix') S.open('reasonix')
Q.open('lazygit') S.open('lazygit')
Q.open('btop') S.open('btop')
Q.open('yazi') S.open('yazi')
Inside any terminal, press <C-\><C-\> (Ctrl+\\ twice) to hide it. Inside any terminal, press <C-\><C-\> (Ctrl+\\ twice) to hide it.
The process keeps running in the background. The process keeps running in the background.
============================================================================== ==============================================================================
API *QQdock-api* API *slot-api*
QQdock.setup({opts}) *QQdock.setup* slot.setup({opts}) *slot.setup*
Configure and register keymaps. Call once, typically in your plugin Configure and register keymaps. Call once, typically in your plugin
manager's `config` function. manager's `config` function.
Parameters: ~ Parameters: ~
{opts} (table) Configuration table, see |QQdock-config|. {opts} (table) Configuration table, see |slot-config|.
QQdock.shell() *QQdock.shell* slot.shell() *slot.shell*
Toggle a plain shell terminal. Shortcut for `QQdock.open(nil)`. Toggle a plain shell terminal. Shortcut for `slot.open(nil)`.
QQdock.open({cmd}) *QQdock.open* slot.open({cmd}) *slot.open*
Toggle a persistent terminal for the given command. Toggle a persistent terminal for the given command.
Parameters: ~ Parameters: ~
{cmd} (string|nil) Shell command to run, or nil for default shell. {cmd} (string|nil) Shell command to run, or nil for default shell.
============================================================================== ==============================================================================
LAYOUT LOGIC *QQdock-layout* LAYOUT LOGIC *slot-layout*
The layout is determined automatically based on the current window dimensions: The layout is determined automatically based on the current window dimensions:
@ -135,14 +139,14 @@ without disrupting the rest of the tabpage layout.
Set `debug = true` to see layout decisions in `:messages`. Set `debug = true` to see layout decisions in `:messages`.
============================================================================== ==============================================================================
KEYMAPS *QQdock-keymaps* KEYMAPS *slot-keymaps*
*QQdock-ctrl-backslash* *slot-ctrl-backslash*
<C-\><C-\> (terminal mode)~ <C-\><C-\> (terminal mode)~
Hide the current terminal. Bound automatically in every QQdock terminal Hide the current terminal. Bound automatically in every slot terminal
buffer. Does not affect TUI programs that use Ctrl+\ for other purposes. buffer. Does not affect TUI programs that use Ctrl+\ for other purposes.
Custom keymaps are defined in the `keymaps` table passed to |QQdock.setup|. Custom keymaps are defined in the `keymaps` table passed to |slot.setup|.
Each entry is {mode, lhs}. Key names must match entries in `commands`. Each entry is {mode, lhs}. Key names must match entries in `commands`.
The `shell` and `shell_i` keys are special and are not driven by `commands`. The `shell` and `shell_i` keys are special and are not driven by `commands`.

14
lua/QQdock/init.lua → lua/slot/init.lua
View File

@ -1,9 +1,9 @@
-- QQdock.nvim — Persistent adaptive terminal dock -- slot.nvim — Persistent adaptive terminal dock
-- --
-- 特性：持久化终端实例、自适应窗口方向（横屏右分屏/竖屏下分屏）、基于 Neovim 原生终端 -- 特性：持久化终端实例、自适应窗口方向（横屏右分屏/竖屏下分屏）、基于 Neovim 原生终端
-- --
-- 配置（可选）： -- 配置（可选）：
-- require('QQdock').setup({ -- require('slot').setup({
-- size = { -- size = {
-- horizontal = 10, -- 竖屏下方终端高度（行数） -- horizontal = 10, -- 竖屏下方终端高度（行数）
-- vertical = 40, -- 横屏右侧终端宽度（列数） -- vertical = 40, -- 横屏右侧终端宽度（列数）
@ -23,7 +23,7 @@
-- }) -- })
-- --
-- 用法： -- 用法：
-- local Q = require('QQdock') -- local Q = require('slot')
-- Q.shell() -- 打开/关闭普通 shell -- Q.shell() -- 打开/关闭普通 shell
-- Q.open('reasonix') -- 打开/关闭 Reasonix -- Q.open('reasonix') -- 打开/关闭 Reasonix
-- Q.open('lazygit') -- 打开/关闭 lazygit -- Q.open('lazygit') -- 打开/关闭 lazygit
@ -43,7 +43,7 @@ local config = {
debug = false, debug = false,
} }
---@class QdockTerm ---@class SlotTerm
---@field bufnr integer ---@field bufnr integer
---@field winid integer? ---@field winid integer?
---@field job_id integer ---@field job_id integer
@ -51,7 +51,7 @@ local config = {
---@field borrowed boolean? ---@field borrowed boolean?
---@field original_bufnr integer? ---@field original_bufnr integer?
---@type table<string, QdockTerm> ---@type table<string, SlotTerm>>
local terms = {} -- 缓存终端实例，key 是命令名（nil = 普通 shell → '__shell__'） local terms = {} -- 缓存终端实例，key 是命令名（nil = 普通 shell → '__shell__'）
--- 基于当前窗口宽高返回 { direction, size } --- 基于当前窗口宽高返回 { direction, size }
@ -118,7 +118,7 @@ function M.open(cmd)
term.borrowed = nil term.borrowed = nil
else else
if config.debug then if config.debug then
vim.notify('QQdock: hide [' .. name .. ']', vim.log.levels.INFO) vim.notify('slot: hide [' .. name .. ']', vim.log.levels.INFO)
end end
if term.borrowed then if term.borrowed then
-- 占了主窗口 → 换回原始空 buffer（如果还在的话，否则关窗） -- 占了主窗口 → 换回原始空 buffer（如果还在的话，否则关窗）
@ -150,7 +150,7 @@ function M.open(cmd)
local height = vim.api.nvim_win_get_height(0) local height = vim.api.nvim_win_get_height(0)
local mode = use_main and 'main' or direction local mode = use_main and 'main' or direction
vim.notify( vim.notify(
string.format('QQdock: %dx%d → %s %d [%s]', width, height, mode, size, name), string.format('slot: %dx%d → %s %d [%s]', width, height, mode, size, name),
vim.log.levels.INFO vim.log.levels.INFO
) )
end end

0
plugin/QQdock.lua → plugin/slot.lua
View File