跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

欢迎页

欢迎页——Aggrega 自己的页面,位于单独的编辑器标签页中,先说明 Aggrega 是什么,然后列出扩展在此工作区中所需的条件,并将每个条件标记为 Met 或 To do。每个步骤都提供创建所需事物的方式和指向你已有事物的方式,并解释该条件,而已满足的步骤不会再问你任何问题。标记为 Met 的步骤在其条件失效时会恢复为 To do。已满足的步骤打开时处于折叠状态,因此页面打开时呈现的是剩余的工作。每个步骤还会显示其当前所处的值——工作区根目录、编译器、Release、注册表——字号比指导文字更大、字重更粗,以 Selected: 引出,步骤折叠时位于标题下方,展开时紧挨着按钮上方,并在你尚未选择时用文字说明——有可选内容时显示 None selected.,根本没有可选内容时显示 None available.。其底部是决定页面是否在启动时打开的复选框(与设置界面中的是同一个开关),其下方是你正在运行的扩展和编译器的版本,最后是语言服务器是否正在运行以及它报告的版本。Commands 面板标题栏中的房屋图标可随时再次打开它。它不占用 Aggrega 视图的空间。

Welcome to Aggrega! 在单独的编辑器标签页中打开。它先说明 Aggrega 是什么,然后列出扩展在你打开的工作区中所需的条件:

  1. Aggrega 能识别的工作区——即前提条件中所述的发现机制。
  2. 此编辑器可以运行的编译器——aggrega.server.binaryPath 中指定的 aggrega 二进制文件。
  3. 要操作的 Release——构建、预览和拓扑图各自作用于一个 Release。
  4. 用于解析的注册表——拉取依赖和搜索已发布的目录时,会依据你的配置所指定的注册表进行解析。

每个步骤都会解释该条件的用途以及编辑器如何达成它,因此该页面也是阅读产品介绍的地方,而不仅仅是一份检查清单。

在 Aggrega 尚未识别的文件夹中的 Welcome to Aggrega! 标签页,其第一个步骤“Aggrega 能识别的工作区”被标记为待办,并展开显示其说明。

每个步骤都提供不止一种完成方式,其中一种总是“我已经有了”。 你可以创建工作区配置,或将编辑器指向已带有配置的文件夹;使用你 PATH 上的编译器、选择你放在别处的构建,或下载一个;起草一个 Release 或选择你已有的一个;初始化官方 hub、指定你自己的注册表,或将注册表添加到你已有的配置中。这里没有任何死胡同会只丢给你一个文件对话框,却让该步骤仍未完成。

你已满足的步骤会被勾选,不会再问你任何问题。 页面读取实际情况,而不是向每个人提出相同的问题,因此如果你先在命令行中构建了配置,然后才打开编辑器,所有步骤都会显示为已勾选。

每个步骤都可以折叠,页面打开时显示仍需完成的内容。 每个步骤右上角的插入符号用于展开和折叠它。条件已满足的步骤打开时处于折叠状态,未满足的步骤打开时会将其说明展示在你面前——因此你阅读的是仍需完成的工作,而不是已完成的工作。折叠的步骤保留其标题和所有按钮,只隐藏说明:一旦你了解某个步骤的用途,无需再次阅读即可对它进行操作。

这种布局在页面创建时确定,之后由你掌控。在你阅读时变为已满足的步骤会更新其标记并保持展开——它不会在你的光标下折叠起来——你按下的插入符号会保持在你设置的状态,无论页面在其周围刷新多少次。关闭并重新打开页面会重新读取条件并重新排列。当编辑器重启其扩展时,替代你已打开页面而绘制的页面也是如此——例如向只打开了一个文件夹的窗口添加文件夹时:你原有的页面会被关闭,并在同一标签页组中绘制一个新页面,无论该页面是否设置为启动时打开,因此窗口始终只保留一个页面,且该页面跟随你所在的工作区。

每个步骤还会显示其当前所处的值,因此页面回答的是哪一个,而不仅仅是是否:工作区根目录、编译器、Release 以及配置所声明的注册表。该值的字号比周围的说明更大、字重更粗,因为与大段文字使用相同字重绘制的值需要你去寻找。折叠的步骤将其显示在标题下方,因此你无需展开任何内容即可确认你的选择;展开的步骤将其显示在说明末尾、紧挨着按钮上方,使它成为你操作前最后读到的内容。所选的值以 Selected: 引出,其字号比值本身更小、字重更细,因此该标签指向值,而不是与之争夺注意力。

已配置工作区中的欢迎页,编译器、Release 和注册表步骤被标记为已满足并折叠,每个步骤都在按钮上方显示所选的值,页脚是启动复选框、版本信息和语言服务器的状态。

在你尚未选择时,步骤会用文字说明,而不是留下空行,空行会被理解为页面未能绘制——并且它会区分读者需要不同处理的两种状态。None selected. 表示有可选的内容,但你没有选择其中任何一个。None available. 表示这里根本没有可供选择的内容,因此按下该步骤的“I already have one”只能给你显示一个空列表,你需要的是它的另一种完成方式。只有提供列表的两个步骤可能显示 None available.——工作区和 Release。编译器是直接指定的,注册表是直接注册的,因此这两个步骤都没有可能为空的列表。注册表步骤还保留第三种显示 Not read yet.,用于无法询问编译器的情况:在没有任何东西能够回答时告诉你一个都没有配置,会超出页面所知道的。

