更新使用文档

README.md

@@ -1,5 +1,9 @@
 # 思源表达式插件
 
+[使用文档](#使用文档)
+
+qq群：706761641 （心栈空间）
+
 ### 同意以下约定后方可使用本产品
 
 试用约定：
@@ -12,11 +16,11 @@
 
 在订阅时间内你可以使用本产品。
 
-  视同订阅的情况：你对崮生本人有过任意形式的帮助、你对社会有过公认的贡献、无法支付。
+视同订阅的情况：你对崮生本人有过任意形式的帮助、你对社会有过公认的贡献、无法支付。
 
-  订阅金额：等价10人民币，可采取任意支付方式，不限制时间（你可以决定任意时间后采取任意付费措施，但现在就开始使用）。
+订阅金额：等价 10 人民币，可采取任意支付方式，不限制时间（你可以决定任意时间后采取任意付费措施，但现在就开始使用）。
 
-  订阅时间：从付费之时到一百次产品更新的使用权或365天，取时间跨度更长的作为订阅时间，可叠加。（即如果我在极短时间内更新了超过一百次则按一年计算）
+订阅时间：从付费之时到一百次产品更新的使用权或 365 天，取时间跨度更长的作为订阅时间，可叠加。（即如果我在极短时间内更新了超过一百次则按一年计算）
 
 [通过爱发电平台付费](https://afdian.net/@llej0)
 
@@ -28,4 +32,60 @@
 
 禁止使用本产品用于任意违法乱纪相关行为。
 
-作者不为你使用本产品所产生的任何后果负责。
+作者不为你使用本产品所产生的任何后果负责。
+
+## 使用文档
+
+给块添加自定义属性 expr ，值设置为合法 js 表达式，插件会使用 eval 对表达式进行求值，返回值将作为块内容以及自定义属性 expr-_value 的值。
+
+值如果为 Promise 会将 Promise 的结果作为块内容。
+
+### 自动求值
+
+插件会不断对发生变化的块进行求值，但为了避免产生大量运算和读写，依据块的 update 字段进行了一些优化，在插件初次启动时会对所有表达式进行一次求值，之后只会对更新了的块的表达式进行求值。
+
+注意！[更新块属性并不会导致块的 update 字段更新](https://github.com/2234839/siyuan_expr/issues/1#issuecomment-2147809646),如果想要触发求值，可以手动随意修改一下块内容。
+
+### 表达式内可以直接引用的一些特殊变量
+
+#### expr
+
+插件实例
+
+#### block
+
+表达式可以直接输入 block 来获取表达式所在块的数据,其中以 `a_` 开头的为custom-expr的属性，其余均为块属性。
+
+```js
+const block = {
+    a_block_id: "块id",
+    a_box: "笔记本id",
+    a_id: "属性id",
+    a_name: "custom-expr",
+    a_path: "/文档id/文档id/文档id.sy",
+    a_root_id: "文档id",
+    a_type: "b",
+    a_value: "表达式脚本",
+    alias: "",
+    box: "笔记本id",
+    content: "块内容",
+    created: "20240605121837",
+    fcontent: "",
+    hash: "f570917",
+    hpath: "可读路径",
+    ial: "块属性"
+    id: "块id",
+    length: 16,
+    markdown: "块内容 markdown",
+    memo: "",
+    name: "",
+    parent_id: "父块id",
+    path: "/文档id/文档id/文档id.sy",
+    root_id: "文档id",
+    sort: 10,
+    subtype: "",
+    tag: "",
+    type: "p",
+    updated: "20240605134312"
+}
+```

package.json

@@ -1,6 +1,6 @@
 {
   "name": "expr",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "type": "module",
   "description": "",
   "repository": "https://github.com/2234839/siyuan_expr",

plugin.json

@@ -2,7 +2,7 @@
   "name": "expr",
   "author": "崮生_子虚",
   "url": "https://github.com/2234839/siyuan_expr",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "minAppVersion": "2.10.3",
   "backends": [
     "all"

src/index.ts

@@ -13,38 +13,42 @@ type MergedBlock = aliasAttribute & Block;
 
 const dev = console.log;
 declare global {
-  var Expr: Expr;
+  var expr: Expr;
 }
 export default class Expr extends Plugin {
   IntervalId = 0;
+  /** 主循环的间隔毫秒数 */
+  intervalMs = 1_000;
   /** 只更新这个时间戳以后的表达式 */
   updated = 0;
   /** 为 true 代表正在进行求值运算中 */
   evalState = false;
   async onload() {
-    globalThis.Expr = this;
-    this.onunloadFn.push(() => {
-      //@ts-ignore
-      delete globalThis.Expr;
-    });
+    /** 注册Expr实例到全局变量 */
+    globalThis.expr = this;
+    this.onunloadFn.push(
+      () =>
+        //@ts-ignore
+        delete globalThis.expr,
+    );
 
-    const updateExprEval = this.updateExprEval.bind(this);
-    this.IntervalId = setInterval(updateExprEval, 1_000);
-    updateExprEval();
+    /** 注册求值循环 */
+    this.IntervalId = setInterval(this.evalAllExpr.bind(this), this.intervalMs);
     this.onunloadFn.push(() => clearInterval(this.IntervalId));
 
+    /** 在 body 上注册插件类名，用于控制样式的开关 */
     document.body.classList.add(pluginClassName);
     this.onunloadFn.push(() => document.body.classList.remove(pluginClassName));
   }
 
+  /** 插件卸载时会执行此数组中的函数 */
   onunloadFn = [] as (() => void)[];
   async onunload() {
-    dev("expr plugin unload");
     this.onunloadFn.forEach((fn) => fn());
   }
 
-  /** 对最近更新过的表达式进行求值 */
-  async updateExprEval() {
+  /** 对所有表达式进行求值 */
+  async evalAllExpr() {
     if (this.evalState) {
       /** 只有上一轮求值计算进行完毕后才会开始新一轮计算 */
       return;
@@ -60,7 +64,6 @@ export default class Expr extends Plugin {
       ORDER BY b.updated DESC;`,
       );
       if (exprAttr.length > 0) {
-        console.log(exprAttr, this.updated);
         await Promise.all(exprAttr.map(this.exprEval.bind(this)));
       }
     } catch (error) {
@@ -100,7 +103,7 @@ export default class Expr extends Plugin {
     // custom-expr-value="-0.56273369360008952"
     /** 将求值结果更新到块文本 */
     await updateBlock("markdown", String(evalValue + "\n" + newKramdownAttr), block.id);
-    dev(newKramdownAttr, this.updated);
+    dev(block.id,block.a_value, evalValue);
   }
 }
 

vite.config.ts

@@ -6,11 +6,11 @@ import livereload from "rollup-plugin-livereload";
 import zipPack from "vite-plugin-zip-pack";
 import fg from "fast-glob";
 import { siyuan } from "@llej/js_util";
-/** 自动更新plugin.json */
 import { writeFile } from "fs/promises";
+
 import pluginJSON from "./plugin.json";
 import pkg from "./package.json";
-
+/** 自动更新plugin.json */
 writeFile("./plugin.json", JSON.stringify(siyuan.mergePluginPackage(pkg, pluginJSON), null, 2));
 
 const args = minimist(process.argv.slice(2));
@@ -93,7 +93,7 @@ export default defineConfig({
                 //监听静态资源文件
                 name: "watch-external",
                 async buildStart() {
-                  const files = await fg(["src/i18n/*.json", "./README*.md", "./plugin.json"]);
+                  const files = await fg(["src/i18n/*.json","./plugin.json"]);
                   for (let file of files) {
                     this.addWatchFile(file);
                   }
@@ -121,7 +121,7 @@ export default defineConfig({
           }
           return assetInfo.name!;
         },
-        //TODO 这里使用伺服模式有问题，但我不知道如何解决,反正这个功能也基本就开发者使用，就这样吧。
+        //TODO 这里在非localhost下有问题，但我不知道如何解决,反正这个功能也基本就开发者使用，就这样吧。
         sourcemapBaseUrl: `http://localhost:6806/plugins/${pluginJSON.name}/`,
         sourcemapPathTransform: (sourcePath) => {
           return `${pluginJSON.name}/${sourcePath}`;