WPS Android版API

WPS Android版API

一、WPS Office API简介

通过第三方程序启动WPS，然后进行文档的编辑、修改等操作，甚至可以通过第三方
程序控制wps的一些基本操作，如打开文档、保存、另存、复制、剪切、粘贴、插
入图片（文字）等功能。而根据操作的类型，调用打开方式分为第三方启动方式
以及AIDL方式两种。

二、第三方启动方式

1.方式简介
第三方启动方式是指通过StartActivity方式，启动WPS，启动的时候可以传入一
些参数，以便控制文档的打开效果。主要可以实现控制上次打开进度、上次缩放
进度、 第三方操作身份验证等功能。

2.参数介绍
1: 打开模式参数列表

模式	说明	备注
“ReadOnly”	只读模式
“Normal”	正常模式
“ReadMode”	打开直接进入阅读器模式	仅Word、TXT文档支持
“SaveOnly”	保存模式(打开文件,另存,关闭)	仅Word、TXT文档支持

2: 文档打开参数列表

参数名	参数说明	类型	默认值
OpenMode	打开文件的模式。	String	Normal
SendSaveBroad	文件保存时是否发送广播。	boolean	false
SendCloseBroad	文件关闭时是否发送广播。	boolean	false
ThirdPackage	第三方的包名，关闭的广播会包含该项。	String
ClearBuffer	关闭文件时是否请空临时文件。	boolean	false
ClearTrace	关闭文件时是否删除使用记录	。boolean	false
ClearFile	关闭文件时是否删除打开的文件。	boolean	false
ViewProgress	文件上次查看的进度。	float	0.0%
AutoJump	是否自动跳转到上次查看的进度。	boolean	false
SavePath	文件保存路径。	String
ViewScale	文件上次查看的视图的缩放。	float	1.0
ViewScrollX	文件上次查看的视图的X坐标。	int	0
ViewScrollY	文件上次查看的视图的Y坐标。	int	0
UserName	批注的作者。	String
HomeKeyDown	监听home键并发广播	boolean	false
BackKeyDown	监听back键并发广播	boolean	false
EnterReviseMode	以修订模式打开文档	boolean	false
CacheFileInvisible	Wps生成的缓存文件外部是否可见	boolean	True

PS：以上参数均放在Intent中，如有需要使用或者需要参加，请使用Intent添加或获取参数的方式使用。

例如：

Intent intent = new Intent();

Bundle bundle = new Bundle();

bundle.putString(Define.OPEN_MODE, OpenMode); //打开模式

包名类名相关参数

参数名	普通版	英文版	企业版
className	cn.wps.moffice.documentmanager.PreStartActivity2	cn.wps.moffice.documentmanager.PreStartActivity2	cn.wps.moffice.documentmanager.PreStartActivity2
packageName	cn.wps.moffice_eng	cn.wps.moffice_eng	cn.wps.moffice_ent

3: 广播事件

1. Back按钮广播
   BackKeyDown的值为true的时候，会发送该条广播
   参数：action = “com.kingsoft.writer.back.key.down”

2. Home 按钮广播
   HomeKeyDown 的值为true的时候，会发送该条广播
   参数：action = “com.kingsoft.writer.home.key.down”

3. 保存文件
   文件保存时，SendSaveBroad为true的时候
   会发送一个”cn.wps.moffice.file.save”的广播。

   广播含有以下信息，具体见下表。

   参数名	参数说明	类型
   “OpenFile”	文件最初的路径	String
   “ThirdPackage”	传入的第三方的包名。	String
   “SavePath”	文件这次保存的路径	String

4. 关闭文件
   文件关闭时，SendCloseBroad值为true时
   会发送一个”cn.wps.moffice.file.close”的广播。

   广播含有以下信息，具体见下表。

参数名	参数说明	类型	默认值
“CloseFile”	关闭文件的路径	String
“ThirdPackage”	传入的第三方的包名。	String
“ViewProgress”	文件查看的进度 float	0.0%
“ViewScale”	文件上次查看的视图的缩放	float	1.0
“ViewScrollX”	文件上次查看的视图的X坐标	int	0
“ViewScrollY”	文件上次查看的视图的Y坐标	int	0

示例代码
PS：使用StartActivity方式，传入指定的参数，即可控制WPS打开的时候表现方式。以打开指定路径的文档为例：

