StackEdit API文档：开发集成的完整参考指南-优快云博客

StackEdit API文档：开发集成的完整参考指南

【免费下载链接】stackedit In-browser Markdown editor 项目地址: https://gitcode.com/gh_mirrors/st/stackedit

1. 概述

StackEdit（Stack Edit）是一款功能强大的浏览器内Markdown编辑器，提供丰富的API接口，支持开发者进行深度集成与定制。本文档详细介绍StackEdit的核心API、使用方法及集成示例，帮助开发者快速实现编辑器功能扩展、数据交互与第三方系统对接。

2. 核心服务与类结构

StackEdit的API架构基于模块化服务设计，核心功能通过独立服务类封装，支持灵活调用与扩展。

2.1 主要服务类概览

服务名称	核心类	功能描述
Animation Service	`Animation`	提供编辑器UI动画控制，支持平滑过渡与状态切换
Sync Service	`SyncContext`	管理云同步上下文，处理文件版本冲突与同步状态
Editor Service	`SectionDesc`	控制编辑器内容区块，支持段落管理与格式转换
Time Service	`RelativeTime`	提供时间格式化工具，支持相对时间（如"3分钟前"）展示
LocalDB Service	`Connection`	本地数据库连接管理，处理离线数据持久化
Workspace Service	-	工作区管理，支持多项目切换与配置保存
Publish Service	-	发布功能核心，对接GitHub、Google Drive等平台

2.2 类关系图

mermaid

3. 核心API详解

3.1 编辑器服务（Editor Service）

3.1.1 内容操作

获取当前文档内容

// 获取完整文档内容
const content = editorSvc.getContent();

// 获取指定区块内容
const section = editorSvc.getSectionById('section-123');
const sectionContent = section.content;

更新文档内容

// 替换整个文档
editorSvc.setContent('# 新文档内容\n\n这是通过API更新的文本');

// 更新指定区块
editorSvc.updateSection('section-123', {
  content: '更新后的段落内容',
  type: 'paragraph'
});

3.1.2 格式控制

应用文本格式

// 加粗选中文本
editorSvc.applyFormat('bold');

// 设置代码块语言
editorSvc.setCodeLanguage('javascript');

// 添加表格
editorSvc.insertTable(3, 4); // 3行4列

3.1.3 区块管理

// 创建新段落
const newSection = editorSvc.createSection({
  type: 'paragraph',
  content: '新段落内容',
  position: 'after', // before/after/top/bottom
  targetId: 'section-123'
});

// 删除区块
editorSvc.deleteSection('section-456');

// 移动区块
editorSvc.moveSection('section-789', 'section-123', 'before');

3.2 同步服务（Sync Service）

3.2.1 同步控制

初始化同步

// 创建同步上下文
const syncContext = new SyncContext({
  provider: 'github', // github/gitlab/google-drive
  resourceId: '123456', // 远程资源ID
  autoSync: true
});

// 手动触发同步
syncContext.sync()
  .then(status => console.log('Sync status:', status))
  .catch(error => console.error('Sync failed:', error));

处理同步冲突

// 监听冲突事件
syncContext.on('conflict', (conflict) => {
  console.log('Conflict detected:', conflict);
  
  // 选择本地版本
  conflict.resolve('local');
  
  // 或选择远程版本
  // conflict.resolve('remote');
  
  // 或手动合并
  // const mergedContent = merge(conflict.localContent, conflict.remoteContent);
  // conflict.resolve('custom', mergedContent);
});

3.2.2 同步状态查询

// 获取同步状态
const status = syncContext.getStatus();
// {
//   state: "idle", // idle/syncing/error/conflict
//   lastSynced: "2023-10-15T08:30:22Z",
//   pendingChanges: false
// }

// 监听状态变化
syncContext.on('statusChange', (newStatus) => {
  updateSyncIndicator(newStatus.state);
});

3.3 工作区服务（Workspace Service）

3.3.1 工作区管理

