# 插件设置

## 概述

本插件提供了完善的设置系统，允许用户在 Joplin 的配置界面中自定义插件行为。设置通过 Joplin 的 Settings API 实现，支持持久化存储和实时更新。

## 设置项

### 导出路径样式

**设置键**: `exportPathStyle`

**类型**: 枚举（下拉菜单）

**描述**: 选择导出笔记时的文件和资源组织方式

**选项**:

| 值 | 标签 | 描述 |
|----|------|------|
| 0 | 扁平结构 | 所有文件和资源放在同一目录下 |
| 1 | 层次结构 | 按照文件夹结构组织文件 |

**默认值**: `flat`（扁平结构）

#### 扁平结构示例

当选择"扁平结构"时，导出的文件组织如下：

```
export/
├── note1.md
├── note2.md
└── assets/
    ├── image1.png
    ├── image2.png
    └── document.pdf
```

#### 层次结构示例

当选择"层次结构"时，导出的文件按照笔记本层级组织：

```
export/
├── 工作/
│   ├── 项目A.md
│   ├── 项目B.md
│   └── assets/
│       ├── screenshot1.png
│       └── screenshot2.png
└── 个人/
    ├── 日记.md
    ├── 笔记.md
    └── assets/
        └── photo.jpg
```

### 保存合并内容

**设置键**: `saveMergedContent`

**类型**: 布尔值（开关）

**描述**: 是否将所有笔记合并为一个文件保存

**选项**:

| 值 | 标签 | 描述 |
|----|------|------|
| `false` | 关闭（默认） | 每个笔记保存为独立的 MD 文件 |
| `true` | 开启 | 将所有笔记内容合并到一个文件中 |

**默认值**: `false`（关闭）

#### 关闭状态（默认）

当"保存合并内容"关闭时，每个笔记被保存为独立的 MD 文件：

```
export/
├── 笔记1.md
├── 笔记2.md
├── 笔记3.md
└── assets/
    └── ...
```

#### 开启状态

当"保存合并内容"开启时，所有笔记内容合并到一个文件：

```
export/
├── export.md          # 包含所有笔记的合并内容
└── assets/
    └── ...
```

**注意**: 无论此设置如何，系统都会处理每个笔记的资源链接。开启此选项只是额外生成一个包含所有笔记内容的合并文件。

### 默认作者

**设置键**: `defaultAuthor`

**类型**: 字符串

**描述**: 导出笔记时使用的默认作者名称（当笔记没有设置作者时使用）

**默认值**: `"Unknown Author"`

**示例**:

```json
{
  "defaultAuthor": "张三"
}
```

## 使用方法

### 在插件中注册设置

在插件的 `onStart` 事件中调用 `registerSettings()` 函数：

```typescript
import joplin from "api";
import { registerSettings } from "./settings";

joplin.plugins.register({
  onStart: async function() {
    // 注册插件设置
    await registerSettings();
  }
});
```

### 获取导出路径样式设置值

使用 `getExportPathStyle()` 函数获取当前设置：

```typescript
import { getExportPathStyle, ExportPathStyle } from "./settings";

const style = await getExportPathStyle();
if (style === ExportPathStyle.Flat) {
  console.log("使用扁平结构导出");
} else {
  console.log("使用层次结构导出");
}
```

### 设置导出路径样式

使用 `setExportPathStyle()` 函数修改设置：

```typescript
import { setExportPathStyle, ExportPathStyle } from "./settings";

await setExportPathStyle(ExportPathStyle.Hierarchical);
```

### 获取保存合并内容设置值

使用 `getSaveMergedContent()` 函数获取当前设置：

```typescript
import { getSaveMergedContent } from "./settings";

const saveMerged = await getSaveMergedContent();
if (saveMerged) {
  console.log("将保存合并内容文件");
} else {
  console.log("只保存单独的笔记文件");
}
```

### 设置保存合并内容

使用 `setSaveMergedContent()` 函数修改设置：

```typescript
import { setSaveMergedContent } from "./settings";

await setSaveMergedContent(true);
```

### 获取默认作者设置值

使用 `getDefaultAuthor()` 函数获取当前设置：

```typescript
import { getDefaultAuthor } from "./settings";

const author = await getDefaultAuthor();
console.log(`默认作者: ${author}`);
```

### 设置默认作者

使用 `setDefaultAuthor()` 函数修改设置：

