update: new api doc

Future-Scholars · Jun 30, 2024 · 4ee1dd6 · 4ee1dd6
1 parent 2ccef4b
commit 4ee1dd6
Show file tree

Hide file tree

Showing 16 changed files with 144 additions and 7 deletions.
diff --git 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
@@ -42,4 +42,15 @@ scrapeEntry(payloads: any[]): Promise<PaperEntity[]>;
  * @param force - force scraping metadata.
  * @returns List of paper entities. */
 scrapeMetadata(paperEntityDrafts: PaperEntity[], scrapers: string[], force?: boolean): Promise<PaperEntity[]>;
+```
+
+
+### `fuzzyScrape`
+
+```typescript
+/**
+ * Scrape a data source's metadata fuzzily.
+ * @param payloads - data source payloads.
+ * @returns List of paper entities' candidates. */
+fuzzyScrape(paperEntities: IPaperEntityCollection): Promise<Record<string, PaperEntity[]>>;
 ```
diff --git 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<void>;
 ```
 
+```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
@@ -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<PaperEntity>;
   selectedFeedEntities: Array<FeedEntity>;
-  selectedQuerySentenceId: string;
+  selectedQuerySentenceIds: string[];
+  showingCandidatesId: string;
+  metadataCandidates: Record<string, PaperEntity[]>;
   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
@@ -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
@@ -28,7 +28,7 @@ getSystemPath(key: "home" | "appData" | "userData" | "sessionData" | "temp" | "e
  * Show a file picker.
  * @returns {Promise<OpenDialogReturnValue>} The result of the file picker.
  */
-showFilePicker(): Promise<OpenDialogReturnValue>;
+showFilePicker(props?: Array<"openDirectory" | "multiSelections" | "showHiddenFiles" | "createDirectory" | "promptToCreate" | "noResolveAliases" | "treatPackageAsDirectory" | "dontAddToRecent">): Promise<OpenDialogReturnValue>;
 ```
 
 ### `showFolderPicker`

diff --git 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<PaperEntity>`, 输出 `Record<string, Array<PaperEntity>>`，即每个论文的 `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
@@ -46,4 +46,11 @@ PLAPI.uiSlotService.updateSlot(
 
 ```
 
-`id` 是内容的唯一标识符。如果 `id` 已经在插槽中，内容将被更新。否则，将添加新内容。
+`id` 是内容的唯一标识符。如果 `id` 已经在插槽中，内容将被更新。否则，将添加新内容。
+
+### 插槽删除
+
+```typescript
+PLAPI.uiSlotService.deleteSlotItem("paperDetailsPanelSlot1", <id>);
+```
+
diff --git 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
@@ -42,4 +42,14 @@ scrapeEntry(payloads: any[]): Promise<PaperEntity[]>;
  * @param force - force scraping metadata.
  * @returns List of paper entities. */
 scrapeMetadata(paperEntityDrafts: PaperEntity[], scrapers: string[], force?: boolean): Promise<PaperEntity[]>;
+```
+
+### `fuzzyScrape`
+
+```typescript
+/**
+ * Scrape a data source's metadata fuzzily.
+ * @param payloads - data source payloads.
+ * @returns List of paper entities' candidates. */
+fuzzyScrape(paperEntities: IPaperEntityCollection): Promise<Record<string, PaperEntity[]>>;
 ```
diff --git 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<void>;
 ```
 
+```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
@@ -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<PaperEntity>;
   selectedFeedEntities: Array<FeedEntity>;
-  selectedQuerySentenceId: string;
+  selectedQuerySentenceIds: string[];
+  showingCandidatesId: string;
+  metadataCandidates: Record<string, PaperEntity[]>;
   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
@@ -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
@@ -28,7 +28,7 @@ getSystemPath(key: "home" | "appData" | "userData" | "sessionData" | "temp" | "e
  * Show a file picker.
  * @returns {Promise<OpenDialogReturnValue>} The result of the file picker.
  */
-showFilePicker(): Promise<OpenDialogReturnValue>;
+showFilePicker(props?: Array<"openDirectory" | "multiSelections" | "showHiddenFiles" | "createDirectory" | "promptToCreate" | "noResolveAliases" | "treatPackageAsDirectory" | "dontAddToRecent">): Promise<OpenDialogReturnValue>;
 ```
 
 ### `showFolderPicker`

diff --git 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`> |
+| 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
@@ -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.
+`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", <id>);
+```