Skip to content

API文档_Android_Java_LuaContext

Jump to bottom
vimfung edited this page Nov 16, 2018 · 7 revisions

API文档 > 类目录 > LuaContext

LuaContext

Summary

LuaScriptCore框架的核心类型之一，想要让Android原生代码与lua进行交互则必须由这个上下文对象来管理所有的交互细节。其封装了一系列的方法用于简化桥接过程，不需要使用者熟悉lua的c api接口。只要像平时编写代码一样实现业务逻辑即可。同时，每个LuaContext对象所维护的lua环境是相对独立的，不能进行数据上的共享。

包

cn.vimfung.luascriptcore

继承

LuaContext > LuaBaseObject

Constructor

该类型不允许直接构造，需要使用类方法create来实现初始化。

Class Methods

create

创建上下文对象，使用该方法来代替构造函数实现LuaContext的初始化。

声明
static LuaContext create(LuaEnv env);
static LuaContext create(Context context);
参数
  • env: 环境参数，用于设定一些框架外界的信息，方便框架进行获取和使用。
  • context: Android应用的上下文环境
返回

新创建的Lua上下文环境对象实例

Instance Methods

addSearchPath

添加搜索路径。在lua脚本中当使用require来引用其他lua脚本时，默认情况下，lua解析器只会查找一些内置的搜索路径（如lua解析器所在目录，系统库目录等）。如果引用的脚本不在这些内置目录中则会提示无法找到对应的脚本文件。这时候就需要使用此方法来添加一个搜索路径，让解析器可以在指定的路径下查找lua脚本文件。

在LuaContext中默认添加了lua缓存目录作为搜索路径（缓存目录中的lua文件是由assets中拷贝而来）。

声明
void addSearchPath (String path);
参数
  • path: 需要搜索的绝对路径地址。
示例
File cacheDir = new File (String.format("%s/lua", applicationContext.getCacheDir()));
luaContext.addSearchPath(cacheDir.toString());

evalScript

将lua脚本内容以字符串形式传给LuaContext来解析。这种方式使用灵活，可以在程序执行时动态生成脚本让上下文对象进行解析。脚本内容可以带有返回值（只要在内容最后写入return关键字即可返回想要的结果），在方法执行完后，返回值会封装在LuaValue对象中。

声明
LuaValue evalScript (String script);
参数
  • script: lua脚本字符串
返回值

脚本的返回值会被封装在LuaValue对象中返回，开发者可以通过LuaValue来取得返回值并作后续的操作。

示例
String scriptText = "return \"Hello World!\";";
LuaValue retVal = context.evalScript(script);
Log.v("lsc", String.format("retVal = %s", retVal.toString()));

evalScriptFromFile

通过传入lua脚本文件所在路径来解析脚本。传入路径分两种情况：如果脚本包含在应用包内，则可以通过传入相对路径来指定脚本路径。除了前面说到的情况外都必须传入绝对路径来指定脚本的位置。

声明
LuaValue evalScriptFromFile (String filePath);
参数
  • path: lua脚本文件所在路径
返回值

脚本的返回值会被封装在LuaValue对象中返回，开发者可以通过LuaValue来取得返回值并作后续的操作。

示例
String scriptPath = String.format("%s/lua/test.lua", applicationContext.getCacheDir());
LuaValue retVal = context.evalScriptFromFile(scriptPath);
Log.v("lsc", retVal.toString());

callMethod

使用该方法可以在原生层让一个lua层的方法进行调用执行并返回结果，传入方法名称和参数即可。其中方法的每个参数要求封装到一个LuaValue对象中，并且添到一个数组类型中传入给方法，数组的元素位置表示参数的顺序（下标0的元素表示方法第一个参数，下标1表示第二个参数，如此类推）。

对于registerMethod注册到lua的方法，同样可以使用该方法进行调用。

声明
LuaValue callMethod(String methodName, LuaValue[] arguments);
参数
  • methodName: 方法名称，全局方法可以直接写方法名，如果是某个对象/Table中的方法可以使用xxx:methodName或xxx.methodName方式传入（其中xxx为对象/Table的名称）。
  • arguments: 参数列表，所需参数先封装成LuaValue对象后放入到数组中，再统一传入方法。
返回值

方法的返回值会被封装在LuaValue对象中返回，开发者可以通过LuaValue来取得返回值并作后续的操作。

示例

假设lua中存在下面一个方法

function testMethod(msg)

    return "say: " .. msg

end

原生层可以这样调用

LuaValue[] args = new LuaValue[] {new LuaValue("Hello World")};
LuaValue retVal = this.callMethod("testMethod", args);
Log.v("lsc", String.format("retVal = %s", retVal.toString()));

registerMethod

将一段原生层的处理逻辑注册为一个lua方法提供lua层调用。对于一些功能lua无法直接处理的（如调用手机的摄像头拍照），可以使用该方法让原生层来负责处理，并在lua层生成一个方法入口，让lua层在任何地方都可以调用。

其中原生处理逻辑也由LuaMethodHandler接口形式传入给方法，其声明如下：

