最近想要阅读几本繁体中文版的epub书籍，于是想一键翻译成简体中文方便阅读，本以为Sigil会有相关功能，却发现似乎连相关的插件都没有。

然而Sigil的插件是基于Python的，这就很容易寻找到相关的开源库——OpenCC，说来萌发编写的想法也不见为奇了。

但网上对于 Sigil 插件编写的相关资料很少，基本只有官方的一本不完全的插件开发的epub电子书和github上的一些开源的插件代码。

简单写写此文，希望对想要入门 Sigil 插件编写的朋友提供一些帮助。

插件文件夹结构

[Plugin Name]
├── plugin.py
└── plugin.xml

你的插件目录下至少需要有plugin.py、plugin.xml两个文件，plugin.py是插件的具体实现，plugin.xml记录插件的一些具体信息，如版本号。

对于plugin.xml，它的内容应该像下面一样。

<?xml version=""1.0"" encoding=""UTF-8""?>
<plugin>
<name>[Plugin Name]</name>
<type>[type]</type>
<author>SpaceSkyNet</author>
<description>[description]</description>
<engine>[engine]</engine>
<version>0.1</version>
<oslist>[oslist]</oslist>
<autostart>true</autostart>
</plugin>

变量	内容
[Plugin Name]	插件名称，与文件夹名一致（且不能使用中文）
[type]	插件类型，Sigil 已定义（从input, validation, edit, output中选择）
[description]	插件简介
[engine]	插件运行引擎，一般来说从python2.7, python3.4中选择一个或者以逗号分隔填入两个（取决于plugin.py的运行环境）
[oslist]	插件运行操作系统，从osx, unx, win中选择并组合，两个及以上以逗号分隔

插件有四种类型输入、验证、编辑、输出（input, validation, edit, output），不同类型有一些差别，本文仅讲述相同之处。（毕竟是入门教程）

插件的编写

将plugin.xml处理好了后，就可以开始编写plugin.py了。

如果要程序与用户交互，最好使用图形界面，所以至少掌握到PyQt、Tkinter等GUI开发框架的入门级别（不用交互可以忽略这句话）。

当然，也得了解一下epub的文件结构。

程序入口

Sigil 会默认将plugin.py中的run函数作为程序的入口，并默认传入bk参数（bk是 Sigil 提供的 epub 书籍内容的一个对象，可以利用它访问并操作 epub 内的文件）。

def run(bk):
    return yourFunction(bk)

返回值为 $0$ 表示程序正常结束。

程序实现

为了程序显得比较模块化，我把它分成了三个部分。这里的GUI开发框架使用PyQt。

主体

用来统一GUI的交互和后台处理的函数。

def yourFunction(bk):
    item = {""some_argv"": 0}
    
    app = QApplication(sys.argv)
    QtGUI = youtQtGUI(app=app, items=items, bk=bk)
    QtGUI.show()
    
    rtnCode = app.exec_()
    if rtnCode != 1:
        print('User abort by closing Setting dialog')
        return -1
    
    return yourProcessFunction(bk, item)

可以通过一个item字典和用户在GUI上交互，获得或传出需要的信息。

可以通过指定GUI类的返回值判断GUI是否是正常按照既定的程序逻辑退出。

GUI

用来与用户交互。

class youtQtGUI(QDialog):
    def __init__(self,
                 app=None,
                 parent=None,
                 bk=None,
                 items=None):

        super(youtQtGUI, self).__init__(parent)

        self.app = app
        self.items = items

        self.setWindowIcon(QIcon(os.path.join(bk._w.plugin_dir, '[Plugin Name]', 'plugin.png')))       
        layout = QVBoxLayout()
        
        choice_info = '选择对象：'
        layout.addWidget(QLabel(choice_info))
        self.choice_list = ['Test1', 'Test2', 'Test3',]
        self.combobox = QComboBox(self)
        self.combobox.addItems(self.choice_list)
        self.combobox.setCurrentIndex(items['some_argv'])
        layout.addWidget(self.combobox)
        self.combobox.currentIndexChanged.connect(lambda: self.on_combobox_func())

        self.btn = QPushButton('确定', self)
        self.btn.clicked.connect(lambda: (self.bye(items)))
        self.btn.setFocusPolicy(Qt.StrongFocus)

        layout.addWidget(self.btn)

        self.setLayout(layout)
        self.setWindowTitle(' Test ')
    def on_combobox_func(self):
        self.items['current_index'] = self.combobox.currentIndex()

    def bye(self, items):
        self.close()
        self.app.exit(1)

