Engines - 脚本引擎
<p>[TOC]</p>
<h1>Engines</h1>
<blockquote>
<p>Stability: 2 - Stable</p>
</blockquote>
<p>engines模块包含了一些与脚本环境、脚本运行、脚本引擎有关的函数，包括运行其他脚本，关闭脚本等。</p>
<p>例如，获取脚本所在目录：</p>
<pre><code>toast(engines.myEngine().cwd());</code></pre>
<h2>engines.execScript(name, script[, config])</h2>
<ul>
<li><code>name</code> {string} 要运行的脚本名称。这个名称和文件名称无关，只是在任务管理中显示的名称。</li>
<li><code>script</code> {string} 要运行的脚本内容。</li>
<li><code>config</code> {Object} 运行配置项
<ul>
<li><code>delay</code> {number} 延迟执行的毫秒数，默认为0</li>
<li><code>loopTimes</code> {number} 循环运行次数，默认为1。0为无限循环。</li>
<li><code>interval</code> {number} 循环运行时两次运行之间的时间间隔，默认为0</li>
<li><code>path</code> {Array} | {string} 指定脚本运行的目录。这些路径会用于require时寻找模块文件。</li>
</ul></li>
</ul>
<p>在新的脚本环境中运行脚本script。返回一个<a href="#engines_scriptexecution">ScriptExectuion</a>对象。</p>
<p>所谓新的脚本环境，指定是，脚本中的变量和原脚本的变量是不共享的，并且，脚本会在新的线程中运行。</p>
<p>最简单的例子如下：</p>
<pre><code>engines.execScript("hello world", "toast('hello world')");</code></pre>
<p>如果要循环运行，则：</p>
<pre><code>//每隔3秒运行一次脚本，循环10次
engines.execScript("hello world", "toast('hello world')", {
loopTimes: 10,
interval: 3000
});</code></pre>
<p>用字符串来编写脚本非常不方便，可以结合 <code>Function.toString()</code>的方法来执行特定函数:</p>
<pre><code>function helloWorld(){
//注意，这里的变量和脚本主体的变量并不共享
toast("hello world");
}
engines.execScript("hello world", "helloWorld();\n" + helloWorld.toString());</code></pre>
<p>如果要传递变量，则可以把这些封装成一个函数：</p>
<pre><code>function exec(action, args){
args = args || {};
engines.execScript(action.name, action.name + "(" + JSON.stringify(args) + ");\n" + action.toString());
}
//要执行的函数，是一个简单的加法
function add(args){
toast(args.a + args.b);
}
//在新的脚本环境中执行 1 + 2
exec(add, {a: 1, b:2});</code></pre>
<h2>engines.execScriptFile(path[, config])</h2>
<ul>
<li><code>path</code> {string} 要运行的脚本路径。</li>
<li><code>config</code> {Object} 运行配置项
<ul>
<li><code>delay</code> {number} 延迟执行的毫秒数，默认为0</li>
<li><code>loopTimes</code> {number} 循环运行次数，默认为1。0为无限循环。</li>
<li><code>interval</code> {number} 循环运行时两次运行之间的时间间隔，默认为0</li>
<li><code>path</code> {Array} | {string} 指定脚本运行的目录。这些路径会用于require时寻找模块文件。</li>
</ul></li>
</ul>
<p>在新的脚本环境中运行脚本文件path。返回一个<a href="#ScriptExecution">ScriptExecution</a>对象。</p>
<pre><code>engines.execScriptFile("/sdcard/脚本/1.js");</code></pre>
<h2>engines.execAutoFile(path[, config])</h2>
<ul>
<li><code>path</code> {string} 要运行的录制文件路径。</li>
<li><code>config</code> {Object} 运行配置项
<ul>
<li><code>delay</code> {number} 延迟执行的毫秒数，默认为0</li>
<li><code>loopTimes</code> {number} 循环运行次数，默认为1。0为无限循环。</li>
<li><code>interval</code> {number} 循环运行时两次运行之间的时间间隔，默认为0</li>
<li><code>path</code> {Array} | {string} 指定脚本运行的目录。这些路径会用于require时寻找模块文件。</li>
</ul></li>
</ul>
<p>在新的脚本环境中运行录制文件path。返回一个<a href="#ScriptExecution">ScriptExecution</a>对象。</p>
<pre><code>engines.execAutoFile("/sdcard/脚本/1.auto");</code></pre>
<h2>engines.stopAll()</h2>
<p>停止所有正在运行的脚本。包括当前脚本自身。</p>
<h2>engines.stopAllAndToast()</h2>
<p>停止所有正在运行的脚本并显示停止的脚本数量。包括当前脚本自身。</p>
<h2>engines.myEngine()</h2>
<p>返回当前脚本的脚本引擎对象(<a href="#engines_scriptengine">ScriptEngine</a>)</p>
<p><strong>[v4.1.0新增]</strong>
特别的，该对象可以通过<code>execArgv</code>来获取他的运行参数，包括外部参数、intent等。例如：</p>
<pre><code>log(engines.myEngine().execArgv);</code></pre>
<p>普通脚本的运行参数通常为空，通过定时任务的广播启动的则可以获取到启动的intent。</p>
<h2>engines.all()</h2>
<ul>
<li>返回 {Array}</li>
</ul>
<p>返回当前所有正在运行的脚本的脚本引擎<a href="#engines_scriptengine">ScriptEngine</a>的数组。</p>
<pre><code>log(engines.all());</code></pre>
<h1>ScriptExecution</h1>
<p>执行脚本时返回的对象，可以通过他获取执行的引擎、配置等，也可以停止这个执行。</p>
<p>要停止这个脚本的执行，使用<code>exectuion.getEngine().forceStop()</code>.</p>
<h2>ScriptExecution.getEngine()</h2>
<p>返回执行该脚本的脚本引擎对象(<a href="#engines_scriptengine">ScriptEngine</a>)</p>
<h2>ScriptExecution.getConfig()</h2>
<p>返回该脚本的运行配置(<a href="#engines_scriptconfig">ScriptConfig</a>)</p>
<h1>ScriptEngine</h1>
<p>脚本引擎对象。</p>
<h2>ScriptEngine.forceStop()</h2>
<p>停止脚本引擎的执行。</p>
<h2>ScriptEngine.cwd()</h2>
<ul>
<li>返回 {string}</li>
</ul>
<p>返回脚本执行的路径。对于一个脚本文件而言为这个脚本所在的文件夹；对于其他脚本，例如字符串脚本，则为<code>null</code>或者执行时的设置值。</p>
<h2>ScriptEngine.getSource()</h2>
<ul>
<li>返回 <a href="#engines_scriptsource">ScriptSource</a></li>
</ul>
<p>返回当前脚本引擎正在执行的脚本对象。</p>
<pre><code>log(engines.myEngine().getSource());</code></pre>
<h2>ScriptEngine.emit(eventName[, ...args])</h2>
<ul>
<li><code>eventName</code> {string} 事件名称</li>
<li><code>...args</code> {any} 事件参数</li>
</ul>
<p>向该脚本引擎发送一个事件，该事件可以在该脚本引擎对应的脚本的events模块监听到并在脚本主线程执行事件处理。</p>
<p>例如脚本receiver.js的内容如下：</p>
<pre><code>//监听say事件
events.on("say", function(words){
toastLog(words);
});
//保持脚本运行
setInterval(()=>{}, 1000);</code></pre>
<p>同一目录另一脚本可以启动他并发送该事件：</p>
<pre><code>//运行脚本
var e = engines.execScriptFile("./receiver.js");
//等待脚本启动
sleep(2000);
//向该脚本发送事件
e.getEngine().emit("say", "你好");</code></pre>
<h1>ScriptConfig</h1>
<p>脚本执行时的配置。</p>
<h2>delay</h2>
<ul>
<li>{number}</li>
</ul>
<p>延迟执行的毫秒数</p>
<h2>interval</h2>
<ul>
<li>{number}</li>
</ul>
<p>循环运行时两次运行之间的时间间隔</p>
<h2>loopTimes</h2>
<ul>
<li>{number}</li>
</ul>
<p>循环运行次数</p>
<h2>getPath()</h2>
<ul>
<li>返回 {Array}</li>
</ul>
<p>返回一个字符串数组表示脚本运行时模块寻找的路径。</p>