interface LuaMethodHandler
{
    public LuaValue onExecute(LuaValue[] arguments);
}

其中onExecute方法是需要实现的处理逻辑。

声明
void registerMethod(String methodName, LuaMethodHandler handler);
参数
  • methodName: 注册到lua层的方法名称。如果lua存在同名方法，则会被该操作覆盖之前的方法。
  • block: 方法的处理逻辑。
示例
context.registerMethod("testMethod", new LuaMethodHandler() {
    @Override
    public LuaValue onExecute(LuaValue[] arguments) {
        return new LuaValue("Hello World!");
    }
});

lua中可以这样调用

local retVal = testMethod();
print (retVal);

onException

在lua脚本执行过程中可能会产生一些异常，通过该方法可以对产生的异常进行捕获并处理，同时也方便在开发过程中的调试工作。

该方法要求传入一个异常处理类型LuaExceptionHandler，其声明如下：

interface LuaExceptionHandler
{
    public void onException(String message);
}

其中接口中的onException为处理异常处理方法。

声明
void onException (LuaExceptionHandler handler);
参数
  • handler: 异常的处理方法
示例

下例是将lua中的异常输出到日志中进行查看，这样可以方便开发中的调试工作。

context.onException(new LuaExceptionHandler() {
    @Override
    public void onException(String message) {
        Log.v("lsc", String.format("lua exception = %s", message));
    }
});

raiseException

在lua层调用一个原生方法时，如果lua传入参数不符合规则或者在方法处理过程中出现一些错误，则不能让lua脚本继续向下执行，可以使用该方法来抛出一个lua的异常，让lua中断执行。需要注意的是，在抛出lua异常同时，该方法也会抛出一个原生异常，所以需要原生代码使用try-catch来进行异常捕获。

声明
void raiseException (String message) throws Error;
参数
  • message: 抛出异常的消息内容。用于告知异常产生的原因。
示例

下例通过在注册lua方法中判断lua是否有传入一个字符串参数给原生，如果没有则抛出异常。

context.registerMethod("testMethod", new LuaMethodHandler() {
    @Override
    public LuaValue onExecute(LuaValue[] arguments) {
                
        try 
        {
            if (arguments.length == 0 || arguments[0].valueType() != LuaValueType.String)
            {
                raiseException("argument invalid");
            }
                    
            String msg = arguments[0].toString();
            return new LuaValue(String.format("say: %s", msg));
        }
        catch (Exception ex)
        {
            return null;
        }
    }
});

setGlobal

为lua层的某个全局变量赋值，如果指定变量名称不存在则创建变量，如果存在则覆盖变量原有值。其中变量的值需要先封装到LuaValue中再传给方法。

声明
void setGlobal(String name, LuaValue value);
参数
  • value: 变量的值
  • name: 变量名称
示例

在原生层中为lua的msg全局变量赋值

LuaValue value = new LuaValue("Hello World");
context.setGlobal("msg", value);

lua层中就可以对msg变量进行使用

print(msg);  -- 输出Hello World

getGlobal

通过变量名称来获取lua层中全局变量的值。返回值会封装在LuaValue对象中返回给原生层。

声明
LuaValue getGlobal(String name);
参数
  • name: 变量名称
返回值

封装成LuaValue对象返回全局变量的值。

示例

下面例子演示获取lua中的全局变量msg并打印

LuaValue value = this.getGlobal("msg");
Log.v("lsc", String.format("value = %s", value.toString()));

retainValue

用于保留lua层变量的引用，延长其生命周期。在一般情况下，lua和原生两层变量有着不同且独立的内存管理方式，因此为了避免在原生层操作lua层变量时，lua层已对变量进行内存释放所带来的异常，就要使用该方法来保留lua层对变量的引用，直到原生层调用releaseValue方法后进行释放。最常见的情况是原生层引用lua层以local声明的function来进行回调。

记得注意的是，调用该方法引用变量，会以引用次数来维护该变量的生命周期，即调用了多少次retainValue方法，就需要对应次数的releaseValue方法才能对变量进行内存释放。同时，被引用的是lua的变量而非传入的LuaValue对象，所以不同的LuaValue对象封装相同的变量，其引用次数会累计在同一个变量上。

该方法只适用于function、table、userdata以及导出类型对象实例。

声明
void retainValue(LuaValue value);
参数
  • value: 需要引用的lua变量。
示例

下例演示对lua传入的function对象进行引用

context.registerMethod("testMethod", new LuaMethodHandler() {
    @Override
    public LuaValue onExecute(LuaValue[] arguments) {
                
        if (arguments.length > 0 && arguments[0].valueType() == LuaValueType.Function)
        {
            context.retainValue(arguments[0]);
        }
                
        return new LuaValue();
    }
});

releaseValue

与retainValue方法相对应，用于释放被引用的lua变量。每次调用都会使变量的引用次数减1，直到引用次数为0时，对象被释放。

声明
void releaseValue(LuaValue value);
参数
  • value: 需要释放的变量
Clone this wiki locally