可以通过bk._w.plugin_dir获取插件所在的绝对目录，并通过setWindowIcon设定插件的图标。

后台处理

def Test1(bk):
    # process html/xhtml files
    for (file_id, _) in bk.text_iter():
        file_href = bk.id_to_href(file_id)
        file_basename = bk.href_to_basename(file_href)
        file_mime = bk.id_to_mime(file_id)
        html_original = bk.readfile(file_id)
         '''
         your code for processing 
         '''
        bk.writefile(file_id, html_original_conv)
        print('Changed:', file_basename, file_mime) 
    return 0
def Test2(bk):
    # process ncx file
    NCX_id = bk.gettocid()
    if not NCX_id:
        print('ncx file is not exists!')
        return -1
    
    NCX_mime = bk.id_to_mime(NCX_id)
    NCX_href = bk.id_to_href(NCX_id)
    NCX_original = bk.readfile(NCX_id)
    '''
    your code for processing 
    '''
    bk.writefile(NCX_id, NCX_original)
    print('Changed:', NCX_href, NCX_mime)
    return 0

def Test3(bk):
    # process opf file
    OPF_basename = 'content.opf'
    OPF_mime = 'application/oebps-package+xml'
    metadata = bk.getmetadataxml()
    '''
    your code for processing 
    '''    
    bk.setmetadataxml(metadata)
    
    print('Changed:', OPF_basename, OPF_mime)
    return 0
    
def yourProcessFunction(bk, items):
    c_index = items['some_argv']
    print(""Selected:"", c_index)
    
    if c_index == 1:
        return Test1(bk)
    elif c_index == 2:
        return Test2(bk)
    else:
        return Test3(bk)

以上演示的是通过GUI选择一个选项并运行相应函数。

对于bk对象常用的函数，附在最后。

总代码

#!/usr/bin/env python3
#-*- coding: utf-8 -*-
# By: SpaceSkyNet

from lxml import etree
from PyQt5.QtGui import QIcon
from PyQt5.QtWidgets import (QDialog, QPushButton, QComboBox,
                             QLabel, QApplication, QVBoxLayout)
from PyQt5.QtCore import Qt
import sys, os
class youtQtGUI(QDialog):
    def __init__(self,
                 app=None,
                 parent=None,
                 bk=None,
                 items=None):

        super(youtQtGUI, self).__init__(parent)

        self.app = app
        self.items = items

        self.setWindowIcon(QIcon(os.path.join(bk._w.plugin_dir, '[Plugin Name]', 'plugin.png')))       
        layout = QVBoxLayout()
        
        choice_info = '选择对象：'
        layout.addWidget(QLabel(choice_info))
        self.choice_list = ['Test1', 'Test2', 'Test3',]
        self.combobox = QComboBox(self)
        self.combobox.addItems(self.choice_list)
        self.combobox.setCurrentIndex(items['some_argv'])
        layout.addWidget(self.combobox)
        self.combobox.currentIndexChanged.connect(lambda: self.on_combobox_func())

        self.btn = QPushButton('确定', self)
        self.btn.clicked.connect(lambda: (self.bye(items)))
        self.btn.setFocusPolicy(Qt.StrongFocus)

        layout.addWidget(self.btn)

        self.setLayout(layout)
        self.setWindowTitle(' Test ')
    def on_combobox_func(self):
        self.items['current_index'] = self.combobox.currentIndex()

    def bye(self, items):
        self.close()
        self.app.exit(1)
 
