From 4ee1dd6bae59650cb4c80b04ddc6e039899b09f7 Mon Sep 17 00:00:00 2001 From: geoffreychen777 Date: Sun, 30 Jun 2024 15:17:42 +0100 Subject: [PATCH] update: new api doc --- .../extension-doc/plapi/preference-service.md | 1 + src/cn/extension-doc/plapi/scrape-service.md | 11 +++++ src/cn/extension-doc/plapi/uislot-service.md | 10 +++++ src/cn/extension-doc/plapi/uistate-service.md | 4 +- .../plmainapi/contextmenu-service.md | 1 + .../plmainapi/filesystem-service.md | 2 +- src/cn/extension-doc/process-hook.md | 37 +++++++++++++++++ src/cn/extension-doc/ui-slot.md | 9 ++++- .../extension-doc/plapi/preference-service.md | 1 + src/en/extension-doc/plapi/scrape-service.md | 10 +++++ src/en/extension-doc/plapi/uislot-service.md | 10 +++++ src/en/extension-doc/plapi/uistate-service.md | 4 +- .../plmainapi/contextmenu-service.md | 1 + .../plmainapi/filesystem-service.md | 2 +- src/en/extension-doc/process-hook.md | 40 ++++++++++++++++++- src/en/extension-doc/ui-slot.md | 8 +++- 16 files changed, 144 insertions(+), 7 deletions(-) diff --git a/src/cn/extension-doc/plapi/preference-service.md b/src/cn/extension-doc/plapi/preference-service.md index e18fb04..14f4ea6 100644 --- a/src/cn/extension-doc/plapi/preference-service.md +++ b/src/cn/extension-doc/plapi/preference-service.md @@ -108,6 +108,7 @@ declare interface IPreferenceStore { shortcutFlag: string; shortcutCopyKey: string; shortcutDelete: string; + shortcutImportFrom: string; sidebarWidth: number; detailPanelWidth: number; mainviewSortBy: string; diff --git a/src/cn/extension-doc/plapi/scrape-service.md b/src/cn/extension-doc/plapi/scrape-service.md index 46bbef2..e80cdcf 100644 --- a/src/cn/extension-doc/plapi/scrape-service.md +++ b/src/cn/extension-doc/plapi/scrape-service.md @@ -42,4 +42,15 @@ scrapeEntry(payloads: any[]): Promise; * @param force - force scraping metadata. * @returns List of paper entities. */ scrapeMetadata(paperEntityDrafts: PaperEntity[], scrapers: string[], force?: boolean): Promise; +``` + + +### `fuzzyScrape` + +```typescript +/** + * Scrape a data source's metadata fuzzily. + * @param payloads - data source payloads. + * @returns List of paper entities' candidates. */ +fuzzyScrape(paperEntities: IPaperEntityCollection): Promise>; ``` \ No newline at end of file diff --git a/src/cn/extension-doc/plapi/uislot-service.md b/src/cn/extension-doc/plapi/uislot-service.md index 2d4b957..612811a 100644 --- a/src/cn/extension-doc/plapi/uislot-service.md +++ b/src/cn/extension-doc/plapi/uislot-service.md @@ -22,6 +22,16 @@ updateSlot(slotID: keyof IUISlotState, patch: { }): Promise; ``` +```typescript +/** + * Delete an item from a slot + * @param slotID - The slot to delete from + * @param itemID - The item to delete + * @returns + */ +deleteSlotItem(slotID: keyof IUISlotState, itemID: string): void; +``` + ## Avaliable Slots ```typescript diff --git a/src/cn/extension-doc/plapi/uistate-service.md b/src/cn/extension-doc/plapi/uistate-service.md index 37b515f..65a3d60 100644 --- a/src/cn/extension-doc/plapi/uistate-service.md +++ b/src/cn/extension-doc/plapi/uistate-service.md @@ -79,7 +79,9 @@ interface IUIStateServiceState { // It can be accessed in any component. But it is read-only. It can be only changed by the event listener of selectedIndex in the dataview. selectedPaperEntities: Array; selectedFeedEntities: Array; - selectedQuerySentenceId: string; + selectedQuerySentenceIds: string[]; + showingCandidatesId: string; + metadataCandidates: Record; selectedFeed: string; editingPaperSmartFilter: PaperSmartFilter; querySentenceSidebar: string; diff --git a/src/cn/extension-doc/plmainapi/contextmenu-service.md b/src/cn/extension-doc/plmainapi/contextmenu-service.md index 743665d..9b0e0ad 100644 --- a/src/cn/extension-doc/plmainapi/contextmenu-service.md +++ b/src/cn/extension-doc/plmainapi/contextmenu-service.md @@ -62,6 +62,7 @@ unregisterContextMenu(extID: string): void; | `dataContextMenuShowInFinderClicked` | `{key: 'dataContextMenuShowInFinderClicked'}` | When `Show in Finder` is clicked in the context menu of a paper in the library | | `dataContextMenuEditClicked` | `{key: 'dataContextMenuEditClicked'}` | When `Edit` is clicked in the context menu of a paper in the library | | `dataContextMenuScrapeClicked` | `{key: 'dataContextMenuScrapeClicked'}` | When `Scrape` is clicked in the context menu of a paper in the library | +| `dataContextMenuFuzzyScrapeClicked` | `{key: 'dataContextMenuFuzzyScrapeClicked'}` | When `Fuzzily Scrape` is clicked in the context menu of a paper in the library | | `dataContextMenuDeleteClicked` | `{key: 'dataContextMenuDeleteClicked'}` | When `Delete` is clicked in the context menu of a paper in the library | | `dataContextMenuFlagClicked` | `{key: 'dataContextMenuFlagClicked'}` | When `Flag` is clicked in the context menu of a paper in the library | | `dataContextMenuExportBibTexClicked` | `{key: 'dataContextMenuExportBibTexClicked'}` | When `Export BibTex` is clicked in the context menu of a paper in the library | diff --git a/src/cn/extension-doc/plmainapi/filesystem-service.md b/src/cn/extension-doc/plmainapi/filesystem-service.md index b80abde..f94069d 100644 --- a/src/cn/extension-doc/plmainapi/filesystem-service.md +++ b/src/cn/extension-doc/plmainapi/filesystem-service.md @@ -28,7 +28,7 @@ getSystemPath(key: "home" | "appData" | "userData" | "sessionData" | "temp" | "e * Show a file picker. * @returns {Promise} The result of the file picker. */ -showFilePicker(): Promise; +showFilePicker(props?: Array<"openDirectory" | "multiSelections" | "showHiddenFiles" | "createDirectory" | "promptToCreate" | "noResolveAliases" | "treatPackageAsDirectory" | "dontAddToRecent">): Promise; ``` ### `showFolderPicker` diff --git a/src/cn/extension-doc/process-hook.md b/src/cn/extension-doc/process-hook.md index 59efae9..3b08575 100644 --- a/src/cn/extension-doc/process-hook.md +++ b/src/cn/extension-doc/process-hook.md @@ -246,3 +246,40 @@ interface WebContentSourcePayload { | Callback 参数 | `string` | | Callback 返回值 | 参数数组<`string`> | + +## 模糊元数据搜刮流程 + +在用户点击模糊搜索之后，用户选中的论文，会经过这个流程，得到模糊搜索的元数据。 + +该流程中，主要的钩子点都在 `ScrapeService` 的 `fuzzyScrape()` 方法中。 + +`fuzzyScrape()` 接受 `Array`, 输出 `Record>`，即每个论文的 `id` 于候选 metadata 的映射。 + +可用的钩子如下： + +### `beforeFuzzyScrape + +| 参数 | 值 | +| --- | --- | +| 类型 | `Modify` | +| 位置 | `fuzzyScrape()` 方法的最开始，还未搜寻 metadata 之前 | +| Callback 参数 | `paperEntities: PaperEntity[]` | +| Callback 返回值 | 参数数组<`paperEntities: PaperEntity[]`> | + +### `fuzzyScrape` + +| 参数 | 值 | +| --- | --- | +| 类型 | `Transform` | +| 位置 | `fuzzyScrape()` 的主要钩子点，接受 `PaperEntity` 数组，返回一个数组，每个元素是对应论文的候选匹配数组，即类型为 `PaperEntity[][]` | +| Callback 参数 | `paperEntities: PaperEntity[]` | +| Callback 返回值 | `PaperEntity[][]` | + +### `afterFuzzyScrape` + +| 参数 | 值 | +| --- | --- | +| 类型 | `Modify` | +| 位置 | `fuzzyScrape()` 方法的最后，已经搜寻 metadata 之后 | +| Callback 参数 | `paperEntityDraftCandidates: PaperEntity[][]` | +| Callback 返回值 | 参数数组<`paperEntityDraftCandidates: PaperEntity[][]`> | diff --git a/src/cn/extension-doc/ui-slot.md b/src/cn/extension-doc/ui-slot.md index 59ac745..1ba8215 100644 --- a/src/cn/extension-doc/ui-slot.md +++ b/src/cn/extension-doc/ui-slot.md @@ -46,4 +46,11 @@ PLAPI.uiSlotService.updateSlot( ``` -`id` 是内容的唯一标识符。如果 `id` 已经在插槽中，内容将被更新。否则，将添加新内容。 \ No newline at end of file +`id` 是内容的唯一标识符。如果 `id` 已经在插槽中，内容将被更新。否则，将添加新内容。 + +### 插槽删除 + +```typescript +PLAPI.uiSlotService.deleteSlotItem("paperDetailsPanelSlot1", ); +``` + diff --git a/src/en/extension-doc/plapi/preference-service.md b/src/en/extension-doc/plapi/preference-service.md index 46b9485..8b5a1ae 100644 --- a/src/en/extension-doc/plapi/preference-service.md +++ b/src/en/extension-doc/plapi/preference-service.md @@ -108,6 +108,7 @@ declare interface IPreferenceStore { shortcutFlag: string; shortcutCopyKey: string; shortcutDelete: string; + shortcutImportFrom: string; sidebarWidth: number; detailPanelWidth: number; mainviewSortBy: string; diff --git a/src/en/extension-doc/plapi/scrape-service.md b/src/en/extension-doc/plapi/scrape-service.md index 46bbef2..a78b25b 100644 --- a/src/en/extension-doc/plapi/scrape-service.md +++ b/src/en/extension-doc/plapi/scrape-service.md @@ -42,4 +42,14 @@ scrapeEntry(payloads: any[]): Promise; * @param force - force scraping metadata. * @returns List of paper entities. */ scrapeMetadata(paperEntityDrafts: PaperEntity[], scrapers: string[], force?: boolean): Promise; +``` + +### `fuzzyScrape` + +```typescript +/** + * Scrape a data source's metadata fuzzily. + * @param payloads - data source payloads. + * @returns List of paper entities' candidates. */ +fuzzyScrape(paperEntities: IPaperEntityCollection): Promise>; ``` \ No newline at end of file diff --git a/src/en/extension-doc/plapi/uislot-service.md b/src/en/extension-doc/plapi/uislot-service.md index fb15d23..9028f1e 100644 --- a/src/en/extension-doc/plapi/uislot-service.md +++ b/src/en/extension-doc/plapi/uislot-service.md @@ -22,6 +22,16 @@ updateSlot(slotID: keyof IUISlotState, patch: { }): Promise; ``` +```typescript +/** + * Delete an item from a slot + * @param slotID - The slot to delete from + * @param itemID - The item to delete + * @returns + */ +deleteSlotItem(slotID: keyof IUISlotState, itemID: string): void; +``` + ## Avaliable Slots ```typescript diff --git a/src/en/extension-doc/plapi/uistate-service.md b/src/en/extension-doc/plapi/uistate-service.md index 37b515f..65a3d60 100644 --- a/src/en/extension-doc/plapi/uistate-service.md +++ b/src/en/extension-doc/plapi/uistate-service.md @@ -79,7 +79,9 @@ interface IUIStateServiceState { // It can be accessed in any component. But it is read-only. It can be only changed by the event listener of selectedIndex in the dataview. selectedPaperEntities: Array; selectedFeedEntities: Array; - selectedQuerySentenceId: string; + selectedQuerySentenceIds: string[]; + showingCandidatesId: string; + metadataCandidates: Record; selectedFeed: string; editingPaperSmartFilter: PaperSmartFilter; querySentenceSidebar: string; diff --git a/src/en/extension-doc/plmainapi/contextmenu-service.md b/src/en/extension-doc/plmainapi/contextmenu-service.md index 743665d..9b0e0ad 100644 --- a/src/en/extension-doc/plmainapi/contextmenu-service.md +++ b/src/en/extension-doc/plmainapi/contextmenu-service.md @@ -62,6 +62,7 @@ unregisterContextMenu(extID: string): void; | `dataContextMenuShowInFinderClicked` | `{key: 'dataContextMenuShowInFinderClicked'}` | When `Show in Finder` is clicked in the context menu of a paper in the library | | `dataContextMenuEditClicked` | `{key: 'dataContextMenuEditClicked'}` | When `Edit` is clicked in the context menu of a paper in the library | | `dataContextMenuScrapeClicked` | `{key: 'dataContextMenuScrapeClicked'}` | When `Scrape` is clicked in the context menu of a paper in the library | +| `dataContextMenuFuzzyScrapeClicked` | `{key: 'dataContextMenuFuzzyScrapeClicked'}` | When `Fuzzily Scrape` is clicked in the context menu of a paper in the library | | `dataContextMenuDeleteClicked` | `{key: 'dataContextMenuDeleteClicked'}` | When `Delete` is clicked in the context menu of a paper in the library | | `dataContextMenuFlagClicked` | `{key: 'dataContextMenuFlagClicked'}` | When `Flag` is clicked in the context menu of a paper in the library | | `dataContextMenuExportBibTexClicked` | `{key: 'dataContextMenuExportBibTexClicked'}` | When `Export BibTex` is clicked in the context menu of a paper in the library | diff --git a/src/en/extension-doc/plmainapi/filesystem-service.md b/src/en/extension-doc/plmainapi/filesystem-service.md index b80abde..f94069d 100644 --- a/src/en/extension-doc/plmainapi/filesystem-service.md +++ b/src/en/extension-doc/plmainapi/filesystem-service.md @@ -28,7 +28,7 @@ getSystemPath(key: "home" | "appData" | "userData" | "sessionData" | "temp" | "e * Show a file picker. * @returns {Promise} The result of the file picker. */ -showFilePicker(): Promise; +showFilePicker(props?: Array<"openDirectory" | "multiSelections" | "showHiddenFiles" | "createDirectory" | "promptToCreate" | "noResolveAliases" | "treatPackageAsDirectory" | "dontAddToRecent">): Promise; ``` ### `showFolderPicker` diff --git a/src/en/extension-doc/process-hook.md b/src/en/extension-doc/process-hook.md index b71c88d..dcaefb0 100644 --- a/src/en/extension-doc/process-hook.md +++ b/src/en/extension-doc/process-hook.md @@ -244,4 +244,42 @@ In general, when exporting references, we need to get the array of `PaperEntity` | Type | `Modify` | | Location | At the end of the `exportPlainText()` method | | Callback arguments | `string` | -| Callback Return Value | ArgumentArray<`string`> | \ No newline at end of file +| Callback Return Value | ArgumentArray<`string`> | + + +## Fuzzy Metadata Scraping Process + +When the user clicks on the fuzzy search, the selected paper will go through this process to get the metadata of the fuzzy search. + +In this process, the main hook points are in the `fuzzyScrape()` method of `ScrapeService`. + +The `fuzzyScrape()` method accepts an array of `PaperEntity` and outputs a mapping of the `id` of each paper to the candidate metadata. + +The main available hooks are as follows: + +### `beforeFuzzyScrape + +| Parameter | Value | +| --- | --- | +| Type | `Modify` | +| Location | At the very beginning of the `fuzzyScrape()` method | +| Callback arguments | `PaperEntity[]` | +| Callback Return Value | ArgumentArray<`PaperEntity[]`> | + +### `fuzzyScrape` + +| Parameter | Value | +| --- | --- | +| Type | `Transform` | +| Location | The main hook point of `fuzzyScrape()`, accepts an array of `PaperEntity`, and outputs an array of `PaperEntity` arrays | +| Callback arguments | `paperEntities: PaperEntity[]` | +| Callback Return Value | `PaperEntity[][]` | + +### `afterFuzzyScrape` + +| Parameter | Value | +| --- | --- | +| Type | `Modify` | +| Location | At the end of the `fuzzyScrape()` method, after searching for metadata | +| Callback arguments | `paperEntityDraftCandidates: PaperEntity[][]` | +| Callback Return Value | ArgumentArray<`paperEntityDraftCandidates: PaperEntity[][]`> | diff --git a/src/en/extension-doc/ui-slot.md b/src/en/extension-doc/ui-slot.md index 63837b5..99f3374 100644 --- a/src/en/extension-doc/ui-slot.md +++ b/src/en/extension-doc/ui-slot.md @@ -46,4 +46,10 @@ PLAPI.uiSlotService.updateSlot( ``` -`id` is the unique identifier of the content. If the `id` is already in the slot, the content will be updated. Otherwise, a new content will be added. \ No newline at end of file +`id` is the unique identifier of the content. If the `id` is already in the slot, the content will be updated. Otherwise, a new content will be added. + +### Delete Slot + +```typescript +PLAPI.uiSlotService.deleteSlotItem("paperDetailsPanelSlot1", ); +```