创建工作区

// 创建新工作区
workspaceSvc.createWorkspace({
  name: '项目文档',
  description: '产品需求规格说明书',
  template: 'blank' // blank/note/blog/post
}).then(workspace => {
  console.log('Workspace created:', workspace.id);
  // 切换到新工作区
  workspaceSvc.switchWorkspace(workspace.id);
});

工作区列表与切换

// 获取所有工作区
const workspaces = workspaceSvc.getWorkspaces();

// 切换工作区
workspaceSvc.switchWorkspace('workspace-789');

// 删除工作区
workspaceSvc.deleteWorkspace('workspace-789', {
  force: true // 强制删除（即使有未同步更改）
});

3.3.2 工作区配置

// 获取当前配置
const config = workspaceSvc.getConfig();

// 更新配置
workspaceSvc.updateConfig({
  editor: {
    lineNumbers: true,
    wordWrap: 'on',
    theme: 'dark'
  },
  sync: {
    interval: 300, // 自动同步间隔（秒）
    autoPush: true
  }
});

3.4 导出服务（Export Service）

3.4.1 格式导出

导出为HTML

// 导出完整HTML
exportSvc.exportAsHtml({
  standalone: true, // 包含样式
  toc: true, // 生成目录
  template: 'styled' // plain/styled/styled-with-toc
}).then(html => {
  // 保存HTML内容
  saveToFile(html, 'document.html');
});

导出为PDF

// 导出PDF
exportSvc.exportAsPdf({
  pageSize: 'A4',
  margin: { top: 20, right: 20, bottom: 20, left: 20 },
  header: '文档标题',
  footer: '第 {page} 页，共 {total} 页'
}).then(pdfBlob => {
  // 下载PDF
  const url = URL.createObjectURL(pdfBlob);
  downloadFile(url, 'document.pdf');
});

3.4.2 高级导出选项

// 导出为GitHub Gist
exportSvc.exportToProvider('gist', {
  name: '技术文档.md',
  description: '使用StackEdit API导出的文档',
  public: false
}).then(result => {
  console.log('Gist创建成功:', result.url);
});

// 批量导出
exportSvc.batchExport([
  { format: 'html', fileId: 'file-123' },
  { format: 'pdf', fileId: 'file-456' }
], {
  zip: true, // 打包为ZIP
  fileName: '文档集合'
});

4. 扩展开发指南

4.1 扩展服务（Extension Service）

注册扩展

// 注册简单扩展
extensionSvc.registerExtension({
  id: 'custom-extension',
  name: '自定义扩展',
  version: '1.0.0',
  activate: (context) => {
    console.log('扩展已激活');
    
    // 注册命令
    context.registerCommand('custom.formatCode', () => {
      // 实现代码格式化功能
      const code = editorSvc.getSelectedText();
      const formattedCode = formatCode(code);
      editorSvc.replaceSelection(formattedCode);
    });
    
    // 添加菜单项
    context.addMenuItem('edit', {
      label: '格式化代码',
      command: 'custom.formatCode',
      icon: 'code'
    });
  },
  deactivate: () => {
    console.log('扩展已停用');
  }
});

4.2 事件系统

监听编辑器事件

// 内容变化事件
editorSvc.on('contentChange', (changes) => {
  console.log('内容变化:', changes);
});

// 选区变化事件
editorSvc.on('selectionChange', (selection) => {
  console.log('选区变化:', selection);
});

// 格式应用事件
editorSvc.on('formatApplied', (format) => {
  console.log('应用格式:', format);
});

自定义事件

// 触发自定义事件
extensionSvc.emit('customEvent', {
  data: '自定义数据'
});

// 监听自定义事件
extensionSvc.on('customEvent', (data) => {
  console.log('接收到自定义事件:', data);
});

5. 集成示例

5.1 GitHub集成

初始化GitHub同步