def Test1(bk):
    # process html/xhtml files
    for (file_id, _) in bk.text_iter():
        file_href = bk.id_to_href(file_id)
        file_basename = bk.href_to_basename(file_href)
        file_mime = bk.id_to_mime(file_id)
        html_original = bk.readfile(file_id)
         '''
         your code for processing 
         '''
        bk.writefile(file_id, html_original_conv)
        print('Changed:', file_basename, file_mime) 
    return 0
def Test2(bk):
    # process ncx file
    NCX_id = bk.gettocid()
    if not NCX_id:
        print('ncx file is not exists!')
        return -1
    
    NCX_mime = bk.id_to_mime(NCX_id)
    NCX_href = bk.id_to_href(NCX_id)
    NCX_original = bk.readfile(NCX_id)
    '''
    your code for processing 
    '''
    bk.writefile(NCX_id, NCX_original)
    print('Changed:', NCX_href, NCX_mime)
    return 0

def Test3(bk):
    # process opf file
    OPF_basename = 'content.opf'
    OPF_mime = 'application/oebps-package+xml'
    metadata = bk.getmetadataxml()
    '''
    your code for processing 
    '''    
    bk.setmetadataxml(metadata)
    
    print('Changed:', OPF_basename, OPF_mime)
    return 0
    
def yourProcessFunction(bk, items):
    c_index = items['some_argv']
    print(""Selected:"", c_index)
    
    if c_index == 1:
        return Test1(bk)
    elif c_index == 2:
        return Test2(bk)
    else:
        return Test3(bk)

def yourFunction(bk):
    item = {""some_argv"": 0}
    
    app = QApplication(sys.argv)
    QtGUI = youtQtGUI(app=app, items=items, bk=bk)
    QtGUI.show()
    
    rtnCode = app.exec_()
    if rtnCode != 1:
        print('User abort by closing Setting dialog')
        return -1
    
    return yourProcessFunction(bk, item)

def run(bk):
    return yourFunction(bk)

bk对象常用函数

bk.readfile(manifest_id)

通过文件的 manifest_id 读取文件，id 可通过 href 等获取，或者使用迭代器获取。

返回一个包含文件原始内容string对象

bk.writefile(manifest_id, data)

通过文件的 manifest_id 写入文件。

可传入文件原始内容的string或bytes对象，string对象必须以 utf-8 编码。

bk.text_iter()

返回一个 python 迭代器对象，迭代所有 xhtml/html 文件，每个元素是一个元组 (manifest_id, OPF_href)。

类似的还有bk.css_iter()、bk.image_iter()、bk.font_iter()、bk.manifest_iter()，具体信息可查看官方插件开发文档。

bk.id_to_href(id)

通过 manifest_id 获取文件 href。

类似的还有bk.href_to_id(OPF_href)、bk.id_to_mime(manifest_id)、bk.basename_to_id(basename)、bk.href_to_basename(href)，具体信息可查看官方插件开发文档。

bk.gettocid()

获取目录文件toc.ncx的 manifest_id。

bk.getmetadataxml()

以string对象返回 OPF 文件中 metadata 的部分。

bk.setmetadataxml(new_metadata)

修改 OPF 文件中 metadata 的部分。

OPF 文件被修改会被打上标记，Sigil 会自动修改，不需要去writefile。

其他

更多详见官方插件开发文档.

如果下载过慢或者不能下载，可在gitee上寻找 Sigil 同名仓库并寻找Sigil_Plugin_Framework_rev12.epub文件。

后记

这次发现其实官方文档也是不太完整，通过阅读Sigil的插件启动器Python源代码加上他人的插件源代码，我才完成了 Sigil 插件的编写。

所以，有时候不妨看看源代码，或许比官方文档更有帮助。

我也写了一些 Sigil 的插件，放在了github上，可以用来对照下。

spaceskynet/Sigil-Plugins