Surfingkeys – 用javascript和键盘扩展你的chrome

安装

简介

Surfingkeys和现有的一些插件一样，让你尽可能的通过键盘来使用chrome浏览器，比如跳转网页，上下左右滚屏。但不只是给vim用户使用，Surfingkeys的基本特性是让你自己写一段Javascript脚本，然后通过mapkey映射到某些按键。之后当你按了那几个键以后，对应的Javascript脚本就会被执行。

Surfingkeys的配置全部写在一段javascript中，很容易添加自己的映射按键。如：

mapkey('<Ctrl-y>', 'Show me the money', function() {
    Front.showPopup('a well-known phrase uttered by characters in the 1996 film Jerry Maguire (Escape to close).');
});

配置参考.

演示

关于浏览器限制

无论是Chromium家族的Chrome/Edge还是Firefox，都有一些特殊的页面是禁用任何插件的，比如chrome://XXXXX之类的页面、Chrome Webstore。这种限制是无法通过Javascript或者某些配置来绕开的。为了突破这种限制，我一般是使用自己编译的Chromium，如果大家有需要可以在这里（提取码: 4d3u）下载（Windows系统用户请下载Chromium_installer.exe，MacOS系统用户请下载Chromium.dmg）。我会不定期的更新这个定制版的Chromium，基于Chrome的稳定版。当前这个定制版包含了以下改动：

放开对Surfingkeys的限制，使得它可以在所有页面上使用。
在Chromium里内嵌一个取词翻译的功能，如果你需要这个功能，请按照这里的步骤下载安装一个dictorium.db的文件到指定目录，Surfingkeys也提供了对Dictorium的支持。
禁用了浏览器自带的Ctrl-n/Ctrl-p快捷，这样就可以按照这里设置在输入框里用Ctrl-n/Ctrl-p来选择下一个/上一个选项。

功能特性

所有配置都用javascript描述，易于修改添加自己的按键。
一个大号光标，这样visual mode不会太痛苦。
搜索选中文本，在normal mode和visual mode都好用。
自动生成帮助信息。
在visual mode下，按* 可以搜索当前单词。
滚动操作（像e d上下翻页之类）可以在顶层页面工作，也可以在一个支持滚动的DIV中使用。
在一个有多个frame的页面中，w可以切换frame。
会话管理。
一个多功能书签地址栏
前缀数字可多次重复相应操作
使用VIM编辑页面上各种输入框
点命令重复前一个操作
sm预览markdown

快速上手

安装本插件以后，打开你要访问的站点。先按?或者u看看帮助信息，按Esc可以关掉帮助信息。

试试帮助信息里的那些按键，比如，e向上翻页，d向下翻页，se打开设置。

? 显示帮助
t 搜索收藏夹和访问历史
/ 在当前页查找
f 拨号打开链接
v 切换文本选择模式
T 切换标签页

打开连接

默认的拨号键有asdfgqwertzxcvb，如果按了一个非拨号键，会自动退出拨号。下面的设置可以改成右手习惯：

Hints.characters = 'yuiophjklnm'; // for right hand

当拨号盘有重叠上，可以按Shift翻转重叠的拨号盘。按住空格键可隐藏拨号盘，松开恢复。

Surfingkeys支持的模式

Surfingkeys有三种模式：normal，visual和insert。

Normal mode，默认模式

当你打开一个页面时，自动进入该模式。通过函数mapkey添加的所有按键都只在这种模式下有用。

Visual mode，用于选中文本，以及各种针对选中文本的操作

除了通过函数vmapkey添加的所有按键在这种模式下有用，此外还有一些内置类似vim的按键，如j k h l b w0 $等。

按v可以切换visual mode。在visual mode下，你会在页面底部看到一个提示 – Caret或者Range，页面中还有一个大号的光标。光标做得这么大，是让人在页面中好找到它。

Caret 表明当你按jkhl时会移动光标，Range则表明你移动光标会选择文本。下面有个小练习：

按下v，确认你能看到Caret提示和光标。
使用j k h l b w0 $试试移动光标。
再按下v，确认你看到Range提示。
使用j k h l b w0 $试试选中文本。
按下sg看看发生了什么。
再按下v回到normal mode。

search_selected

Insert mode

当输入焦点定位到各类输入框时（无论你是通过i或f选择定位还是鼠标点击定位的），就进入该模式。通过函数imapkey添加的所有按键都只在这种模式下有用。

`Ctrl - i` 打开vim编辑器。

