ONLYOFFICE API 文档 - 集成ONLYOFFICE移动web编辑器

在本节中，我们将使用 GitHub上提供的iOS移动演示示例，通过 WKWebView 查看集成过程。

基于ONLYOFFICE测试范例的集成

此示例演示了如何将ONLYOFFICE移动web编辑器与ONLYOFFICE 测试或DMS范例集成。

通过测试范例实现iOS集成

打开ONLYOFFICE编辑器

下载并安装ONLYOFFICE 文档企业或开发者版本。
从 GitHub下载适用于iOS的移动演示示例。
用 Xcode 打开 EditorWebViewDemo.xcodeproj 项目，以修改此示例的代码片段，使DMS能够正常工作。

要显示DMS主页，请在 Info.plist 文件的 DocumentServerURL 属性值中指定文档服务器web界面的地址。

<dict>
    ...
    <key>DocumentServerURL</key>
    <string>https://documentserver/</string>
</dict>

其中， documentserver 是安装了ONLYOFFICE 文档服务器的服务器的名称。

如果指定了 DocumentServerURL ，则会加载DMS主页。否则，会发生错误：

private func load() {
    if documentServerUrlString.isEmpty {
        showAlert(title: "Error", message: "You must specify the document server address, the \"DocumentServerURL\" value in the Info.plist file.")
        return
    }

    guard let url = URL(string: documentServerUrlString.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) ?? "") else {
        return
    }

    webView.load(URLRequest(url: url))
}

未指定DocumentServerURL

已指定DocumentServerURL

使用 DocumentServerViewController 控制器在iOS设备上正确打开编辑器。在此控制器中，定义通过WKWebView组件打开文档的函数。首先，请求一个绝对URL并检查它是否包含 "/editor?" 字符串。如果是，请向链接添加其他查询参数（移动平台类型）：

private var openDocumentMarker = "/editor?"
private var additionalQueryParameters = ["type": "mobile"]

func webView(_ webView: WKWebView,
    decidePolicyFor navigationAction:
    WKNavigationAction,
    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void)
{
    guard let urlString = navigationAction.request.url?.absoluteString else {
        decisionHandler(.cancel)
        return
    }

    if urlString.contains(openDocumentMarker),
       let redirectUrl = navigationAction.request.url?.appendingQueryParameters(additionalQueryParameters)
    {
        decisionHandler(.cancel)
        navigator.navigate(to: .documentServerEditor(url: redirectUrl))
    } else {
        reloadItem.isEnabled = true
        backItem.isEnabled = webView.canGoBack
        forwardItem.isEnabled = webView.canGoForward

        title = navigationAction.request.url?.host ?? ""

        decisionHandler(.allow)
    }

}

在 DocumentServerViewController 控制器中，创建DMS主页上可用的导航操作。例如，在我们的测试范例中，它们是用界面元素指定的，例如 Reload, Back, 和 Forward 按钮。
为了便于与编辑器交互，请定义 活动指示器 和 进度视图 UI组件。

DocumentServerViewController 的完整代码可以在此处找到。

活动指示器

进度视图

按钮

要开始处理文档，请通过WKWebView组件在移动设备上显示ONLYOFFICE编辑器。为此，请在 DocumentServerEditorViewController 控制器中设置WKWebView和布局，如下所示：

private func configureView() {
    let preferences = WKPreferences()
    let configuration = WKWebViewConfiguration()
    preferences.javaScriptEnabled = true
    configuration.preferences = preferences

    webView = WKWebView(frame: .zero, configuration: configuration)

    view.addSubview(webView)
    webView.translatesAutoresizingMaskIntoConstraints = false

    webView.navigationDelegate = self
    webView.uiDelegate = self

    if let webViewSuperview = webView.superview {
        webView.topAnchor.constraint(equalTo: webViewSuperview.topAnchor).isActive = true
        webView.leadingAnchor.constraint(equalTo: webViewSuperview.leadingAnchor).isActive = true
        webView.bottomAnchor.constraint(equalTo: webViewSuperview.bottomAnchor).isActive = true
        webView.trailingAnchor.constraint(equalTo: webViewSuperview.trailingAnchor).isActive = true
    }
...
}

在Xcode工具栏中，选择要运行应用程序的构建方案和设备。然后，选择 Product -> Run，或单击项目工具栏中的 Run 按钮来构建和运行代码。
在应用程序的主屏幕上，选择 Using DocumentServer 选项以演示一个将ONLYOFFICE移动web编辑器与ONLYOFF测试或DMS范例集成的示例。

关闭ONLYOFFICE编辑器

使用 DocumentServerEditorViewController 控制器退出编辑器。例如，在当前测试范例中，创建返回按钮以导航到上一屏：

private let goBackUrl = Bundle.main.object(forInfoDictionaryKey: "DocumentServerURL") as? String ?? ""

func webView(_ webView: WKWebView,
    decidePolicyFor navigationAction: WKNavigationAction,
    decisionHandler: @escaping (WKNavigationActionPolicy) -> Void)
{
    guard let urlString = navigationAction.request.url?.absoluteString else {
        decisionHandler(.cancel)
        return
    }
        
    if urlString == goBackUrl {
        decisionHandler(.cancel)
        navigationController?.popViewController(animated: true)
    } else {
        decisionHandler(.allow)
    }
}