// 配置GitHub提供者
const githubProvider = publishSvc.getProvider('github');
githubProvider.configure({
  repo: 'username/repo',
  branch: 'main',
  path: 'docs/',
  token: 'user-personal-access-token'
});

// 发布文档
publishSvc.publish({
  provider: 'github',
  fileId: 'current-document',
  commitMessage: 'Update via StackEdit API',
  createPullRequest: false
}).then(result => {
  console.log('发布成功:', result.url);
});

5.2 第三方系统数据交互

保存到自定义后端

// 监听保存事件
workspaceSvc.on('save', async (content) => {
  try {
    // 发送到自定义API
    await fetch('https://api.example.com/documents', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer ' + userToken
      },
      body: JSON.stringify({
        id: workspaceSvc.getCurrentWorkspaceId(),
        content: content,
        updatedAt: new Date().toISOString()
      })
    });
    console.log('保存到自定义系统成功');
  } catch (error) {
    console.error('保存失败:', error);
  }
});

5.3 自定义工具栏按钮

// 添加自定义按钮
editorSvc.addToolbarButton({
  icon: '<svg>...</svg>', // 按钮图标
  tooltip: '插入自定义组件',
  action: () => {
    // 插入自定义内容
    editorSvc.insertContent('<CustomComponent data-id="123" />');
  },
  position: 'right' // left/right
});

6. 错误处理与调试

6.1 错误处理最佳实践

// 同步错误处理
try {
  await syncContext.sync();
} catch (error) {
  if (error.type === 'CONNECTION_ERROR') {
    console.error('网络连接错误:', error.message);
    // 显示离线模式提示
    showNotification('网络连接失败，已切换到离线模式', 'error');
  } else if (error.type === 'AUTH_ERROR') {
    console.error('认证失败:', error.message);
    // 触发重新认证
    authSvc.refreshToken();
  } else if (error.type === 'CONFLICT_ERROR') {
    console.error('同步冲突:', error.conflictDetails);
    // 显示冲突解决界面
    showConflictResolver(error.conflictDetails);
  }
}

6.2 调试工具

启用调试模式

// 启用详细日志
utils.setDebugLevel('verbose'); // silent/error/warn/info/verbose

// 导出调试信息
const debugInfo = utils.exportDebugInfo();
saveToFile(debugInfo, 'stackedit-debug-info.json');

7. API参考速查表

7.1 常用方法速查

功能	方法	参数	返回值
获取内容	`editorSvc.getContent()`	-	`string`
设置内容	`editorSvc.setContent(content)`	`content: string`	`void`
保存文档	`workspaceSvc.save()`	-	`Promise<boolean>`
导出PDF	`exportSvc.exportAsPdf(options)`	`options: Object`	`Promise<Blob>`
同步文档	`syncContext.sync()`	-	`Promise<SyncStatus>`
创建工作区	`workspaceSvc.createWorkspace(config)`	`config: Object`	`Promise<Workspace>`

7.2 事件速查

事件名称	触发时机	事件数据
`contentChange`	内容变化时	`{ changes: Array, timestamp: Date }`
`syncComplete`	同步完成时	`{ status: string, changes: number }`
`exportComplete`	导出完成时	`{ format: string, size: number }`
`workspaceSwitched`	工作区切换时	`{ previous: string, current: string }`
`formatApplied`	格式应用时	`{ type: string, range: Range }`

8. 总结与展望

StackEdit提供了全面的API接口，支持从内容编辑、格式控制到数据同步、第三方集成的完整开发需求。通过灵活运用这些API，开发者可以构建高度定制化的Markdown编辑体验，实现与现有工作流的无缝对接。

未来版本将进一步增强API能力，包括：

扩展插件市场
自定义语法支持
AI辅助编辑接口
实时协作API

建议开发者关注官方更新日志，及时获取API变更通知，确保集成方案的兼容性与稳定性。

【免费下载链接】stackedit In-browser Markdown editor 项目地址: https://gitcode.com/gh_mirrors/st/stackedit

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考