public class WpsModel {
    public static final String OPEN_MODE = "OpenMode";// 打开文件的模式。  
    public static final String SEND_SAVE_BROAD = "SendSaveBroad";// 文件保存时是否发送广播。  
    public static final String SEND_CLOSE_BROAD = "SendCloseBroad";// 文件关闭时是否发送广播  
    public static final String THIRD_PACKAGE = "ThirdPackage";// 第三方的包名，关闭的广播会包含该项。  
    public static final String CLEAR_BUFFER = "ClearBuffer";// 关闭文件时是否请空临时文件。  
    public static final String CLEAR_TRACE = "ClearTrace";// 关闭文件时是否删除使用记录。  
    public static final String CLEAR_FILE = "ClearFile";// 关闭文件时是否删除打开的文件。  
    public static final String VIEW_PROGRESS = "ViewProgress";// 文件上次查看的进度。  
    public static final String AUTO_JUMP = "AutoJump";// 是否自动跳转到上次查看的进度。  
    public static final String SAVE_PATH = "SavePath";// 文件保存路径。  
    public static final String VIEW_SCALE = "ViewScale";// 文件上次查看的视图的缩放。  
    public static final String VIEW_SCALE_X = "ViewScrollX";// 文件上次查看的视图的X坐标。  
    public static final String VIEW_SCALE_Y = "ViewScrollY";// 文件上次查看的视图的Y坐标。  
    public static final String USER_NAME = "UserName";// 批注的作者。  
    public static final String HOMEKEY_DOWN = "HomeKeyDown";// 监听home键并发广播  
    public static final String BACKKEY_DOWN = "BackKeyDown";// 监听back键并发广播  
    public static final String ENTER_REVISE_MODE = "EnterReviseMode";// 以修订模式打开文档  
    public static final String CACHE_FILE_INVISIBLE = "CacheFileInvisible";// Wps生成的缓存文件外部是否可见  

    public class OpenMode {
        public static final String NORMAL = "Normal";// 只读模式  
        public static final String READ_ONLY = "ReadOnly";// 正常模式  
        public static final String READ_MODE = "ReadMode";// 打开直接进入阅读器模式  
        // 仅Word、TXT文档支持
        public static final String SAVE_ONLY = "SaveOnly";// 保存模式(打开文件,另存,关闭)  
        // 仅Word、TXT文档支持
    }

    public class ClassName {
        public static final String NORMAL = "cn.wps.moffice.documentmanager.PreStartActivity2";
            // 普通版
        public static final String ENGLISH = "cn.wps.moffice.documentmanager.PreStartActivity2";
            // 英文版
        public static final String ENTERPRISE = "cn.wps.moffice.documentmanager.PreStartActivity2";
            // 企业版
    }

    public class PackageName {
        public static final String NORMAL = "cn.wps.moffice_eng";// 普通版  
        public static final String ENGLISH = "cn.wps.moffice_eng";// 英文版  
    }

    public class Reciver {
        public static final String ACTION_BACK = "com.kingsoft.writer.back.key.down";// 返回键广播  
        public static final String ACTION_HOME = "com.kingsoft.writer.home.key.down";// Home键广播  
        public static final String ACTION_SAVE = "cn.wps.moffice.file.save";// 保存广播  
        public static final String ACTION_CLOSE = "cn.wps.moffice.file.close";// 关闭文件广播  
    }
}  

boolean openFile(String path) {

        Intent intent = new Intent();
        Bundle bundle = new Bundle();
        bundle.putString(WpsModel.OPEN_MODE, WpsModel.OpenMode.READ_ONLY);
        //打开模式
        bundle.putBoolean(WpsModel.SEND_SAVE_BROAD, true);
        //关闭时是否发送广播
        bundle.putString(WpsModel.THIRD_PACKAGE, getApplication().getPackageName());
        //第三方应用的包名，用于对改应用合法性的验证
        bundle.putBoolean(WpsModel.CLEAR_TRACE, true);
        //清除打开记录
        //bundle.putBoolean(CLEAR_FILE, true);
        //关闭后删除打开文件
        intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
        intent.setAction(android.content.Intent.ACTION_VIEW);
        intent.setClassName(WpsModel.PackageName.NORMAL, WpsModel.ClassName.NORMAL);
        File file = new File(path);
        if (!file.exists()){
            return false;
        }
        Uri uri = Uri.fromFile(file);
        intent.setData(uri);
        intent.putExtras(bundle);
        try {
            startActivity(intent);
        } catch (ActivityNotFoundException e) {
            e.printStackTrace();
            return false;
        }
        return true;
    }

