Skip to content

Latest commit

 

History

History
165 lines (134 loc) · 6.14 KB

README_zh_CN.md

File metadata and controls

165 lines (134 loc) · 6.14 KB

English

思源笔记插件示例

开始

  • 通过 Use this template 按钮将该库文件复制到你自己的库中,请注意库名必须和插件名称一致,默认分支必须为 main
  • 将你的库克隆到本地开发文件夹中,为了方便可以直接将开发文件夹放置在 {工作空间}/data/plugins/
  • 安装 NodeJSpnpm,然后在开发文件夹下执行 pnpm i
  • 执行 pnpm run dev 进行实时编译
  • 在思源中打开集市并在下载选项卡中启用插件

开发

  • i18n/*
  • icon.png (160*160)
  • index.css
  • index.js
  • plugin.json
  • preview.png (1024*768)
  • README*.md
  • 前端 API
  • 后端 API

国际化

国际化方面我们主要考虑的是支持多语言,具体需要完成以下工作:

  • 插件自身的元信息,比如插件描述和自述文件
    • plugin.json 中的 descriptionreadme 字段,以及对应的 README*.md 文件
  • 插件中使用的文本,比如按钮文字和提示信息
    • src/i18n/*.json 语言配置文件
    • 代码中使用 this.i18.key 获取文本
  • 最后在 plugin.json 中的 i18n 字段中声明该插件支持的语言

建议插件至少支持英文和简体中文,这样可以方便更多人使用。

plugin.json

{
  "name": "plugin-sample",
  "author": "Vanessa",
  "url": "https://github.com/siyuan-note/plugin-sample",
  "version": "0.1.3",
  "minAppVersion": "2.8.8",
  "backends": ["windows", "linux", "darwin"],
  "frontends": ["desktop"],
  "displayName": {
    "default": "Plugin Sample",
    "zh_CN": "插件示例"
  },
  "description": {
    "default": "This is a plugin sample",
    "zh_CN": "这是一个插件示例"
  },
  "readme": {
    "default": "README.md",
    "zh_CN": "README_zh_CN.md"
  },
  "funding": {
    "openCollective": "",
    "patreon": "",
    "github": "",
    "custom": [
      "https://ld246.com/sponsor"
    ]
  },
  "keywords": [
    "sample", "示例"
  ]
}
  • name:插件名称,必须和库名一致,且全局唯一(集市中不能有重名插件)
  • author:插件作者名
  • url:插件仓库地址
  • version:插件版本号,建议遵循 semver 规范
  • minAppVersion:插件支持的最低思源笔记版本号
  • backends:插件需要的后端环境,可选值为 windows, linux, darwin, docker, android, ios and all
    • windows:Windows 桌面端
    • linux:Linux 桌面端
    • darwin:macOS 桌面端
    • docker:Docker 端
    • android:Android 端
    • ios:iOS 端
    • all:所有环境
  • frontends:插件需要的前端环境,可选值为 desktop, desktop-window, mobile, browser-desktop, browser-mobile and all
    • desktop:桌面端
    • desktop-window:桌面端页签转换的独立窗口
    • mobile:移动端
    • browser-desktop:桌面端浏览器
    • browser-mobile:移动端浏览器
    • all:所有环境
  • displayName:模板显示名称,主要用于模板集市列表中显示,支持多语言
    • default:默认语言,必须存在
    • zh_CNen_US 等其他语言:可选,建议至少提供中文和英文
  • description:插件描述,主要用于插件集市列表中显示,支持多语言
    • default:默认语言,必须存在
    • zh_CNen_US 等其他语言:可选,建议至少提供中文和英文
  • readme:自述文件名,主要用于插件集市详情页中显示,支持多语言
    • default:默认语言,必须存在
    • zh_CNen_US 等其他语言:可选,建议至少提供中文和英文
  • funding:插件赞助信息
    • openCollective:Open Collective 名称
    • patreon:Patreon 名称
    • github:GitHub 登录名
    • custom:自定义赞助链接列表
  • keywords:搜索关键字列表,用于集市搜索功能

打包

无论使用何种方式编译打包,我们最终需要生成一个 package.zip,它至少包含如下文件:

  • i18n/*
  • icon.png (160*160)
  • index.css
  • index.js
  • plugin.json
  • preview.png (1024*768)
  • README*.md

上架集市

如果是第一次发布版本,还需要创建一个 PR 到 Community Bazaar 社区集市仓库,修改该库的 plugins.json。该文件是所有社区插件库的索引,格式为:

{
  "repos": [
    "username/reponame"
  ]
}

PR 被合并以后集市会通过 GitHub Actions 自动更新索引并部署。后续发布新版本插件时只需要按照上述步骤创建新的发布即可,不需要再 PR 社区集市仓库。

正常情况下,社区集市仓库每隔 1 小时会自动更新索引并部署,可在 https://github.com/siyuan-note/bazaar/actions 查看部署状态。

开发者须知

开发者需注意以下规范。

1. 读写文件规范

插件或者外部扩展如果有直接读取或者写入 data 下文件的需求,请通过调用内核 API 来实现,不要自行调用 fs 或者其他 electron、nodejs API,否则可能会导致数据同步时分块丢失,造成云端数据损坏。

相关 API 见 /api/file/*(例如 /api/file/getFile 等)。

2. Daily Note 属性规范

思源在创建日记的时候会自动为文档添加 custom-dailynote-yyyymmdd 属性,以方便将日记文档同普通文档区分。

详情请见 Github Issue #9807

开发者在开发手动创建 Daily Note 的功能时请注意:

  • 如果调用了 /api/filetree/createDailyNote 创建日记,那么文档会自动添加这个属性,无需开发者特别处理
  • 如果是开发者代码手动创建文档(例如使用 createDocWithMd API 创建日记),请手动为文档添加该属性