退出编辑器的按钮

DocumentServerEditorViewController 的完整代码可以在此处找到。

基于ONLYOFFICE 文档 API的集成

此示例演示如何使用 API文档和配置示例中描述的编辑器配置通过WKWebView打开ONLYOFFICE编辑器。

通过api集成iOS

打开ONLYOFFICE编辑器

下载并安装ONLYOFFICE 文档企业或开发者版本。
从 GitHub下载适用于iOS的移动演示示例。
用 Xcode 打开 EditorWebViewDemo.xcodeproj 项目，以修改此示例的代码片段，使DMS能够正常工作。
创建一个空的 html 文件。用演示项目 editor.html 资源作模板。
添加 div 元素，如下所示：
```
<div id="placeholder"></div>
```
使用将用于您的网站的 JavaScript API 指定您的 ONLYOFFICE 文档服务器链接：
```
<script type="text/javascript" src="https://documentserver/web-apps/apps/api/documents/api.js"></script>
```
其中， documentserver 是安装了ONLYOFFICE 文档服务器的服务器的名称。

使用要打开的文档的配置添加脚本，初始化div元素的文档编辑器：添加脚本指定你想打开的文档，为 div 元素初始化 文档编辑器。

window.docEditor = new DocsAPI.DocEditor("placeholder",
    {
        {external_config},
        "type": "mobile",
        "events": {
            "onAppReady": onAppReady,
            "onDocumentReady": onDocumentReady,
            "onDownloadAs": onDownloadAs,
            "onError": onError,
            "onInfo": onInfo,
            "onRequestClose": onRequestClose,
            "onRequestInsertImage": onRequestInsertImage,
            "onRequestUsers": onRequestUsers,
            "onWarning": onWarning,
        }
    });

要开始处理文档，请通过WKWebView组件在移动设备上显示ONLYOFFICE编辑器。为此，请指定 EditorViewController 控制器。向编辑器请求 editor.html 文件的URL，获取其内容并用示例 samples.plist 文件中的配置替换 "{external_config}" 参数，在这里，根据 API documentation Try page对所有示例配置进行分类：
```
private func load() {
    guard let url = Bundle.main.url(forResource: "editor", withExtension: "html") else {
        return
    }

    var html = ""

    do {
        html = try String(contentsOf: url)
    } catch {
        print(error)
    }

    html = html.replacingOccurrences(of: "{external_config}", with: config ?? "")
    webView.loadHTMLString(html, baseURL: nil)
}
```
ONLYOFFICE编辑器示例

EditorViewController 的完整代码可以在这里找到。
在Xcode工具栏中，选择要运行应用程序的构建方案和设备。然后，选择 Product -> Run，或单击项目工具栏中的 Run 按钮来构建和运行代码。
在应用程序的主屏幕上，选择 使用API配置 选项，演示如何使用API文档和配置示例中描述的编辑器配置打开ONLYOFFICE移动web编辑器。
在下一页中，选择一个配置示例以在WKWebView组件中打开生成的HTML。

使用文档

要使用文档（打开、下载、插入图像、提及其他用户等），请使用API文档的事件和方法：

要跟踪事件并调用适当的方法，请通过 EditorEventsHandler 控制器以本地代码处理ONLYOFFICE编辑器的事件，然后将其委托给 EditorViewController处理：

var delegate: EditorEventsDelegate?

convenience init(configuration: WKWebViewConfiguration) {
    self.init()
   
    configuration.userContentController.add(self, name: EditorEvent.onDownloadAs.rawValue)
    ....
}

extension EditorEventsHandler: WKScriptMessageHandler {
    func userContentController(_ userContentController: WKUserContentController,
        didReceive message: WKScriptMessage)
    {
        let event = EditorEvent(rawValue: message.name)

        switch event {
        case .onDownloadAs:
            guard
                let json = message.body as? [String: Any],
                let fileType = json["fileType"] as? String,
                let url = json["url"] as? String
            else { return }

            delegate?.onDownloadAs(fileType: fileType, url: url)
        ...
        }
    }
}

让我们以 onDownloadAs 事件为例。在WKWebView配置期间，通过调用 configuration.userContentController.add(self, name: messageName)，为特定消息的处理程序注册一个对象。获取事件参数（文件类型和URL）并将事件委托给 EditorViewController处理：

func onDownloadAs(fileType: String, url: String) {
    print("⚡ ONLYOFFICE Document Editor create file: \(url)")
}

定义 callMethod 函数以从本地代码调用 API方法。它可以将字符串、布尔值或对象值作为参数。此函数将方法名及其参数添加到带有JavaScript代码的字符串中，然后使用 evaluateJavaScript 方法运行WKWebView组件中的JavaScript：

private func callMethod(function: String, arg: Bool) {
    let javascript = "window.docEditor.\(function)(\(arg))"
    webView.evaluateJavaScript(javascript, completionHandler: nil)
}