查找

查找不是模式，但是它会让你自动进入visual mode. 按/打开查找栏，输入你要查找的文字，你会看到所有匹配的文字会被高亮。按回车完成查找，这时你会自动进入visual mode – Caret。按n定位下一个，N定位前一个。

搜索栏

一些需要用户输入的功能通过搜索栏提供，比如

用t打开网页（从收藏夹或访问历史）
用b打开收藏夹
用og/ob等打开搜索引擎
用:打开命令模式

用t打开搜索栏时，

`Ctrl - d` 可以从收藏夹或访问历史中删除选中项

用b打开搜索栏时，

`Ctrl - <any letter>` 创建相应的类似vim的全局标示。

search_engine

搜索选中文本

从使用Firefox时起，我就必装的一个插件。无论Firefox还是Chrome，我用的插件都是通过右键菜单来实现的。Surfingkeys则通过按键来实现。默认情况下，当你在normal mode下按sg，Surfingkeys会打开google搜索选中文本，如果没有文字被选中，则搜索系统剪贴板里面的文字。在visual mode下，它只会搜索选中文本。

sg里面的g是个别名，用于google，还有其他一些内置的别名，如b是百度的别名。这样当你按sb的时候就是使用百度来搜索选中文本。参考在搜索栏里添加搜索别名来添加你自己的搜索别名，尤其那些用于公司内部的搜索。

此外，还有sog可以使用google在本站搜索选中文本。在这个sog里面，s是search_leader_key，o是only_this_site_key，g是搜索别名。

search_leader_key(s)加上大写的别名(G)会打开搜索框让你可以修改添加搜索内容，再用Google搜索。其它别名和你通过addSearchAliasX添加的别名，大写的都可以这样工作。

类vim标示

简单说，vim中的marks就是按m，然后跟一个字符（a-z为当前页内标示，其它的如0-9，A-Z为全局标示），标示一下当前网址。之后，你随时按'跟上你定义的那个标示符，就会跳转到该网址。

除了m键创建标示外，你还可以从收藏夹里按住Ctrl，加上标示符来创建。如下：

按下b打开收藏夹。
随便输点啥，定位到你要标示的网址。
按住Ctrl，加上你选中的标示符，比如f。

之后，按'F就可以直接打开该网址来。

这个功能对那些你需要经常访问对网址很有用，两个键直达。om可以查看你已创建的标示。

切换标签页

默认情况下，按T会显示所有已打开标签页，然后按相应的提示键可以切到该标签页。

tabs_overlay

这里有个设置settings.tabsThreshold，当然打开的标签页总数超过它时，再按空格就会使用搜索栏来选择标签。

tabs_omnibar

如果你希望一直用搜索栏来选择标签页，可使用如下设置:

mapkey(' ', 'Choose a tab with omnibar', 'Front.openOmnibar(OpenTabs)');

效果相当于：

settings.tabsThreshold = 0;

无论是否在搜索栏里，标签页都按最近使用的顺序列出。如果你希望按标签页原本的顺序列出，可以设置：

settings.tabsMRUOrder = false;

命令

用:打开搜索栏可用于执行命令，命令执行结果会显示在搜索栏下方。可以添加你自己的命令如下：

command('<command_name>', '<help message for this command>', function() {
    // to do
});

例如，

command('setProxyMode', 'setProxyMode <always|direct|byhost>', function(args) {
    // args is an array of arguments
    RUNTIME('updateProxy', {
        mode: args[0]
    });
    // return true to close Omnibar for Commands, false to keep Omnibar on
    return true;
});

// 映射不同的按键到该命令，但采用不同的参数。
map('spa', ':setProxyMode always');
map('spb', ':setProxyMode byhost');
map('spd', ':setProxyMode direct');

除了命令，你还可以执行各类简单js代码。

commands_in_omnibar

顺滑滚动

所有可以滚动的对象都默认支持顺滑滚动，如下可以关掉顺滑特性：

settings.smoothScroll = false;

会话管理

用Surfingkeys在Chrome里保存会话相当于保存所有标签页的地址，打开会话则相当于在不同的标签页中打开所有保存其中的网页地址，所以会话基本上就是一个网页地址列表，每个会话有自己的名字。

ZZ会保存所有当前标签页到一个名为LAST的会话，然后退出。
ZR恢复名为LAST的会话。
ZQ就只退出，不保存当前会话。

你可以在命令模式下创建／管理多个不同名称的会话。按:打开命令窗口，然后输入:

createSession works

就会创建一个名为works的会话，要打开该会话使用如下命令：

openSession works

列出已保存的所有会话：

listSession

删除某个会话：

deleteSession works

前缀数字可多次重复相应操作

如果需要重复多次某个操作，可以在按该映射键之前按下相应的数字，比如3d，就会往下滚3页。这种方法同样适用于标签操作，比如，你现在在第一个标签页，你想切换到第四个标签页，

按3R就可以
3E会切回到第一个标签页

另一个例子是移动标签页，假设你现在开着23个标签页，你在第12个，

11<< 就把当前标签页移到第一个
10>> 则会把它移到最后一个

通常情况，你不需要去数多少个标签页，如果你只是想移动到开头或者结尾的话，你按一个足够大的数字就可以，比如99<<。

开关热键

默认情况下，按Alt-s可以在当前站点开关Surfingkeys。当Surfingkeys处于关闭状态时，除了热键，其它所有按键映射都停止工作。用如下设置修改热键：

map('<Ctrl-i>', '<Alt-s>'); // 热键只能是一个按键，但可以带辅助按键，不能是`gg`这样的一串按键。

当Surfingkeys在某个网站被Alt-s关掉时，这个状态会被保存在设置里，如

"blacklist": {
    "https://github.com": 1
},

再按一次Alt-s会从settings.blacklist中删除该站点。另外，yj可以把当前设置复制到系统剪贴板。

另一个禁用Surfingkeys的方法是用settings.blacklistPattern，请参考regex for disabling.

代理设置

SwitchySharp是个很好的代理管理插件，但我的用法很简单，

创建一个使用PAC脚本的配置。
在PAC脚本里维护一个网站列表，如果当前所访问的站点在其中就使用代理。
当碰到一个站点是被墙的，就把这个网站加入列表。
然后点击SwitchySharp的图标重载配置。
有时也会点击图标在配置之间切换。

其中需要手工编辑PAC脚本，鼠标点击SwitchySharp图片切换重载配置，因此我把代理设置的功能集成进来，并提供相关的命令和快捷键。

setProxy, 设置代理，示例如下：

  setProxy 192.168.1.100:8080
  setProxy 127.0.0.1:1080 SOCKS5

setProxyMode, 设置代理模式，有三种模式：direct, byhost, always

  direct      Chrome不使用代理访问任何网站。
  byhost      Chrome只在访问你通过下面的命令添加的网站时使用代理。
  always      Chrome使用代理访问所有网站。

addProxySite, removeProxySite, toggleProxySite, 管理你需要通过代理访问的网站，比如：
```
  addProxySite google.com,facebook.com,twitter.com
```
proxyInfo, 列出你当前的代理设置，包括用以上命令设置的信息。
cp, 切换当前站点的代理设置，即是否使用代理访问当前站点。
spa, :setProxyMode always快捷键。
spb, :setProxyMode byhost快捷键。
spd, :setProxyMode direct快捷键。
spi, :proxyInfo快捷键。

VIM编辑器

Surfingkeys集成了ACE里的VIM编辑器，用于：

编辑网页上的各类文本输入框。
编辑URL并在新标签页打开
编辑设置

编辑网页上的各类文本输入框

在Normal模式，按大写的I，然后按相应的字母选择一个输入框。这时会打开一个VIM编辑器。对于单行输入框input和多行输入框textarea，打开的VIM编辑器会有点细微的不同。

对于单行输入框input，打开的VIM编辑器只有一行，你可以通过各类VIM按键编辑你的文本，按Enter或者:w就会把VIM编辑器里的内容写回相应的输入框。

input_with_vim

对于多行输入框textarea，打开的VIM编辑器有多行，在你完成编辑之后，按Ctrl-Enter或者:w就会把VIM编辑器里的内容写回相应的输入框。

textarea_with_vim

对于下拉列表select，打开的VIM编辑器有多行，但你不能编辑其中的文本，你只能搜索你需要的选项，跳到那一行，然后按Enter选中它。这对那种有几十个以上选项的下拉列表尤其有用。

select_with_vim

按键Esc或:q可退出VIM编辑器，不写回输入。

Tab键可以从当前页面上搜索匹配的词组，然后按空格键补齐。

如果你是通过按键i或者鼠标点击进入一个输入框的，你可以正常修改输入框中的文本，也可以随时按Ctrl-i打开一个VIM编辑器。

记住在插入模式，按Ctrl-i打开VIM编辑器。

