跳到主要内容

打开方式

什么是「打开方式」​

你放在 udctl 里的每一个文件，都由某个查看器来显示：图片用图片查看器打开，PDF 用 PDF 查看器，图表用图表编辑器，以此类推。多数情况下 udctl 会根据文件名自动替你选好查看器。

但有时一个文件可以用不止一种方式显示，有时你也会想换一个和 udctl 默认不同的查看器。打开 方式这个控件让你看到当前用的是哪个查看器，并切换到另一个——就像电脑上你可以选择用哪个应 用打开文件一样。

可用范围： 打开方式，以及本页介绍的全部内容，现已在网页版 app.udctl.com 上线。桌面版将在后续版本提供；如果你的桌面版还看不 到打开方式控件，请改用网页版，或等下一个版本发布后更新。

切换查看器​

打开任意文件（从「资源」页，或从任务上附带的文件）。在文件上方的头部，你会看到一个打开方 式按钮，上面写着当前所用查看器的名字，例如图片或通用图表。

点它，会弹出一个短菜单：

  • 能显示这个文件的查看器，当前所用的那个旁边有一个勾。选另一个就立刻切过去。如果同一类文件 有不止一个插件能打开，它们都会各自作为一个选项列在这里。
  • 按文本查看 —— 以纯文本显示文件原始内容。始终可用。
  • 下载 —— 把文件保存到你的电脑。始终可用。

这样切换只在你打开这个文件期间有效。

如果某个查看器或插件显示不了文件——文件损坏，或插件运行出错——udctl 不会留给你一个空白框，而 是在原位显示一条简短提示，并继续保留按文本查看和下载，让你仍然能拿到文件内容。

设为默认​

如果你希望某一类文件总是用同一种方式打开，打开打开方式菜单，选总是用这种方式打开 .xyz 文件（.xyz 是文件的后缀）。从此，每个该后缀的文件都会用你选的查看器打开。

默认设置跟着你的账号走，因此会在你的各台设备上生效，也不会影响到别人。想恢复自动选择，再打开 菜单，选清除 .xyz 的默认。

内置的查看器​

下面这些文件类型有内置查看器，无需安装任何东西：

  • 图表 —— .drawio 通用图表、udctl 数据流图
  • Excalidraw 手绘图
  • 图片、视频、音频
  • PDF 和 Word 文档
  • 电子表格和表格
  • Markdown、代码、纯文本
  • 演示文稿和 HTML 页面

其余文件类型暂时无法自行预览。udctl 不会给你一个空白预览，而是告诉你还没有能打开它的应用，并 在下载链接旁边把你指向插件库，让你为它装一个查看器。

用插件增加查看器​

插件让 udctl 学会显示它本身不认识的文件类型——就像给操作系统装一个应用，让它能打开一种 新的文件。装好插件后，它负责的那类文件就会用它打开，而不再只是显示下载链接，插件也会作为一个 选项出现在打开方式菜单里。

插件如何被约束安全​

一个插件就是一个独立、自包含的网页（一个 .html 文件）。udctl 把它放在一个封闭的沙箱里运 行：插件能读取并显示你打开的那一个文件，但它上不了网，看不到你的其它文件，也碰不到你的账号或 应用的其余部分。

这个沙箱很强，但并非无懈可击——一个行为不端、且已经拿到你这个文件的插件，仍有可能通过浏览器 无法替我们封死的个别通道把内容送出去。这和代码编辑器、笔记应用对待它们的扩展是同一种取舍。 udctl 会在安装前把一个插件能做什么清楚地告诉你并请你确认，所以规则很简单：只装你信任的插 件。

安装插件​

进入设置 → 资源插件。有两种方式：

  • 插件库 —— 浏览发布到官方 registry 的插件，一键安装。udctl 会下载它，并对照 registry 里 公布的指纹校验文件是否被篡改，然后安装。有新版本发布时你会看到更新选项；如果某个插件被 从插件库下架，你会看到一条提示，建议你卸载它。
  • 上传自己的 —— 选一个你已有的 .html 插件文件，填上它应当打开的文件后缀（例如 .ipynb），然后安装。