注册广播
@Override
    public void onCreate() {
        super.onCreate();
        IntentFilter filter = new IntentFilter();
        filter.addAction(WpsModel.Reciver.ACTION_CLOSE);
        filter.addAction(WpsModel.Reciver.ACTION_SAVE);
        registerReceiver(mReceiver, filter);
    }

    @Override
    public void onDestroy() {
        super.onDestroy();
        unregisterReceiver(mReceiver);
    }

    private final BroadcastReceiver mReceiver = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            String action = intent.getAction();
            if (WpsModel.Reciver.ACTION_CLOSE.equals(action)) {
                //TODO
            } else if (WpsModel.Reciver.ACTION_SAVE.equals(action)) {
                 //TODO
            }
        }
    };

三、AIDL方式

1. 方式简介
   AIDL方式启动WPS是指，通过绑定Service，调用WPS对外暴露的接口
   直接操作WPS的功能。如打开、保存、另存、打开手绘等。

   两种操作方式各有利弊
   使用第三方启动方式，简单方便，但是仅仅能控制一些打开文档的显示方式
   使用AIDL方式打开可以操控的功能比较多，但是实现较为复杂。
   下面我们介绍一下具体的操作实现。

AIDL操作实现

下面代码展示如何绑定WPS的Service，通过获得绑定的Service对象
调用对应的接口，即可操作WPS的相关功能。

public static final String OFFICE_SERVICE_ACTION = "cn.wps.moffice.service.OfficeService";
    public static final String PRO_OFFICE_SERVICE_ACTION =
        "cn.wps.moffice.service.ProOfficeService";
    private boolean mIsBound;

    void doBindService() {
        Intent intentOfficeService = new Intent(PRO_OFFICE_SERVICE_ACTION);
        // PRO_OFFICE_SERVICE_ACTION是绑定service的IntentFilter，之前版本提供的OFFICE_SERVICE_ACTION
        // 也可以使用，只不过为了避免和个人版的冲突，添加了一个新参数
        intentOfficeService.putExtra("DisplayView", true);
        bindService(intentOfficeService, mConnection, BIND_AUTO_CREATE);
    }

    void doUnbindService() {
        if (mIsBound) {
            unbindService(mConnection);
            mIsBound = false;
        }
    }

    //获取连接实例

    private ServiceConnection connection = new ServiceConnection() {
        @Override
        public void onServiceConnected(ComponentName name, IBinder service) {
            mService = OfficeService.Stub.asInterface(service);
        }

        @Override
        public void onServiceDisconnected(ComponentName name) {
            mService = null;
        }
    };


    Intent intent = new Intent();
    Bundle bundle = new Bundle();
    bundle.putBoolean(Define.BACK_KEY_DOWN,true);//监听Back键事件,对外发送广播
    intent.putExtras(bundle);
    mDoc =mService.openDocument(path,"",intent);//mService为绑定文档后返回的对象

**注意：第三方程序如果需要使用AIDL方式操作wps，
需要将 moffice-aidl.jar和moffice-event-interface.jar
两个jar包导入到自己的工程中，并在eclipse中选择Java Build
Path的Order and Export中选中两个jar包，这样编出的第三方应用程
序才能正常操作控制wps。**

AIDL接口介绍

OfficeService对象	方法摘要
Documents	getDocuments();获取文档对象集合
Document	openDocument(String docPath, String password, Intent intent)： 打开文字文档获得文档对象；参数说明：docPath:要打开的文档路径Password:WPS加密文档的密码 如果文档没有使用WPS加密，传入””;Intent：包装其他数据，传入不同的打开参数，实现不同的效果 文档具体打开参数见附录1。
Workbooks	getWorkbooks();获取表格对象集合；暂时不支持带界面的操作
Workbook	openWorkbook(String path, String password);打开表格文档，获取表格文档对象； 暂时不支持带界面的操作
Document	newDocument(String newDocPath, in Intent intent); 功能：新建一个doc文档，newDocPath是文件路径，intent是AIDL操作文档的一些设置，与openDocument的intent相同作用