编辑URL并在新标签页打开

su可以打开一个VIM编辑器来编辑当前URL，然后按Enter或者:w就会打开编辑后的URL，就像一个地址栏一样，但这是一个支持vim按键的地址栏。

Tab键可以从书签和访问历史中搜索匹配的URL，然后按空格键补齐。

url_with_vim

编辑设置

se打开设置编辑器, :w保存设置。

点命令重复前一个操作

重复前一个操作

所有normal模式下的按键都可以由点来重复，除了那些在创建时指定repeatIgnore为true的按键，如

mapkey('e', '#2Scroll a page up', 'Normal.scroll("pageUp")', {repeatIgnore: true});

这样，.就不会往上翻页，即使你刚刚按了e。

Markdown预览

复制markdown代码到系统剪贴板。
sm预览剪贴板里的markdown。
在预览页，再按sm会打开vim编辑器编辑markdown。
:wp刷新预览。
r可以从系统剪贴板里重新加载markdown.

markdown

Surfingkeys默认使用这个markdown分析器，如果你想用github提供的API，可以设置：

settings.useLocalMarkdownAPI = false;

配置参考

添加一个按键映射

mapkey(keystroke, help_string, action_code, [options])

参数	含义
keystroke	字符串，触发某个操作的按键
help_string	字符串，帮助描述，会自动出现在`u`打开的帮助小窗里。
action_code	字符串或者函数，一段Javascript代码，或者一个Javascript函数。
options	object, 字段属性如下
extra_chars	布尔值[可选]，下一个按键是否为action_code的参数，可以参考`m`或`'`的设置。
domain	正则表达式[可选]，表明只有当域名匹配时，该按键映射才会生效。比如，`/github\.com/i` 说明按键映射只在github.com上生效。
repeatIgnore	布尔值[可选]，是否可通过点命令重复该按键。

一个示例，在不同网站上映射相同的按键到不同的操作：

mapkey('zz', 'Choose a tab', 'Front.chooseTab()', {domain: /github\.com/i});
mapkey('zz', 'Show usage', 'Front.showUsage()', {domain: /google\.com/i});

可视化模式下的mapkey

vmapkey(keystroke, help_string, action_code, [options])

映射按键到其他按键

map(new_keystroke, old_keystroke, [domain_pattern], [new_annotation])

参数	含义
new_keystroke	字符串，将要使用的按键。
old_keystroke	字符串，将被替换的按键。
domain_pattern	正则表达式[可选]，表明只有当域名匹配时，该按键映射才会生效。
new_annotation	字符串[可选], 如果提供了就用作帮助描述，否则就用old_keystroke对应的帮助描述。

删除一个按键映射

unmap(keystroke, [domain_pattern])

参数	含义
keystroke	字符串，将要删除的按键。
domain_pattern	正则表达式[可选]，表明只有当域名匹配时，该操作会生效。

在搜索栏里添加搜索别名

addSearchAlias(alias, prompt, search_url, suggestion_url, callback_to_parse_suggestion);

参数	含义
alias	一个以上字符，用作搜索别名。当你在搜索栏里输入它之后，再按空格键，会切换到对应的搜索引擎。
prompt	提示符，说明当前所用搜索引擎。
search_url	搜索引擎搜索地址。
suggestion_url[可选]	搜索自动完成URL，如果提供的话，搜索栏会列出相关关键字。
callback_to_parse_suggestion[可选]	解析suggestion_url返回的内容，列出相关关键字。

addSearchAliasX(alias, prompt, search_url, search_leader_key, suggestion_url, callback_to_parse_suggestion, only_this_site_key);

参数	含义
search_leader_key	一个以上字符，如果你不想使用默认的`s`键。
only_this_site_key	一个以上字符，如果你不想使用默认的`o`键。

这是一个扩展版本，除了往搜索栏里添加搜索别名，还会创建一个按键映射，由search_leader_key加上alias组成，对应的操作就是搜索选中文本。比如，下面这行，

addSearchAliasX('s', 'stackoverflow', 'http://stackoverflow.com/search?q=', 'o');

就相当于

addSearchAlias('s', 'stackoverflow', 'http://stackoverflow.com/search?q=');
mapkey('os', 'Search Selected with stackoverflow',  'searchSelectedWith("http://stackoverflow.com/search?q=")');
vmapkey('os', 'Search Selected with stackoverflow',  'searchSelectedWith("http://stackoverflow.com/search?q=")');