无论哪种方式，udctl 都会先简要说明这个插件能做什么并请你确认。同一类文件可以装不止一个插件： 为一个已经被别的插件占用的后缀再装一个查看器是允许的，两个插件随后都会出现在打开方式菜单 里，你可以在它们之间选用，或把其中一个设为默认。

你随时可以在同一个设置页用卸载移除插件。卸载时会请你确认，确认后会连同这个插件自己的文件 一起删除；绝不会动你的任何文件，取消则什么都不变。你安装的插件只属于你自己——不会改变你队友 那边的任何东西。

一个现成的例子：Jupyter 笔记本​

官方的 Jupyter Notebook Viewer 插件以只读方式渲染 .ipynb 笔记本——markdown 单元、代码单 元的语法高亮、表格和图片。它已发布在插件库里，所以体验插件最快的办法就是打开设置 → 资源插件 → 插件库把它装上。它的完整源码在 registry 里： ud-registry 中的 ipynb-viewer。

自己写一个插件​

一个插件就是一个 .html 文件，所有东西都在里面——它的脚本、样式、图片全部内联，因为沙箱会拦 掉任何网络请求。udctl 把要显示的文件交给插件，插件负责把它画出来。

udctl 和你的插件之间的对话只有三条短消息。每条消息都带 udPlugin: 1（协议版本）：

  1. 当你的插件加载完、开始监听时，它告诉 udctl 自己就绪（ready）。
  2. udctl 把**文件（file）**发过来一次：文件名（fileName）和字节（bytes，一个由你的插件自 己解码的 ArrayBuffer）。这是插件唯一能收到的东西——绝不会有链接、令牌，或任何与你账号有 关的信息。
  3. 如果你的插件显示不了这个文件，它可以报告错误（error），udctl 会在原位显示一条提示。

一个完整、能跑的插件就这么点：

<!doctype html>
<html>
  <body>
    <pre id="out">等待文件…</pre>
    <script>
      // 1. 监听 udctl 将要发来的文件。
      window.addEventListener('message', function (event) {
        var msg = event.data;
        if (!msg || msg.udPlugin !== 1 || msg.type !== 'file') return;
        var text = new TextDecoder().decode(msg.bytes);
        document.getElementById('out').textContent =
          msg.fileName + '\n\n' + text;
      });
      // 2. 告诉 udctl 我们已经准备好接收。
      parent.postMessage({ udPlugin: 1, type: 'ready' }, '*');
    </script>
  </body>
</html>

把它存成一个 .html 文件，在设置 → 资源插件 → 上传自己的里填上你想让它打开的后缀安装，它 就会把任何匹配文件的原始文本显示出来。在此基础上你可以加 markdown 渲染、语法高亮，或你的文件类 型需要的任何功能——只要每个库都打包进这一个文件里。 Jupyter Notebook Viewer 源码 就是一个照这种方式做出来的完整例子。

插件 registry​

registry 是一个公开的 GitHub 仓库， oatnil-top/ud-registry，它列出了所有人都能安装的 插件。udctl 里的插件库直接读取它的清单，一键安装就是这么来的。registry 里的每个插件都带有 它那个文件的指纹，udctl 安装前会校验这个指纹，所以你装到的就是当初发布的那份。

提交你自己的插件​

插件通过 pull request 加入 registry：

  1. Fork oatnil-top/ud-registry。
  2. 把你构建好的 .html 文件放到 plugins/<id>/<id>.html，并在 plugins.json 里加一条对应的 条目。
  3. 发起 pull request —— 模板会引导你填写各个字段。

一个自动检查会确认你的条目格式正确、指纹与文件一致，还有一位审阅者会在合并前阅读源码。合并即 发布到插件库。完整的提交步骤见 registry 的 README。