diff --git a/README.md b/README.md index aff3842..3a9cd08 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,9 @@ The embedded block feature of SiYuan supports querying using JavaScript syntax. > You can download it and click the "Help Document" button in the top-left menu. The plugin will automatically create a help document within SiYuan. > > ​![image](assets/image-20241211194348-sfzl8pc.png)​ +> +> The help documentation will include the latest API type definitions for the plugin. +> If you are only interested in reviewing the interface content and not the other parts of the help documentation, you can set "User documentation only imports type references" to `true`​ in the plugin settings. ## 0. Quick Overview of Features @@ -488,6 +491,12 @@ interface IWrappedBlock extends Block { /** Block's SiYuan reference format text */ asref: string; + /** Blocks's ial list, as object + * @example + * let icon = block.asial['icon']; + */ + asial: Record; + /** * Returns a rendered SiYuan attribute * @param attr - Attribute name @@ -515,12 +524,13 @@ interface IWrappedBlock extends Block { All properties can be grouped into several categories: 1. Rendering as links or references, i.e., `aslink`​, `asref`​ (however, since rendering as a reference does not actually create a relationship in the ref table, most of the time using link is sufficient, and ref is not very meaningful). -2. Timestamp-related: Additional properties are extended for updated, created, etc., to facilitate direct display of block timestamps. -3. ​`attr`​ function: +2. ​`asial`​: The ial list of the block itself is a string field. Using this method, the ial can be parsed into an object of type `{ [key: string]: string}`​ +3. Timestamp-related: Additional properties are extended for updated, created, etc., to facilitate direct display of block timestamps. +4. ​`attr`​ function: * Takes a block and block attribute and the return will be rendered as suitable markdown text (as mentioned in the table section earlier). * You can also pass a custom renderer and return a markdown text. If no return or return null, the default rendering scheme is used. -4. ​`custom-xxx`​ properties: Directly access the block's custom attributes, e.g., `block['custom-b']`​, which accesses the `custom-b`​ attribute of the corresponding block. +5. ​`custom-xxx`​ properties: Directly access the block's custom attributes, e.g., `block['custom-b']`​, which accesses the `custom-b`​ attribute of the corresponding block. You can try the following code, and get to know there differences. @@ -2087,7 +2097,9 @@ The plugin provides a button in the block menu to directly perform the above con ​![image](assets/image-20241209001506-1j38x18.png)​ -## Complete API +## Reference + +​``​ > Note: Since the interface file will change with development, the README itself does not include the interface code but some placeholders. > @@ -2105,18 +2117,20 @@ The plugin provides a button in the block menu to directly perform the above con {{Query}} ``` -### DataView +### IWrapBlock & IWrapList ```ts -{{DataView}} +{{Proxy}} ``` -### IWrapBlock & IWrapList +### DataView ```ts -{{Proxy}} +{{DataView}} ``` +​``​ + ## Example Demonstrations Some example codes are provided. Some cases have actually appeared in the above documentation. diff --git a/README_zh_CN.md b/README_zh_CN.md index f351066..0eb939b 100644 --- a/README_zh_CN.md +++ b/README_zh_CN.md @@ -8,6 +8,9 @@ > 你可以在下载下来之后,点击左上角菜单按钮中的“帮助文档”按钮,插件会自动在思源内创建一个帮助文档。 > > ​![image](assets/image-20241211194348-sfzl8pc.png)​ +> +> 帮助文档中会包含插件最新的 API 类型定义接口。 +> 如果你只想要查阅接口内容而对帮助文档的其他部分不感兴趣,可以在插件中将“用户文档只导入类型参考”设置为 `true`​。 ## 0. 功能速览 @@ -484,6 +487,12 @@ interface IWrappedBlock extends Block { /** Block's SiYuan reference format text */ asref: string; + /** Blocks's ial list, as object + * @example + * let icon = block.asial['icon']; + */ + asial: Record; + /** * Returns a rendered SiYuan attribute * @param attr - Attribute name @@ -511,12 +520,13 @@ interface IWrappedBlock extends Block { 以上所有的属性可以分为几组来理解: 1. 渲染为链接或者引用,也就是 `aslink`​, `asref`​ 这些(不过实际上由于渲染成为引用并不会真的在 ref 表中创建关联关系,所以大部分时候使用 link 就可以了,ref 的意义不大) -2. 时间戳相关:额外为 updated,created 这些拓展了一些属性,方便直接用来展示块的时间戳 -3. ​`attr`​ 函数: +2. ​`asial`​:块的 ial 列表本身为一个字符串字段,使用这个方法,可以把 ial 解析为一个 `{ [key: string]: string}`​ 的对象 +3. 时间戳相关:额外为 updated,created 这些拓展了一些属性,方便直接用来展示块的时间戳 +4. ​`attr`​ 函数: * 传入块和块的属性,会讲块的属性渲染为合适的 markdown 文本(就像我们前面在 table 小节提到的那样) * 你也可以自己传入一个自定义的 renderer,然后返回一段 markdown 文本,如果没有返回或者返回 null,则回退到默认的渲染方案 -4. ​`custom-xxx`​ 属性,可以直接访问块的自定义属性,例如 `block['custom-b']`​,会访问对应块的 `custom-b`​ 属性。 +5. ​`custom-xxx`​ 属性,可以直接访问块的自定义属性,例如 `block['custom-b']`​,会访问对应块的 `custom-b`​ 属性。 你可以尝试一下下面的代码,会有直观的区别: @@ -2087,7 +2097,9 @@ dv.render(); ​![image](assets/image-20241209001506-1j38x18.png)​ -## 完整 API +## Reference + +​``​ > 注:由于接口文件会随着开发而变动,所以 README 本体中并不包含 interface 代码,而是放了一些 placeholder 。 > @@ -2105,18 +2117,20 @@ dv.render(); {{Query}} ``` -### DataView +### IWrapBlock & IWrapList ```ts -{{DataView}} +{{Proxy}} ``` -### IWrapBlock & IWrapList +### DataView ```ts -{{Proxy}} +{{DataView}} ``` +​``​ + ## 案例演示 提供了一些 example 代码。部分案例在上面的文档中其实已经出现过了。 diff --git a/public/i18n/en_US.yaml b/public/i18n/en_US.yaml index b1739b8..c3d9225 100644 --- a/public/i18n/en_US.yaml +++ b/public/i18n/en_US.yaml @@ -33,9 +33,14 @@ src_setting_indexts: is "code -w {{filepath}}" which represents opening with VSCode, where {{filepath}} will be replaced with the actual code file at runtime open_local_editor: ✒️ Open Local Editor + plugin_import_help_doc: The plugin allows the help documentation to be imported + into SiYuan. By default, the complete README document and TypeScript Reference + will be imported. If this option is enabled, only the Reference part will be imported + during the import and no other parts. reload: Reload table_default_columns: 🔑 Default columns displayed in table view user_custom_view: User custom view + user_doc_import_type_ref: User documentation only imports type references user_self_written_view: User self-written View component, stored under '/data/public/custom-query-view.js' src_userhelp_examplests: backlinks_table: Display backlinks of the current document in a table format @@ -95,6 +100,8 @@ src_userhelp_indexts: the following two lines src_userhelp_sydocts: create_user_doc: 'Create user documentation:' + plugin_setting_doc: '> 🖊️ Due to your settings in the plugin, this help document only + contains the type definitions of the API.' plugin_update_doc: Detected plugin version update, updating documentation, please wait... user_help: diff --git a/public/i18n/zh_CN.yaml b/public/i18n/zh_CN.yaml index 005e4cf..7545def 100644 --- a/public/i18n/zh_CN.yaml +++ b/public/i18n/zh_CN.yaml @@ -25,9 +25,12 @@ src_setting_indexts: local_command_desc: 本地用于打开代码编辑器的命令, 默认为 "code -w {{filepath}}" 代表使用 VSCode 打开, 其中 {{filepath}} 在运行时会被替换为真实的代码文件 open_local_editor: ✒️ 打开本地编辑器 + plugin_import_help_doc: 插件允许将帮助文档导入到思源笔记中,默认情况下会导入完整的 README 文档以及 Tyepscript Reference;如果开启了这个选项,那么在导入的时候将只导入 + Reference 部分而不会导入其余部分 reload: 重新加载 table_default_columns: 🔑 表格视图默认显示列 user_custom_view: 用户自定义视图 + user_doc_import_type_ref: 用户文档只导入类型参考 user_self_written_view: 用户自行编写的 View 组件, 存放在 '/data/public/custom-query-view.js' 下 src_userhelp_examplests: @@ -64,6 +67,7 @@ src_userhelp_indexts: useview2: 如果要使用 DataView 请注释上面的 return, 并取消下方两行注释 src_userhelp_sydocts: create_user_doc: '创建用户文档:' + plugin_setting_doc: '> 🖊️ 由于你在插件中的设置,此帮助文档只包含了 API 的类型定义。' plugin_update_doc: 检查到插件版本已更新,正在更新文档,请稍等... user_help: ahead_hint: | diff --git a/public/types.d.ts b/public/types.d.ts index dfb9aa1..5327cf7 100644 --- a/public/types.d.ts +++ b/public/types.d.ts @@ -2,7 +2,7 @@ * @name sy-query-view * @author frostime * @version 1.0.2 - * @updated 2024-12-20T13:21:00.445Z + * @updated 2024-12-20T14:03:43.400Z */ declare module 'siyuan' { diff --git a/src/setting/index.ts b/src/setting/index.ts index 4e9e66c..b624009 100644 --- a/src/setting/index.ts +++ b/src/setting/index.ts @@ -3,7 +3,7 @@ * @Author : frostime * @Date : 2024-12-01 16:25:57 * @FilePath : /src/setting/index.ts - * @LastEditTime : 2024-12-13 12:48:22 + * @LastEditTime : 2024-12-20 21:58:58 * @Description : */ @@ -17,7 +17,8 @@ import { loadUserCustomView } from "@/core/custom-view"; let defaultSetting = { codeEditor: 'code -w {{filepath}}', defaultTableColumns: ['type', 'content', 'hpath', 'box'].join(','), - echartsRenderer: 'svg' + echartsRenderer: 'svg', + onlyImportDtsInUserDoc: true }; let settingUtils: SettingUtils; @@ -58,6 +59,13 @@ export const load = async (plugin: Plugin) => { key: 'apiDoc', value: '', }); + settingUtils.addItem({ + type: 'checkbox', + title: i18n.src_setting_indexts.user_doc_import_type_ref, + description: i18n.src_setting_indexts.plugin_import_help_doc, + key: 'onlyImportDtsInUserDoc', + value: defaultSetting.onlyImportDtsInUserDoc, + }); settingUtils.addItem({ type: 'textinput', title: i18n.src_setting_indexts.open_local_editor, diff --git a/src/types/i18n.d.ts b/src/types/i18n.d.ts index 6903c63..114e2ee 100644 --- a/src/types/i18n.d.ts +++ b/src/types/i18n.d.ts @@ -30,9 +30,11 @@ interface I18n { import_success: string; local_command_desc: string; open_local_editor: string; + plugin_import_help_doc: string; reload: string; table_default_columns: string; user_custom_view: string; + user_doc_import_type_ref: string; user_self_written_view: string; }; src_userhelp_examplests: { @@ -68,6 +70,7 @@ interface I18n { }; src_userhelp_sydocts: { create_user_doc: string; + plugin_setting_doc: string; plugin_update_doc: string; }; user_help: { diff --git a/src/user-help/sy-doc.ts b/src/user-help/sy-doc.ts index 10693cf..51edff4 100644 --- a/src/user-help/sy-doc.ts +++ b/src/user-help/sy-doc.ts @@ -3,6 +3,7 @@ import type QueryViewPlugin from "@/index"; import { openBlock } from "@/utils"; import { confirm, showMessage } from "siyuan"; import { i18n } from "@/index"; +import { setting } from "@/setting"; const CUSTOM_USER_README_ATTR = 'custom-query-view-user-readme'; @@ -38,6 +39,22 @@ const createReadmeText = async (plugin: QueryViewPlugin) => { const response = await fetch(`/plugins/sy-query-view/${fname}`); let readme = await response.text(); + if (setting.onlyImportDtsInUserDoc) { + // 找到 ​``​ 和 ​``​ 之间的内容 + const start = '``'; + const end = '``'; + const startIndex = readme.indexOf(start); + const endIndex = readme.indexOf(end); + + const hint = i18n.src_userhelp_sydocts.plugin_setting_doc; + + if (startIndex !== -1 && endIndex !== -1) { + readme = readme.substring(startIndex + start.length, endIndex).trim(); + } + + readme = hint + '\n\n' + readme; + } + const AheadHint = i18n.user_help.ahead_hint.trim(); let ahead = AheadHint.replace('{{version}}', plugin.version); readme = ahead + '\n' + OutlineCode + '\n\n' + readme; diff --git a/vite.config.ts b/vite.config.ts index 4a3c45b..69ee881 100644 --- a/vite.config.ts +++ b/vite.config.ts @@ -267,8 +267,8 @@ function replaceMDImgUrl(dirname: string) { } const prefix_github = 'https://github.com/frostime/sy-query-view/raw/main'; - // const prefix_cdn = 'https://cdn.jsdelivr.net/gh/frostime/sy-query-view@main'; - const prefix_cdn = 'https://ghp.ci/https://github.com/frostime/sy-query-view/raw/main'; + const prefix_cdn = 'https://cdn.jsdelivr.net/gh/frostime/sy-query-view@main'; + // const prefix_cdn = 'https://ghgo.xyz/https://github.com/frostime/sy-query-view/raw/main'; let readmePath = resolve(dirname, 'README.md'); await replace(readmePath, prefix_github);