概念

笔记本就是文档

笔记本是一个 Divooka 文档，它的入口图是一个实现 Notebook Application 的 Events 图。它的 Build 回调负责笔记本的布局；它的其他图（通常是 Function 图）负责响应单元格。文档能拥有的其他一切，它都可以拥有：数据成员、其他图、包、嵌入的资源。

站点、页面、单元格

• 站点就是整个笔记本：一个名称、一个可选图标，以及它的各个页面。
• 页面是笔记本的一项功能，列在侧边栏中。Page 之后添加的所有内容都放在该页面上，直到下一个 Page。
• 单元格是一个输入与一个输出的组合：一个滑块和它显示的内容，一个文本框和它的回应。没有输入的单元格——Markdown、Html、Heading、Image——是静态的；Show 单元格没有输入，但会在页面加载时计算它要显示的内容。

布局是固定的：Build 只布局页面一次，之后变化的只有值、输出，以及哪些输入处于启用状态。如果 Build 为不同访问者布局出不同的内容，就会被拒绝，因为一半是一种布局、一半是另一种布局的页面根本不成其为页面。

布局笔记本的两种方式

逐条语句。 在 Build 之后串联 Notebook Application 自己的节点——Page、Markdown、Slider、Text Box——就像编写 Streamlit 脚本一样。这是通常的做法。

作为值。 Notebook Cells 中的每个节点都把一个单元格作为值生成——Slider、Text Box、Group 等等——你可以对它们连线、把它们保存在数组中，并用 Add Page 或 Add Cell 放置它们。两种方式布局出的是同样的笔记本。

函数响应单元格

每个输入都有一个函数引脚——On Change，按钮则是 On Click——每当输入的值发生变化时，就会用该值调用这个引脚所指定的函数：

输入	函数接收
Number、Slider	一个数字
Text Box、Text Area、Choice、Date	文本（日期格式为 yyyy-MM-dd）
Checkbox、Toggle	一个真值
Upload	上传的文件，或空值
输入组	它的所有字段，一次全部传入，类型为 Notebook Inputs
Button	无

在引脚上使用 Edit Function，会生成一个签名完全匹配的 Function 图。函数返回单元格要显示的内容。如果函数失败，单元格会显示错误，页面其余部分照常工作。

输入的函数在输入第一次变化时才运行，因此页面打开时各输入的输出都是空的。在 Build 中使用 Answer On Load，可以让每个输入在页面打开时就响应其初始值——由滑块驱动的图表通常需要这样。按钮和上传仍然会等待，因为它们没有初始值。

每位访问者独享一份文档

每次加载页面就是一个会话，每个会话都是文档的一个新实例：笔记本创建并构建这个实例，从而把该访问者的单元格绑定到它上面。因此：

• 同一访问者的单元格共享实例的数据成员。 一个单元格的函数可以设置另一个单元格的函数所读取的成员。
• 访问者之间从不共享成员。 使用同一个笔记本的两位同事各自拥有自己的值、输出和成员。
• Input 按标签读取本会话中另一个单元格的当前值；Set Enabled 按标签启用或禁用另一个输入。Get Session Id 提供一个名称，可用于访问者的函数所写入的文件。

共享值

有些东西应该只加载一次并提供给所有人：一张大表格、一个训练好的模型。Site Started 回调在第一位访问者到来之前、在站点自己的实例上运行一次；Set Shared 把一个值保存在那里，Shared 则可以从任何访问者的函数中读取它。这是访问者之间唯一共有的状态，而且是显式的。

Session Started 和 Session Ended 在每位访问者到来和离开时运行。

只读与启用

• Page Read Only 使当前页面变为只读：输入显示其初始值且不能更改，每个单元格显示其函数针对这些值给出的结果。dvn --read-only 对整个站点执行同样的操作。
• Last Read Only 和 Last Disabled 修改最后添加的单元格；Set Enabled 从函数中调用，可在笔记本运行时修改另一个输入。
• Hide Run All 从当前页面去掉 Run All。

输出

函数的返回值决定访问者看到什么，而数据如何绘制由页面决定，而不是由计算决定：

函数返回	页面显示
无	无——输出保持折叠
文本、数字、真值	文本
Notebook Outputs 中的 Markdown、Html、Code	Markdown、HTML 片段（两者都会清除脚本），或带语法高亮的代码块
Html Page	一个完整页面，位于独立的框架中
Divooka 图像，或 Picture	图片，按原样显示
来自 Plotting 工具箱的图形或图表	以交互方式绘制的图表，Image 视图显示 Divooka 自己的渲染结果
Notebook Outputs 中的 Chart、Line Chart、Scatter Chart、Plot Function、Plot With Parameter	由页面绘制的图表
表格	表格，带有视图选择器——Table、Line、Scatter、Bar、Histogram——以及整张表格的 CSV 下载
数字列表	这些数字，以表格或图表形式显示
Download	下载文件的链接
单元格数组	这些单元格的输出，嵌套显示

表格只把前一千行发送到页面；CSV 包含所有行。Last Prefer View 设置表格或图表输出打开时使用的视图。