```typescript
import { setDefaultAuthor } from "./settings";

await setDefaultAuthor("张三");
```

### 获取所有设置

使用 `getAllSettings()` 函数获取所有插件设置：

```typescript
import { getAllSettings } from "./settings";

const allSettings = await getAllSettings();
console.log(allSettings);
// 输出: { exportPathStyle: 1, saveMergedContent: false }
```

## API 参考

### 函数

#### `registerSettings()`

注册所有插件设置项。

**返回值**: `Promise<void>`

**示例**:
```typescript
await registerSettings();
```

#### `getExportPathStyle()`

获取导出路径样式设置值。

**返回值**: `Promise<ExportPathStyle>`

**示例**:
```typescript
const style = await getExportPathStyle();
```

#### `setExportPathStyle(style)`

设置导出路径样式。

**参数**:
- `style`: `ExportPathStyle` - 要设置的样式

**返回值**: `Promise<void>`

**示例**:
```typescript
await setExportPathStyle(ExportPathStyle.Flat);
```

#### `getSaveMergedContent()`

获取保存合并内容设置值。

**返回值**: `Promise<boolean>`

**示例**:
```typescript
const saveMerged = await getSaveMergedContent();
```

#### `setSaveMergedContent(enabled)`

设置保存合并内容开关。

**参数**:
- `enabled`: `boolean` - 是否启用保存合并内容

**返回值**: `Promise<void>`

**示例**:
```typescript
await setSaveMergedContent(true);
```

#### `getDefaultAuthor()`

获取默认作者设置值。

**返回值**: `Promise<string>`

**示例**:
```typescript
const author = await getDefaultAuthor();
```

#### `setDefaultAuthor(author)`

设置默认作者。

**参数**:
- `author`: `string` - 要设置的默认作者名称

**返回值**: `Promise<void>`

**示例**:
```typescript
await setDefaultAuthor("张三");
```

#### `getAllSettings()`

获取所有插件设置值。

**返回值**: `Promise<Record<string, unknown>>`

**示例**:
```typescript
const settings = await getAllSettings();
```

#### `validateSettingValue(key, value)`

验证设置值是否有效。

**参数**:
- `key`: `string` - 设置键名
- `value`: `unknown` - 设置值

**返回值**: `boolean`

**示例**:
```typescript
const isValid = validateSettingValue("exportPathStyle", 1);
const isBoolValid = validateSettingValue("saveMergedContent", true);
```

#### `getSettingDefaultValue(key)`

获取设置的默认值。

**参数**:
- `key`: `string` - 设置键名

**返回值**: `unknown`

**示例**:
```typescript
const defaultValue = getSettingDefaultValue("exportPathStyle");
const mergedDefaultValue = getSettingDefaultValue("saveMergedContent");
```

#### `resetAllSettings()`

重置所有设置为默认值。

**返回值**: `Promise<void>`

**示例**:
```typescript
await resetAllSettings();
```

### 枚举

#### `ExportPathStyle`

导出路径样式枚举。

| 值 | 描述 |
|----|------|
| `Flat` | 扁平结构 |
| `Hierarchical` | 层次结构 |

### 常量

#### `SETTINGS_KEYS`

设置键名常量对象。

```typescript
{
  EXPORT_PATH_STYLE: "exportPathStyle",
  SAVE_MERGED_CONTENT: "saveMergedContent",
  DEFAULT_AUTHOR: "defaultAuthor"
}
```

#### `SETTINGS_SECTION`

设置部分名称。

```typescript
"typoraLikeEditor"
```

#### `SETTINGS_SECTION_INFO`

设置部分显示信息。

```typescript
{
  label: "Typora 风格编辑器",
  iconName: "fas fa-pen",
  description: "配置 Typora 风格导出插件的参数"
}
```

## 配置界面位置

插件设置位于 Joplin 的配置界面中：

1. 打开 Joplin
2. 点击 **工具 > 选项** (Windows/Linux) 或 **Joplin > 偏好设置** (macOS)
3. 找到 **Typora 风格编辑器** 部分
4. 在此处可以修改所有插件设置：
   - **导出路径样式**: 下拉菜单选择
   - **保存合并内容**: 复选框开关
   - **默认作者**: 文本输入框

## 设置持久化

所有设置值自动保存到 Joplin 的数据库中：
- 重启 Joplin 后设置值自动恢复
- 设置值会在不同设备间同步（如果启用了同步功能）