gdh1995/vimium-c

Vimium C - All by Keyboard

Visit on Firefox Add-ons / Microsoft Edge Add-ons / Chrome Web Store

A Customized Vimium (to click web page content and manipulate browser windows using only keyboard) having contextual mapping, global shortcuts, command sequences, Chinese support and injection functionality, in C-style code for quicker action and less resource cost.

Vimium 的一款修改版（可以用键盘点击网页内容、操作浏览器窗口），添加了完整的中文支持、分场景映射、全局快捷键和命令序列功能，还能运行在某些接受 Vimium C 的扩展程序的私有页面里，并且对CPU和内存资源的消耗很低。

阅读中文介绍 (description in Chinese) 。

This project is mainly developed and maintained by gdh1995 (Gong Dahan), and open-sourced under the Apache-2.0 license.

本项目主要由 gdh1995（宫大汉）开发并维护，且以 Apache-2.0 许可协议 开源。

It (the released version) supports the new Microsoft Edge, Google Chrome and other Chromium-based browsers whose core versions are >= 102, and has a perfect support for a recent Firefox (since version 101.0, desktop). It can even run on Microsoft Edge (EdgeHTML), though there're still some errors. If re-compiled from the source code, Vimium C is able to support Chromium 32108 and Firefox 63100.

它支持内核版本不低于 102 的新版 Microsoft Edge、Google Chrome 和其它以 Chromium 为内核的浏览器， 同时也能完美运行在近些年发布的 Firefox 101（桌面版）和更高版本上，甚至在 Edge (EdgeHTML 内核) 上也能正常执行大部分命令。 如果从源码重新编译，Vimum C 还可以支持 Chromium 32108 和 Firefox 63100。

This project is hosted on https://github.com/gdh1995/vimium-c and https://gitee.com/gdh1995/vimium-c .

Some old code of Vimium C was under the MIT license, and you may get it in https://github.com/gdh1995/vimium-c/tree/MIT-licensed-v1 .

Vimium C 的部分旧代码以 MIT 许可协议开源，可以前往 https://github.com/gdh1995/vimium-c/tree/MIT-licensed-v1 获得源码。

An old name of this project is "Vimium++", which has been given up on 2018-08-21.

Keyboard Bindings

This section is modified from philc/vimium 's.

Modifier keys are specified as <c-x>, <m-x>, and <a-x> for Ctrl+x, Meta+x, and Alt+x respectively. For Shift+X and Ctrl+Shift+X, just type X and <c-s-x>. See the next section for how to customize these bindings.

Once you have Vimium C installed, you can see this list of key bindings at any time by typing ?.

Navigating the current page:

?       show the help dialog for a list of all available keys
h       scroll left
j       scroll down
k       scroll up
l       scroll right
gg      scroll to top of the page
G       scroll to bottom of the page
d       scroll down half a page
u       scroll up half a page
f       show hints for links and buttons to open in the current tab
F       show link hints and open a link in a new tab
r       reload
gs      view source
i       enter insert mode -- all commands will be ignored until you hit Esc to exit
yy      copy the current url to the clipboard
yf      copy a link url to the clipboard
gf      cycle forward to the next frame
gF      focus the main/top frame

Navigating to new pages:

o       open URL, bookmark, or history entry, on an English letter "o"
O       open URL, bookmark, history entry in a new tab, on an English letter "O"
b       open bookmark
B       open bookmark in a new tab

Using find:

/       enter find mode
          -- type your search query and hit enter to search, or Esc to cancel
n       cycle forward to the next find match
N       cycle backward to the previous find match

For advanced usage, see regular expressions on the wiki.

Navigating your history:

H       go back in history
L       go forward in history

Manipulating tabs:

J, gT   go one tab left
K, gt   go one tab right
g0      go to the first tab. Use `ng0` to go to n-th tab, on `g` and a number character of `0`
g$      go to the last tab
^       visit the previously-visited tab
t       create tab
yt      duplicate current tab
x       close current tab
X       restore closed tab (i.e. unwind the `x` command)
T       search through your open tabs
W       move current tab to new window
<a-p>   pin/unpin current tab

Using marks:

