✨ feat: user-help

example/exp-avs-under-root-doc.js

@@ -0,0 +1,9 @@
+//!js
+const query = async () => {
+    const root_id = Query.root_id
+    const sql = `select * from blocks where type='av' and path like '%${dv.root_id}%'`;
+    const blocks = await Query.sql(sql);
+    return blocks.pick('id')
+}
+
+return query();

example/exp-outline.js

@@ -1,9 +1,8 @@
 //!js
 const query = async () => {
     let dv = Query.DataView(protyle, item, top);
-    let docId = dv.root_id;
     let ans = await Query.request('/api/outline/getDocOutline', {
-        id: docId
+        id: Query.root_id(protyle)
     });
     const iterate = (data) => {
         for (let item of data) {

public/i18n/en_US.yaml

@@ -22,7 +22,7 @@ src_setting_indexts:
   defaultcolumnsofdataviewtable: When calling DataView.table, the default columns
     to be displayed, separated by commas; leaving it blank means showing all columns
   echarts_renderer: Echarts renderer
-  echarts_renderer_option: 'Echarts renderer, which can be "canvas" or "svg", default "svg"'
+  echarts_renderer_option: Echarts renderer, which can be "canvas" or "svg", default is "svg"
   import_failed: Import failed. Please check the console error for details.
   import_success: Import succeeded. There are a total of {cnt} custom views.
   local_command_desc: The local command used to open the code editor, by default it
@@ -33,3 +33,13 @@ src_setting_indexts:
   table_default_columns: 🔑 Default columns displayed in table view
   user_custom_view: User custom view
   user_self_written_view: User self-written View component, stored under '/data/public/custom-query-view.js'
+src_userhelp_indexts:
+  create_notebook: Please create at least one notebook to store the help documents
+  download: Download
+  help_doc: Help Document
+  help_doc_2: Help Document
+user_help:
+  ahead_hint: |
+    > 💡 Note: This document is automatically generated by the SiYuan Query&View plugin **{{version}}** for the plugin's README documentation.
+    > You can place this document anywhere in SiYuan. If the plugin fails to find this document when it needs to be opened, it will automatically create a new one.
+    > Please do not record anything valuable to you in this document, as the information recorded here is likely to be lost when the user document is recreated!

public/i18n/zh_CN.yaml

@@ -19,10 +19,21 @@ src_setting_indexts:
   echarts_renderer_option: Echarts 渲染器，可以为 "canvas" 或 "svg", 默认 "svg"
   import_failed: 导入失败, 详细情况请检查控制台报错
   import_success: 导入成功, 共 {cnt} 个自定义视图
-  local_command_desc: 本地用于打开代码编辑器的命令, 默认为 "code -w {{filepath}}" 代表使用 VSCode 打开, 其中 {{filepath}} 在运行时会被替换为真实的代码文件
+  local_command_desc: |
+    本地用于打开代码编辑器的命令, 默认为 "code -w {{filepath}}" 代表使用 VSCode 打开, 其中 {{filepath}} 在运行时会被替换为真实的代码文件
   open_local_editor: ✒️ 打开本地编辑器
   reload: 重新加载
   table_default_columns: 🔑 表格视图默认显示列
   user_custom_view: 用户自定义视图
   user_self_written_view: 用户自行编写的 View 组件, 存放在 '/data/public/custom-query-view.js'
     下
+src_userhelp_indexts:
+  create_notebook: 请至少先创建一个笔记本用于存放帮助文档
+  download: 下载
+  help_doc: 帮助文档
+  help_doc_2: 帮助文档
+user_help:
+  ahead_hint: |
+    > 💡 注: 本文档由 SiYuan Query&View 插件 **{{version}}** 版自动生成，为插件的 README 文档。
+    > 你可以将本文档放在思源的任何地方，如果插件在需要打开的时候未能找到本文档，将会自动创建一个新的文档。
+    > 请不要在这个文档中记录任何对你有价值的东西，这些记录在本文档中的信息很有可能随着重新创建用户文档而丢失！

public/types.d.ts

@@ -1,3 +1,10 @@
+/**
+ * @name sy-query-view
+ * @author frostime
+ * @version 1.0.0-beta8
+ * @updated 2024-12-11T04:49:55.328Z
+ */
+
 declare module 'siyuan' {
     interface IProtyle {
         [key: string]: any;
@@ -13,6 +20,7 @@ declare function request(url: string, data: any): Promise<any | null>;
 ///@query.d.ts
 import { IProtyle } from "siyuan";
 
+
 /**
  * Data class for SiYuan timestamp
  * In SiYuan, the timestamp is in the format of yyyyMMddHHmmss
@@ -34,6 +42,10 @@ declare const Query: {
      * @returns DataView instance
      */
     DataView: (protyle: IProtyle, item: HTMLElement, top: number | null) => DataView;
+    /**
+     * Utility for query
+     * Every function here is sync function, no need to await
+     */
     Utils: {
         Date: (value: string | number | Date) => SiYuanDate;
         /**
@@ -93,14 +105,12 @@ declare const Query: {
          * Converts a block to a SiYuan link format
          * @param b - Block to convert
          * @returns String in markdown link format
-         * @alias asRef
          */
         asLink: (b: Block) => string;
         /**
          * Converts a block to a SiYuan reference format
          * @param b - Block to convert
          * @returns String in reference format ((id 'content'))
-         * @alias asLink
          */
         asRef: (b: Block) => string;
         asMap: (blocks: Block[], key?: string) => {
@@ -117,7 +127,6 @@ declare const Query: {
          * Gets the name of a notebook by its ID; equivalent to `notebook(boxid).name`
          * @param boxid - Notebook ID
          * @returns Notebook name
-         * @alias boxname
          * @example
          * Query.Utils.boxName(block['box']) // 'Notebook 123'
          */
@@ -160,14 +169,15 @@ declare const Query: {
      * Gets blocks by their IDs
      * @param ids - Block IDs to retrieve
      * @returns Array of wrapped blocks
+     * @alias `id2block`
      */
-    getBlocksByIds: (...ids: BlockId[]) => Promise<IWrappedBlock[]>;
+    getBlocksByIds: (...ids: BlockId[]) => Promise<IWrappedList<IWrappedBlock>>;
     /**
      * Gets the current document's ID
      * @param protyle - Protyle instance
      * @returns Document ID
      */
-    docid: (protyle: IProtyle) => string;
+    root_id: (protyle: IProtyle) => string;
     /**
      * Gets the current document as a block
      * @param protyle - Protyle instance
@@ -180,14 +190,14 @@ declare const Query: {
      * @param wrap - Whether to wrap results
      * @returns Query results
      */
-    sql: (fmt: string, wrap?: boolean) => Promise<any[]>;
+    sql: (fmt: string, wrap?: boolean) => Promise<IWrappedList<IWrappedBlock>>;
     /**
      * Finds backlinks to a specific block
      * @param id - Block ID to find backlinks for
      * @param limit - Maximum number of results
      * @returns Array of blocks linking to the specified block
      */
-    backlink: (id: BlockId, limit?: number) => Promise<any[]>;
+    backlink: (id: BlockId, limit?: number) => Promise<IWrappedList<IWrappedBlock>>;
     /**
      * Finds blocks with specific attributes
      * @param name - Attribute name
@@ -196,46 +206,72 @@ declare const Query: {
      * @param limit - Maximum number of results
      * @returns Array of matching blocks
      */
-    attr: (name: string, val?: string, valMatch?: "=" | "like", limit?: number) => Promise<any[]>;
+    attr: (name: string, val?: string, valMatch?: "=" | "like", limit?: number) => Promise<IWrappedList<IWrappedBlock>>;
     /**
      * Find unsolved task blocks
      * @param limit - Maximum number of results
      * @returns Array of unsolved task blocks
      */
-    task: (limit?: number) => Promise<any[]>;
+    task: (limit?: number) => Promise<IWrappedList<IWrappedBlock>>;
     /**
      * Randomly roam blocks
      * @param limit - Maximum number of results
      * @param type - Block type
      * @returns Array of randomly roamed blocks
      */
-    random: (limit?: number, type?: BlockType) => Promise<any[]>;
+    random: (limit?: number, type?: BlockType) => Promise<IWrappedList<IWrappedBlock>>;
     /**
      * Gets the daily notes document
-     * @param limit - Maximum number of results
      * @param notebook - Notebook ID, if not specified, all daily notes documents will be returned
+     * @param limit - Maximum number of results
      * @returns Array of daily notes document blocks
      */
-    dailynote: (limit?: number, notebook?: NotebookId) => Promise<any[]>;
+    dailynote: (notebook?: NotebookId, limit?: number) => Promise<IWrappedList<IWrappedBlock>>;
     /**
      * Gets child documents of a block
      * @param b - Parent block or block ID
      * @returns Array of child document blocks
      */
-    childdoc: (b: BlockId | Block) => Promise<IWrappedList<IWrappedBlock>>;
+    childDoc: (b: BlockId | Block) => Promise<IWrappedList<IWrappedBlock>>;
+    /**
+     * Search the document that contains all the keywords
+     * @param keywords
+     * @returns The document blocks that contains all the given keywords
+     */
+    keywordDoc: (...keywords: string[]) => Promise<any[]>;
     /**
      * Return the markdown content of the document of the given block
      * @param block - Block
-     * @returns
+     * @returns Markdown content of the document
+     */
+    docMd: (id: BlockId) => Promise<any>;
+    /**
+     * Return the statistics of the document with given document ID
+     * @param docId The ID of document
+     * @returns The statistics of the document
+     * @returns.runeCount - The number of characters in the document
+     * @returns.wordCount - The number of words (Chinese characters are counted as one word) in the document
+     * @returns.linkCount - The number of links in the document
+     * @returns.imageCount - The number of images in the document
+     * @returns.refCount - The number of references in the document
+     * @returns.blockCount - The number of blocks in the document
      */
-    docMd: (block: Block) => Promise<any>;
+    docStat: (docId: DocumentId) => Promise<{
+        "runeCount": number;
+        "wordCount": number;
+        "linkCount": number;
+        "imageCount": number;
+        "refCount": number;
+        "blockCount": number;
+    }>;
     /**
      * Redirects first block IDs to their parent containers
      * @param inputs - Array of blocks or block IDs
      * @param enable - Configuration for heading and doc processing
      * @param enable.heading - Whether to process heading blocks
      * @param enable.doc - Whether to process document blocks
      * @returns Processed blocks or block IDs
+     * @alias `redirect`
      */
     fb2p: (inputs: Block[], enable?: {
         heading?: boolean;

scripts/export-types.js

@@ -14,6 +14,10 @@ process.chdir(path.join(__dirname, '..'));
 console.log(process.cwd());
 const dirname = process.cwd();
 
+// 读取 plugin.json
+const pluginJson = fs.readFileSync('./plugin.json', 'utf8');
+const plugin = JSON.parse(pluginJson);
+
 const removeTypesDir = () => {
     if (fs.existsSync('./types')) {
         fs.rmSync('./types', { recursive: true, force: true });
@@ -67,6 +71,13 @@ const replaceSomething = (content, lines = []) => {
 }
 
 writer.append(`
+/**
+ * @name ${plugin.name}
+ * @author ${plugin.author}
+ * @version ${plugin.version}
+ * @updated ${new Date().toISOString()}
+ */
+
 declare module 'siyuan' {
     interface IProtyle {
         [key: string]: any;
@@ -82,7 +93,10 @@ declare function request(url: string, data: any): Promise<any | null>;
 
 writer.append('///@query.d.ts\n');
 let query = readFile('./types/core/query.d.ts');
-query = replaceSomething(query, ['import { request } from "@/api";']);
+query = replaceSomething(query, [
+    'import { request } from "@/api";',
+    'import { IWrappedBlock, IWrappedList } from "./proxy";'
+]);
 writer.append(query);
 writer.append('\n');