> ## Documentation Index
> Fetch the complete documentation index at: https://dev.marginnote.com.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 window.mn 与MN进行交互

>  

场景插件在加载时，MN 会向上下文注入 `mn` 实例对象，可以通过访问其上的成员来进行与 MN 的交互。

```typescript theme={null}
window.mn
├── version: number          // sdk版本
├── currentMode: "workspace" | "mini"
├── lang: string             // App 界面语言
├── locale: string           // 系统地区
├── theme: "light" | "dark"	 // 白色、棕褐色、绿色 = light；灰色、黑色 = dark
├── _drag
├── api(path, opts) => Promise<json>
├── ai(noteid, taskId, params) => Promise<json>
├── call(name, data) => Promise<json>  // 向 main.js 发送消息并获取返回值
├── on(event, cb)
├── fit() / height(h) / size(w,h) / mode(m) / close() / reload()
└── log(...args)
```

# 只读信息

以下成员均为 `mn` 对象下的只读成员：

* version：插件 SDK 版本号
* currentMode：`workspace`/`mini`。需要插件自行进行适配
* lang： App 界面语言。
* locale： 系统所在区域。
* theme： `light`/`dark`。白色、棕褐色、绿色为 `light`；灰色、黑色为 `dark`
* \_drag：作用暂不明确

```javascript theme={null}
>	[mn.version,mn.currentMode,mn.lang,mn.locale,mn.theme,mn._drag]
<	[
	  1,
	  "workspace",
	  "zh-Hans",
	  "zh-CN",
	  "dark",
	  false
	]
```

# 方法

## api(path, opts)

对 MN 数据进行 CRUD 操作。此方法调用方式与 Marginnote CLI 相同，但有部分 API 不可用。准确可用 API 需查询 capabilities。

下面代码演示了如何使用 `mn.api` 进行操作

<CodeGroup>
  ```javascript GET theme={null}
  // 😋获取所有 api 可用能力
  const capabilities = mn.api("/capabilities")

  // 按文档顺序获取该学习集的卡片
  const tree = await mn.api("/study-sets/" + topicid + "/tree?sort=document");

  // 获取当前打开的学习集 ID
  const st = await mn.api("/ui-state");
  ```

  ```javascript POST theme={null}
  await mn.api('/notes/' + id + '/edits', {method: 'POST', body: {ops: [
    {op: 'setTitle', text: '…', expectedPrefix: '当前标题的开头'},
    {op: 'appendComment', text: '…'},
    {op: 'deleteComment', index: 2, expectedPrefix: '…'},
    {op: 'removeHashtags', hashtags: ['#VocabPending']},
    {op: 'setAddonValues', addon: '任意', values: {status: 'done'}}
  ], confirm: true, syncReview: false}});
  ```
</CodeGroup>

具体实践详见[数据交互](/zh/data-interact)。

## ai(noteid, taskId, params)

`mn.ai`允许你使用 MN 内置的 AI 执行任务。需要注意的是，使用此命令前需在 `template.json` 中定义任务 id。

```json template.json theme={null}
{
  "aiTasks": [
    {
      "id": "starter_explain", 
      "title": "解释一下", 
      "trigger": "user",
      "scope": "word_sentence",
      "tier": 1,
      "output": {"reply": "string"}, 
      "required": ["reply"],
      "prompt": "用一句中文解释给定的词在学习笔记语境下的意思。"
    }
  ],
  ...
}
```

下面是调用示范

```javascript theme={null}
const r = await mn.ai(
  noteid, 
  "starter_explain", 
  {
    word: "photosynthesis", 
    sentence: "..."
  }
);
if(r.ok) console.log(r.json.reply);
```

具体实践详见 [使用 MN 内置 AI](/zh/use-inner-ai)

## call(name, data)

用于调用`main.js`中定义的函数并接收回调。

具体实践详见[面板之外](/zh/jsaddon)

## on(event, cb)

`mn.on` 用于监听 MN 发送的事件。你需要先在 `mnaddon.json` 里声明你要监听哪些事件。

```json mnaddon.json highlight={9} focus={9} theme={null}
{
	"addonid": "mn.hello",
	"title": "你好世界",
	"version": "0.1.0",
 	"author": "我",
  	"marginnote_version_min": "4.5.0",
  	"panel": "index.html",
  	"icon": "hello.png",
	"events":["excerpt"]
}
```

```javascript theme={null}
mn.on("excerpt", async (card) => {
  console.log(`New excerpt added: ${card.noteid}`)
});
```

具体实践详见 [事件系统](/zh/events)

## UI 相关

* fit(): 自适应面板高度
* height(h): 设置面板高度
* size(w,h): 设置面板宽高
* mode(m): 设置面板模式为`workspace`/`mini`
* close(): 关闭面板
* reload(): 重载面板

具体实践详见[UI 控制](/zh/ui)

## log

记录日志。但由于现在没有查看的入口，作用尚不明确。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.