ma, mA  set local mark "a" (global mark "A")
`a, `A  jump to local mark "a" (global mark "A")
``      jump back to the position before the previous jump
          -- that is, before the previous gg, G, n, N, / or `a

Additional advanced browsing commands:

]], [[  follow the link labeled "next or ">" ("previous" or "<">)
          - helpful for browsing paginated sites
<a-f>   open multiple links in a new tab
gi      focus the first (or n-th) text input box on the page. Use <tab> to cycle through options.
gu      go up one level in the URL hierarchy
gU      go up to root of the URL hierarchy
ge      edit the current URL
gE      edit the current URL and open in a new tab
zH      scroll all the way left
zL      scroll all the way right
v       enter visual mode; use p/P to paste-and-go, use y to yank, use v/c/V to toggle visual/line/caret modes
V       enter visual line mode
yc      select a first word of a sentence and enter visual mode

Vimium C supports command repetition so, for example, hitting 5t will open 5 tabs in rapid succession. <esc> (or <c-[>) will clear any partial commands in the queue and will also exit insert and find modes.

There are some advanced commands which aren't documented here; refer to the help dialog (type ?) for a full list.

Custom Key Mappings

This section is modified from philc/vimium 's.

When you have just installed Vimium C, it will open a new tab to show its default key mappings, and you may also open Vimium C's options page and press ? (usually it's Shift+/) to show those mappings again.

You may remap or unmap any of the default key bindings in the "Custom key mappings" on the options page.

Enter one of the following key mapping commands per line:

• map <key> command: Maps a key to a Vimium C command. Overrides web pages' default behavior (if any).
• mapKey <key> <another_key>: Let Vimium C treat key as another key. Can not affect your browser or web pages.
• unmap <key>: Unmaps a key and restores the default behavior (if any).
• unmapAll: Unmaps all bindings. This is useful if you want to completely wipe Vimium C's default commands and start from scratch with your own setup.

Examples:

• map r reload maps the r key to reloading the page.
• map <c-d> scrollPageDown maps Ctrl+D to scrolling the page down.
• unmap r removes any mapping for the r key.
• unmap <c-d> removes any mapping for Ctrl+D and restores web page or browser's default behavior.
• unmap g0 removes any mapping for a g key and a next 0 key.

Available Vimium C commands can be found via the "Show available commands" link or ? key on the options page. The command name appears to the right of the description in parenthesis.

You can add comments to key mappings by starting a line with " or #, or a space character and a next # in a line.

The following special keys are available for mapping:

• <c-*>, <a-*>, <s-*>, <m-*> for Ctrl, Alt, Shift, and Meta (Command on macOS) respectively with any key. Replace * with the key name of choice.
• <left>, <right>, <up>, <down> for the arrow keys.
• <f1> through <f12> for the function keys.
• <space> for the space key.
• <tab>, <enter>, <delete>, <backspace>, <insert>, <home> and <end> for non-printable keys

Here're some advanced usages which are different with philc/vimium:

• Shift are automatically detected, so, & corresponds to Shift+7 on an English QWERTY keyboard.
  • However, if a single key is longer than 1 character, please wrap it with <+> and insert a s-
  • If you want to trigger a key when multiple modifier keys are pressed, sort a/c/m/s- prefixes by letter order
  • For example, these keys are valid names: <s-left>, <c-j>, <a-s-k>, <a-#> and <a-?>
• mapKey <key:o> <another_key> makes key work as another key only in a special mode named Vomnibar
  • mapKey rules always take effect before matching a key with map rules
  • some other modes are list in https://github.com/gdh1995/vimium-c/wiki/Use-in-another-keyboard-layout#per-mode-mapkey
• map <key:i> command makes key trigger the command in insert mode only, but not the default normal mode
• since v1.99.98, map! <single_key> maps key in both normal mode and insert mode, if only it's not a long sequence
  • For example, map! jj is invalid, but map! <home> and map! <c-j> are suitable
• unmap can only unmap a manually-mapped key or a default key, so a second unmap <key> may result in an error
  • You may use unmap! when you're not sure whether a key has been mapped before
• number keys (0-9 and -) are mapped to "count prefix" of commands by default, so won't be passed to web pages.
  • And then, even after unmapAll, they will be automatically added back on a next map
  • you may write unmap 0 to unmap it explicitly

Project Introduction

Vimium C:

• 中文介绍 (description in Chinese)
• a web extension for Firefox, Microsoft Edge and Google Chrome that provides keyboard-based navigation and control of the web, in the spirit of the Vim editor.
• add some powerful functions and provide more configurable details and convenience.
• here is its Apache-2.0 license and privacy policy
• the initial code is forked from philc/vimium:master on 2014.
• customized after translating it from CoffeeScript into JavaScript and then TypeScript.

Other extensions supporting Vimium C:

• PDF Viewer for Vimium C
  • built from (modified) PDF.js, and is a replacement for the extension named PDF Viewer
  • visit it on Chrome Web Store
  • Project home: vimium-c-helpers/pdf-viewer
• NewTab Adapter
  • take over browser's new tab settings and open another configurable URL
  • visit it on Firefox Add-ons / Chrome Web Store
  • project home: vimium-c-helpers/newtab
• Shortcut Forwarding Tool
  • provide 32 configurable shortcuts and forward them to another extension like Vimium C
  • visit it on Firefox Add-ons / Chrome Web Store
  • project home: vimium-c-helpers/shortcuts
• Modified Weidu New Tab (微度新标签页修改版)
  • a modified and lite version of www.weidunewtab.com (or www.newtabplus.com ), with Chinese translation only
  • it does not take over browser's new tab settings; if needed then NewTab Adapter is recommended
  • visit it on Chrome Web Store

Release Notes

Refer to RELEASE-NOTES.md.

Known Issues

There're some known issues on previous or latest versions of Chromium-based browsers, and please read https://github.com/gdh1995/vimium-c/wiki/Known-issues-on-various-versions-of-Chrome for more information.

Building

If you want to compile this project manually, then you need a Node.js 13+ and npm. Please run:

npm install typescript
npm install pngjs # only needed for Chromium-based browsers
node scripts/tsc
# ./scripts/make.sh vimium_c-debug.zip

gulp local can also compile files in place (using configurable build options), while gulp dist compiles and minimizes files into dist/.

The options including MinCVer and BTypes in gulp.tsconfig.json are used to control supported target browsers and set a minimum browser version.

Donating / 捐赠

Vimium C is an open-source browser extension, and everyone can install and use it free of charge. If you indeed want to give its author ([email protected]) financial support, you may donate any small amount of money to him through Open Collective, PayPal, Alipay or WeChat. Thanks a lot!

Vimium C 是一款开源的浏览器扩展程序，任何人都可以安装使用它而无需支付任何费用。 如果您确实想要资助它的开发者（[email protected]）， 可以通过支付宝、微信、Open Collective 或 PayPal 无偿赠与他一小笔钱。谢谢您的支持！

A partial donation list is in / 部分捐赠列表详见: https://github.com/gdh1995/vimium-c/wiki/Donation-List .

Thanks & Licenses

Vimium C: Copyright (c) Gong Dahan. See the Apache-2.0 license for details.

The translation files in _locales/ belong to CC-BY-SA-4.0, except some of those English sentences which are the same as philc/vimium's are under Vimium's MIT license.

• Vimium: Copyright (c) 2010 Phil Crosby, Ilya Sukhar. Licensed under the MIT license.
• TypeScript: and modified es.d.ts, es/*, dom.d.ts and chrome.d.ts in types/: Copyright (c) Microsoft Corporation (All rights reserved). Licensed under the Apache License 2.0. See more on www.typescriptlang.org.
• Viewer.js (Modified): Copyright (c) 2015-present Chen Fengyuan. Licensed under the MIT license.
• JavaScript Expression Evaluator (Modified): Copyright (c) 2015 Matthew Crumley. Licensed under the MIT license.
• The orange picture in the icon is from https://pixabay.com/vectors/orange-fruit-mandarin-citrus-fruit-158258/
• 微度新标签页: Copyright (c) 2012 杭州佐拉网络有限公司 保留所有权利.
• PDF.js: Copyright (c) Mozilla and individual contributors. Licensed under the Apache License 2.0.

Declaration for Applicable Regions

The Vimium C and other extensions published by gdh1995 are available for all people in "all regions" of Microsoft Edge Add-ons, Chrome Web Store and some other markets. This behavior is only to make these extensions easier to use, but
DOES NOT EXPRESS OR IMPLIED the author (gdh1995) "agrees or has no objection to" that "Taiwan" can be parallel to "China", which was an inappropriate status quo in the stores' (developer) pages on 2021-06-03.

According to The Constitution of the People's Republic of China and international consensus, Taiwan is an inalienable part of the sacred territory of the People's Republic of China.