private func callMethod(function: String, arg: String) {
    let javascript = "window.docEditor.\(function)(\"\(arg)\")"
    webView.evaluateJavaScript(javascript, completionHandler: nil)
}

private func callMethod(function: String, arg: [String: Any]) {
    guard
        let json = try? JSONSerialization.data(withJSONObject: arg, options: []),
        let jsonString = String(data: json, encoding: .utf8)
    else {
        return
    }

    let javascript = "window.docEditor.\(function)(\(jsonString))"
    webView.evaluateJavaScript(javascript, completionHandler: nil)
}

EditorEventsHandler 的完整代码可以在这里找到。

要显示下载和打印文档的结果，请使用 PreviewController 控制器。此控制器基于 QLPreviewController。按文档的URL下载文档，并将 dataSource 和 delegate 属性设置为 QLPreviewController：

func present(url: URL, in parent: UIViewController, complation: @escaping (() -> Void)) {
    download(url: url) { fileUrl in
        DispatchQueue.main.async {
            guard let fileUrl = fileUrl else {
                complation()
                return
            }

            self.fileUrl = fileUrl

            let quickLookController = QLPreviewController()
            quickLookController.dataSource = self
            quickLookController.delegate = self

            if QLPreviewController.canPreview(fileUrl as QLPreviewItem) {
                quickLookController.currentPreviewItemIndex = 0
                parent.present(quickLookController, animated: true, completion: nil)
            }
            complation()
        }
    }
}

PreviewController 的完整代码可以在这里找到。

在本节中，我们将使用 GitHub上提供的Android手机演示范例，通过 WebView 查看集成过程。

基于ONLYOFFICE测试范例的集成

此示例演示了如何将ONLYOFFICE移动web编辑器与ONLYOFFICE 测试或DMS范例集成。

通过测试范例实现Android集成

打开ONLYOFFICE编辑器

下载并安装ONLYOFFICE 文档企业或开发者版本。
从 GitHub下载Android手机演示范例。
使用 Android Studio 打开顶层 build.gradle 文件，修改此示例的代码片段，以便DMS正常工作。

要显示DMS的主页，请在模块级 build.gradle 文件的 DOCUMENT_SERVER_URL 属性中指定文档服务器web界面的地址。

buildConfigField("String", "DOCUMENT_SERVER_URL", "https://documentserver/")

其中， documentserver 是安装了ONLYOFFICE 文档服务器的服务器的名称。

如果指定了 DOCUMENT_SERVER_URL ，则会加载DMS主页。否则，会发生错误：

private fun showDialog() {
    AlertDialog.Builder(requireContext())
    .setMessage("Document server url is empty.\nYou must specify the address in build.gradle")
    .setPositiveButton("Ok") { dialog, _ ->
        dialog.dismiss()
        requireActivity().finish()
    }
    .create()
    .show()
}

未指定DocumentServerURL

已指定DocumentServerURL

使用 MainFragment.kt 控制器在Android设备上正确打开编辑器。在此控制器中，定义通过WebView组件打开文档的函数。请求URL并检查它是否包含 "editor" 字符串，这个字符串指定将要打开的文档：

private class MainWebViewClient(private val navController: NavController) : WebViewClient() {

    override fun shouldOverrideUrlLoading(view: WebView?, request: WebResourceRequest?): Boolean {
        val url = request?.url
        if (url != null) {
            val path = url.path
            if (path?.contains("editor") == true) {
                navController.navigate(R.id.action_mainFragment_to_editorFragment, Bundle(1).apply {
                    putString("document_url", url.toString())
                })
                return true
            }
            return false
        }
        return super.shouldOverrideUrlLoading(view, request)
    }

}

MainFragment.kt 的完整代码，可以在这里找到。

要开始处理文档，请通过WebView组件在移动设备上显示ONLYOFFICE编辑器。为此，在 EditorFragment.kt 控制器中设置WebView和布局如下：

@SuppressLint("SetJavaScriptEnabled")
private fun setSettings() {
    webView?.settings?.apply {
        javaScriptEnabled = true
        javaScriptCanOpenWindowsAutomatically = true
        loadWithOverviewMode = true
        cacheMode = WebSettings.LOAD_NO_CACHE
        domStorageEnabled = true
    }
    webView?.webViewClient = EditorWebViewClient(findNavController())
}

在Android Studio工具栏中，选择应用程序和运行应用程序的设备。然后，单击项目工具栏中的 Run 按钮来构建和运行代码。
该应用程序将被打开，以演示一个将ONLYOFFICE移动web编辑器与ONLYOFF测试或DMS范例集成的示例。

关闭ONLYOFFICE编辑器

使用 EditorFragment.kt 控制器退出编辑器：

private class EditorWebViewClient(private val navController: NavController) : WebViewClient() {

    override fun shouldOverrideUrlLoading(view: WebView?, request: WebResourceRequest?): Boolean {
        request?.url?.let { url ->
            if (!url.toString().contains("editor")) {
                navController.popBackStack()
                return true
            }
        }
        return super.shouldOverrideUrlLoading(view, request)
    }

}

EditorFragment.kt 的完整代码可以在这里找到。