步骤的标记在两个方向上都跟随其条件。 每个步骤在标记旁边用文字表明其状态——Met 或 To do——因为标记本身是一个字形,仅凭字形只能让人猜测其含义。当条件变为成立时,步骤显示 Met;如果之后条件失效——编译器停止响应、Release 被取消选择——则再次显示 To do。页面每次刷新时都读取实际情况,而不是记住曾经成立的情况,因此它绝不会报告你此后已失去的东西。在失效很重要的地方,它也会在你已经在看的地方报告:状态栏会显示已停止响应的编译器,而 Commands 面板顶部的 Project folder、Aggrega workspace 和 Release 行会指明当前的选择。

它特意采用普通的编辑器标签页而不是对话框:每个步骤都要求你指向自己工作区中的某个东西,而对话框会遮住包含答案的文件。它位于编辑器区域而不是 Aggrega 视图中,因此不占用侧边栏空间,并且可以说明产品是什么——狭窄的栏中没有空间做到这一点。它是 Aggrega 自己的标签页,按自己的方式打开和关闭,不提供进入编辑器自身欢迎页的路径。

页面在底部居中位置提供这一决定,命令面板也提供。 两者都修改同一个设置 aggrega.getStarted.show,写入你自己的设置中——绝不写入仓库,因此你的选择不会传给其他打开该仓库的人。底部的控件是一个复选框,标签为 Show Aggrega welcome page on startup,当页面在启动时打开时处于勾选状态——因此它报告的是设置的当前状态,而不是向你提供改变它的操作。在设置界面中将其关闭,复选框随之变化;按下复选框,设置界面随之变化。它是位于两处的同一个开关,而不是两个开关。复选框被按下时保持键盘焦点,因此按空格键可交替勾选和取消勾选。

关闭它只是阻止页面在启动时打开,而不是让页面无法访问,而且这不是一扇单向门:命令面板中的 Aggrega: Get started 会将其重新开启并打开页面,而 Aggrega: Stop opening the welcome page on startup 是命令面板通往同一设置的方式。

Commands 面板在齿轮图标旁提供返回该页面的途径。 它是右上角的房屋图标,工具提示为 Open the welcome page——因此返回页面是你通过查看 Aggrega 视图就能发现的,而不是需要事先知道并输入的东西。它会打开页面,并让你的启动设置保持原样:再次查看页面不会将其重新开启。重新开启它的是命令面板中的命令,因为重新开启是一个决定,而不是一瞥。

页面在底部报告你正在运行的内容。 那里有两个版本读数:Extension,即编辑器加载的此扩展的哪个构建;以及 Compiler,即语言服务器正在运行的 aggrega 二进制文件对自身的说明。Extension 读数在构建扩展时记录,取自那一刻源代码的状态,形式与编译器自身构建用于其版本的形式相同——因此开发窗口、已安装的副本以及从已编辑的源码树打包的副本都会表明自己是哪一种:

  • 单独的版本标签(例如 0.2.0)表示该构建正是该版本;
  • 标签后跟计数和提交(例如 0.2.0-3-g1a2b3c4)表示基于提交 1a2b3c4 的构建,位于该版本之后三个提交——而单独的提交(例如 1a2b3c4)表示在其之前没有任何版本时基于该提交的构建;
  • 以上任一形式带有 -dirty 后缀,表示该构建是从带有未提交更改的源代码副本构建的;
  • dev 表示该构建是在无法读取源代码历史的地方构建的。

这两个读数都不是写入页面的——它们都在绘制页面时读取,因此开发构建会如实报告自己是开发构建而不是什么都不显示,并且重启到不同的编译器时读数会随之变化。如果无法获取某个读数——扩展构建时没有记录它是哪个构建、没有正在运行的程序可询问,或正在运行的程序没有回应——标签仍会保留并说明未报告版本,因此缺失的读数绝不会被误认为是你没有注意到的读数。

页面的最后一行说明语言服务器是否正在运行,以及它是哪个构建。 它显示 Language server running、starting、not running 或 failed to start,用词与状态栏和通知相同;failed to start 表示最近一次启动尝试失败,且此后没有任何服务器运行过。Aggrega 输出通道会说明原因,首次启动或重启失败时发出的通知也会说明。服务器运行期间,该行会加上扩展连接到服务器时,正在运行的服务器所报告的自身版本,写法与 Compiler 读数书写版本的方式相同。其上方的 Compiler 读数是另一个事实:它是启动服务器所用的二进制文件在被询问时给出的说明,当该路径上的文件被替换而由它启动的服务器仍在运行时,两者会不同,因此页面同时显示两者。不报告自身版本的语言服务器在那里显示 version not reported,而不是借用二进制文件的版本。该行及其上方的两个读数会随服务器的启动、停止、重启或失败而更新,无需重新打开页面;步骤在重启过程中保留其标记。