Functions

DEPRECATED()

DEPRECATED(newfunction, oldname, newname)

定义一个作废的接口

PRINT_DEPRECATED()

PRINT_DEPRECATED(msg)

显示作废信息

printLog()

printLog(tag, fmt, ...)

打印调试信息

用法示例

printLog("WARN", "Network connection lost at %d", os.time())

Parameters

·        string tag 调试信息的 tag

·        string fmt 调试信息格式

·        [mixed ...] 更多参数

printError()

printError(fmt, ...)

输出 tag 为 ERR 的调试信息

Parameters

·        string fmt 调试信息格式

·        [mixed ...] 更多参数

printInfo()

printInfo(fmt, ...)

输出 tag 为 INFO 的调试信息

Parameters

·        string fmt 调试信息格式

·        [mixed ...] 更多参数

dump()

dump(value, desciption, nesting)

输出值的内容

用法示例

local t = {comp = "chukong", engine = "quick"}

dump(t)

Parameters

·        mixed value 要输出的值

·        [string desciption] 输出内容前的文字描述

@parma [integer nesting] 输出时的嵌套层级，默认为 3

Functions

printf()

printf(fmt, ...)

输出格式化字符串

printf("The value = %d", 100)

Parameters

·        string fmt 输出格式

·        [mixed ...] 更多参数

checknumber()

checknumber(value, base)

检查并尝试转换为数值，如果无法转换则返回 0

Parameters

·        mixed value 要检查的值

·        [integer base] 进制，默认为十进制

Returns

·        number

checkint()

checkint(value)

检查并尝试转换为整数，如果无法转换则返回 0

Parameters

·        mixed value 要检查的值

Returns

·        integer

checkbool()

checkbool(value)

检查并尝试转换为布尔值，除了 nil 和 false，其他任何值都会返回 true

Parameters

·        mixed value 要检查的值

Returns

·        boolean

checktable()

checktable(value)

检查值是否是一个表格，如果不是则返回一个空表格

Parameters

·        mixed value 要检查的值

Returns

·        table

isset()

isset(hashtable, key)

如果表格中指定 key 的值为 nil，或者输入值不是表格，返回 false，否则返回 true

Parameters

·        table hashtable 要检查的表格

·        mixed key 要检查的键名

Returns

·        boolean

clone()

clone(object)

深度克隆一个值

-- 下面的代码，t2 是 t1 的引用，修改 t2 的属性时，t1 的内容也会发生变化

local t1 = {a = 1, b = 2}

local t2 = t1

t2.b = 3    -- t1 = {a = 1, b = 3} <-- t1.b 发生变化

-- clone() 返回 t1 的副本，修改 t2 不会影响 t1

local t1 = {a = 1, b = 2}

local t2 = clone(t1)

t2.b = 3    -- t1 = {a = 1, b = 2} <-- t1.b 不受影响

Parameters

·        mixed object 要克隆的值

Returns

·        mixed

class()

class(classname, super)

创建一个类

-- 定义名为 Shape 的基础类

local Shape = class("Shape")

-- ctor() 是类的构造函数，在调用 Shape.new() 创建 Shape 对象实例时会自动执行

function Shape:ctor(shapeName)

    self.shapeName = shapeName

    printf("Shape:ctor(%s)", self.shapeName)

end

-- 为 Shape 定义个名为 draw() 的方法

function Shape:draw()

    printf("draw %s", self.shapeName)

end

--

-- Circle 是 Shape 的继承类

local Circle = class("Circle", Shape)

function Circle:ctor()

    -- 如果继承类覆盖了 ctor() 构造函数，那么必须手动调用父类构造函数

    -- 类名.super 可以访问指定类的父类

    Circle.super.ctor(self, "circle")

    self.radius = 100

end

function Circle:setRadius(radius)

    self.radius = radius

end

-- 覆盖父类的同名方法

function Circle:draw()

    printf("draw %s, raidus = %0.2f", self.shapeName, self.raidus)

end

--

local Rectangle = class("Rectangle", Shape)

function Rectangle:ctor()

    Rectangle.super.ctor(self, "rectangle")

end

--

local circle = Circle.new()             -- 输出: Shape:ctor(circle)

circle:setRaidus(200)

circle:draw()                           -- 输出: draw circle, radius = 200.00

local rectangle = Rectangle.new()       -- 输出: Shape:ctor(rectangle)

rectangle:draw()                        -- 输出: draw rectangle

高级用法

class() 除了定义纯 Lua 类之外，还可以从 C++ 对象继承类。

比如需要创建一个工具栏，并在添加按钮时自动排列已有的按钮，那么我们可以使用如下的代码：

-- 从 cc.Node 对象派生 Toolbar 类，该类具有 cc.Node 的所有属性和行为

local Toolbar = class("Toolbar", function()

    return display.newNode() -- 返回一个 cc.Node 对象

end)

-- 构造函数

function Toolbar:ctor()

    self.buttons = {} -- 用一个 table 来记录所有的按钮

end

-- 添加一个按钮，并且自动设置按钮位置

function Toolbar:addButton(button)

    -- 将按钮对象加入 table

    self.buttons[#self.buttons + 1] = button

    -- 添加按钮对象到 cc.Node 中，以便显示该按钮

    -- 因为 Toolbar 是从 cc.Node 继承的，所以可以使用 addChild() 方法

    self:addChild(button)

    -- 按照按钮数量，调整所有按钮的位置

    local x = 0

    for _, button in ipairs(self.buttons) do

        button:setPosition(x, 0)

        -- 依次排列按钮，每个按钮之间间隔 10 点

        x = x + button:getContentSize().width + 10

    end

end

class() 的这种用法让我们可以在 C++ 对象基础上任意扩展行为。

既然是继承，自然就可以覆盖 C++ 对象的方法：

function Toolbar:setPosition(x, y)

    -- 由于在 Toolbar 继承类中覆盖了 cc.Node 对象的 setPosition() 方法

    -- 所以我们要用以下形式才能调用到 cc.Node 原本的 setPosition() 方法

    getmetatable(self).setPosition(self, x, y)

    printf("x = %0.2f, y = %0.2f", x, y)

end

注意: Lua 继承类覆盖的方法并不能从 C++ 调用到。也就是说通过 C++ 代码调用这个 cc.Node 对象的 setPosition() 方法时，并不会执行我们在 Lua 中定义的 Toolbar:setPosition() 方法。

Parameters

·        string classname 类名

·        [mixed super] 父类或者创建对象实例的函数

Returns

·        table

iskindof()

iskindof(obj, classname)

如果对象是指定类或其子类的实例，返回 true，否则返回 false

local Animal = class("Animal")

local Duck = class("Duck", Animal)

print(iskindof(Duck.new(), "Animal")) -- 输出 true

Parameters

·        mixed obj 要检查的对象

·        string classname 类名

Returns

·        boolean

import()

import(moduleName, currentModuleName)

载入一个模块

import() 与 require() 功能相同，但具有一定程度的自动化特性。

假设我们有如下的目录结构：

app/

app/classes/

app/classes/MyClass.lua

app/classes/MyClassBase.lua

app/classes/data/Data1.lua

app/classes/data/Data2.lua

MyClass 中需要载入 MyClassBase 和MyClassData。如果用 require()，MyClass 内的代码如下：

local MyClassBase = require("app.classes.MyClassBase")

local MyClass = class("MyClass", MyClassBase)

local Data1 = require("app.classes.data.Data1")

local Data2 = require("app.classes.data.Data2")

假如我们将 MyClass 及其相关文件换一个目录存放，那么就必须修改 MyClass 中的 require() 命令，否则将找不到模块文件。

而使用 import()，我们只需要如下写：

local MyClassBase = import(".MyClassBase")

local MyClass = class("MyClass", MyClassBase)

local Data1 = import(".data.Data1")

local Data2 = import(".data.Data2")

当在模块名前面有一个"." 时，import() 会从当前模块所在目录中查找其他模块。因此 MyClass 及其相关文件不管存放到什么目录里，我们都不再需要修改MyClass 中的 import() 命令。这在开发一些重复使用的功能组件时，会非常方便。

我们可以在模块名前添加多个"." ，这样 import() 会从更上层的目录开始查找模块。

~

不过 import() 只有在模块级别调用（也就是没有将 import() 写在任何函数中）时，才能够自动得到当前模块名。如果需要在函数中调用 import()，那么就需要指定当前模块名：

# MyClass.lua

# 这里的 ... 是隐藏参数，包含了当前模块的名字，所以最好将这行代码写在模块的第一行

local CURRENT_MODULE_NAME = ...

local function testLoad()

    local MyClassBase = import(".MyClassBase", CURRENT_MODULE_NAME)

    # 更多代码

end

Parameters

·        string moduleName 要载入的模块的名字

·        [string currentModuleName] 当前模块名

Returns

·        module

handler()

handler(obj, method)

将 Lua 对象及其方法包装为一个匿名函数

在quick-cocos2d-x 中，许多功能需要传入一个 Lua 函数做参数，然后在特定事件发生时就会调用传入的函数。例如触摸事件、帧事件等等。

local MyScene = class("MyScene", function()

    return display.newScene("MyScene")

end)

function MyScene:ctor()

    self.frameTimeCount = 0

    -- 注册帧事件

    self:addNodeEventListener(cc.NODE_ENTER_FRAME_EVENT, self.onEnterFrame)

    self:scheduleUpdate()

end

function MyScene:onEnterFrame(dt)

    self.frameTimeCount = self.frameTimeCount + dt

end

上述代码执行时将出错，报告"Invalid self" ，这就是因为 C++ 无法识别 Lua 对象方法。因此在调用我们传入的 self.onEnterFrame 方法时没有提供正确的参数。

要让上述的代码正常工作，就需要使用 handler() 进行一下包装：

function MyScene:ctor()

    self.frameTimeCount = 0

    -- 注册帧事件

    self:addNodeEventListener(cc.ENTER_FRAME_EVENT, handler(self, self.onEnterFrame))

    self:scheduleUpdate()

end

实际上，除了 C++ 回调 Lua 函数之外，在其他所有需要回调的地方都可以使用handler()。

Parameters

·        mixed obj Lua 对象

·        function method 对象方法

Returns

·        function

math.newrandomseed()

math.newrandomseed()

根据系统时间初始化随机数种子，让后续的 math.random() 返回更随机的值

math.round()

math.round(value)

对数值进行四舍五入，如果不是数值则返回 0

Parameters

·        number value 输入值

Returns

·        number

math.angle2radian()

math.angle2radian(angle)

角度转弧度

math.radian2angle()

math.radian2angle(radian)

弧度转角度

io.exists()

io.exists(path)

检查指定的文件或目录是否存在，如果存在返回 true，否则返回 false

可以使用 cc.FileUtils:fullPathForFilename() 函数查找特定文件的完整路径，例如：

local path = cc.FileUtils:getInstance():fullPathForFilename("gamedata.txt")

if io.exists(path) then

    ....

end

Parameters

·        string path 要检查的文件或目录的完全路径

Returns

·        boolean

io.readfile()

io.readfile(path)

读取文件内容，返回包含文件内容的字符串，如果失败返回 nil

io.readfile() 会一次性读取整个文件的内容，并返回一个字符串，因此该函数不适宜读取太大的文件。

Parameters

·        string path 文件完全路径

Returns

·        string

io.writefile()

io.writefile(path, content, mode)

以字符串内容写入文件，成功返回 true，失败返回 false

"mode 写入模式" 参数决定io.writefile() 如何写入内容，可用的值如下：

·        "w+" : 覆盖文件已有内容，如果文件不存在则创建新文件

·        "a+" : 追加内容到文件尾部，如果文件不存在则创建文件

此外，还可以在 "写入模式" 参数最后追加字符"b" ，表示以二进制方式写入数据，这样可以避免内容写入不完整。

Android 特别提示: 在 Android 平台上，文件只能写入存储卡所在路径，assets 和 data等目录都是无法写入的。

Parameters

·        string path 文件完全路径

·        string content 要写入的内容

·        [string mode] 写入模式，默认值为 "w+b"

Returns

·        boolean

io.pathinfo()

io.pathinfo(path)

拆分一个路径字符串，返回组成路径的各个部分

local pathinfo  = io.pathinfo("/var/app/test/abc.png")

-- 结果:

-- pathinfo.dirname  = "/var/app/test/"

-- pathinfo.filename = "abc.png"

-- pathinfo.basename = "abc"

-- pathinfo.extname  = ".png"

Parameters

·        string path 要分拆的路径字符串

Returns

·        table

io.filesize()

io.filesize(path)

返回指定文件的大小，如果失败返回 false

Parameters

·        string path 文件完全路径

Returns

·        integer

table.nums()

table.nums(t)

计算表格包含的字段数量

Lua table 的 "#" 操作只对依次排序的数值下标数组有效，table.nums() 则计算 table 中所有不为 nil 的值的个数。

Parameters

·        table t 要检查的表格

Returns

·        integer

table.keys()

table.keys(hashtable)

返回指定表格中的所有键

local hashtable = {a = 1, b = 2, c = 3}

local keys = table.keys(hashtable)

-- keys = {"a", "b", "c"}

Parameters

·        table hashtable 要检查的表格

Returns

·        table

table.values()

table.values(hashtable)

返回指定表格中的所有值

local hashtable = {a = 1, b = 2, c = 3}

local values = table.values(hashtable)

-- values = {1, 2, 3}

Parameters

·        table hashtable 要检查的表格

Returns

·        table

table.merge()

table.merge(dest, src)

将来源表格中所有键及其值复制到目标表格对象中，如果存在同名键，则覆盖其值

local dest = {a = 1, b = 2}

local src  = {c = 3, d = 4}

table.merge(dest, src)

-- dest = {a = 1, b = 2, c = 3, d = 4}

Parameters

·        table dest 目标表格

·        table src 来源表格

table.insertto()

table.insertto(dest, src, begin)

在目标表格的指定位置插入来源表格，如果没有指定位置则连接两个表格

local dest = {1, 2, 3}

local src  = {4, 5, 6}

table.insertto(dest, src)

-- dest = {1, 2, 3, 4, 5, 6}

dest = {1, 2, 3}

table.insertto(dest, src, 5)

-- dest = {1, 2, 3, nil, 4, 5, 6}

Parameters

·        table dest 目标表格

·        table src 来源表格

·        [integer begin] 插入位置

table.indexof()

table.indexof(array, value, begin)

从表格中查找指定值，返回其索引，如果没找到返回 false

local array = {"a", "b", "c"}

print(table.indexof(array, "b")) -- 输出 2

Parameters

·        table array 表格

·        mixed value 要查找的值

·        [integer begin] 起始索引值

Returns

·        integer

table.keyof()

table.keyof(hashtable, value)

从表格中查找指定值，返回其 key，如果没找到返回 nil

local hashtable = {name = "dualface", comp = "chukong"}

print(table.keyof(hashtable, "chukong")) -- 输出 comp

Parameters

·        table hashtable 表格

·        mixed value 要查找的值

Returns

·        string 该值对应的 key

table.removebyvalue()

table.removebyvalue(array, value, removeall)

从表格中删除指定值，返回删除的值的个数

local array = {"a", "b", "c", "c"}

print(table.removebyvalue(array, "c", true)) -- 输出 2

Parameters

·        table array 表格

·        mixed value 要删除的值

·        [boolean removeall] 是否删除所有相同的值

Returns

·        integer

table.map()

table.map(t, fn)

对表格中每一个值执行一次指定的函数，并用函数返回值更新表格内容

local t = {name = "dualface", comp = "chukong"}

table.map(t, function(v, k)

    -- 在每一个值前后添加括号

    return "[" .. v .. "]"

end)

-- 输出修改后的表格内容

for k, v in pairs(t) do

    print(k, v)

end

-- 输出

-- name [dualface]

-- comp [chukong]

fn 参数指定的函数具有两个参数，并且返回一个值。原型如下：

function map_function(value, key)

    return value

end

Parameters

·        table t 表格

·        function fn 函数

table.walk()

table.walk(t, fn)

对表格中每一个值执行一次指定的函数，但不改变表格内容

local t = {name = "dualface", comp = "chukong"}

table.walk(t, function(v, k)

    -- 输出每一个值

    print(v)

end)

fn 参数指定的函数具有两个参数，没有返回值。原型如下：

function map_function(value, key)

end

Parameters

·        table t 表格

·        function fn 函数

table.filter()

table.filter(t, fn)

对表格中每一个值执行一次指定的函数，如果该函数返回 false，则对应的值会从表格中删除

local t = {name = "dualface", comp = "chukong"}

table.filter(t, function(v, k)

    return v ~= "dualface" -- 当值等于 dualface 时过滤掉该值

end)

-- 输出修改后的表格内容

for k, v in pairs(t) do

    print(k, v)

end

-- 输出

-- comp chukong

fn 参数指定的函数具有两个参数，并且返回一个 boolean 值。原型如下：

function map_function(value, key)

    return true or false

end

Parameters

·        table t 表格

·        function fn 函数

table.unique()

table.unique(t)

遍历表格，确保其中的值唯一

local t = {"a", "a", "b", "c"} -- 重复的 a 会被过滤掉

local n = table.unique(t)

for k, v in pairs(n) do

    print(v)

end

-- 输出

-- a

-- b

-- c

Parameters

·        table t 表格

Returns

·        table 包含所有唯一值的新表格

string.htmlspecialchars()

string.htmlspecialchars(input)

将特殊字符转为 HTML 转义符

print(string.htmlspecialchars("<ABC>"))

-- 输出 <ABC>

Parameters

·        string input 输入字符串

Returns

·        string 转换结果

string.restorehtmlspecialchars()

string.restorehtmlspecialchars(input)

将 HTML转义符还原为特殊字符，功能与 string.htmlspecialchars() 正好相反

print(string.restorehtmlspecialchars("<ABC>"))

-- 输出 <ABC>

Parameters

·        string input 输入字符串

Returns

·        string 转换结果

string.nl2br()

string.nl2br(input)

将字符串中的 \n 换行符转换为 HTML 标记

print(string.nl2br("Hello\nWorld"))

-- 输出

-- Hello<br />World

Parameters

·        string input 输入字符串

Returns

·        string 转换结果

string.text2html()

string.text2html(input)

将字符串中的特殊字符和 \n 换行符转换为 HTML 转移符和标记

print(string.nl2br("<Hello>\nWorld"))

-- 输出

-- &lt;Hello&gt;<br />World

Parameters

·        string input 输入字符串

Returns

·        string 转换结果

string.split()

string.split(input, delimiter)

用指定字符或字符串分割输入字符串，返回包含分割结果的数组

local input = "Hello,World"

local res = string.split(input, ",")

-- res = {"Hello", "World"}

local input = "Hello-+-World-+-Quick"

local res = string.split(input, "-+-")

-- res = {"Hello", "World", "Quick"}

Parameters

·        string input 输入字符串

·        string delimiter 分割标记字符或字符串

Returns

·        array 包含分割结果的数组

string.ltrim()

string.ltrim(input)

去除输入字符串头部的空白字符，返回结果

local input = "  ABC"

print(string.ltrim(input))

-- 输出 ABC，输入字符串前面的两个空格被去掉了

空白字符包括：

·        空格

·        制表符 \t

·        换行符 \n

·        回到行首符 \r

Parameters

·        string input 输入字符串

Returns

·        string 结果

@see string.rtrim, string.trim

string.rtrim()

string.rtrim(input)

去除输入字符串尾部的空白字符，返回结果

local input = "ABC  "

print(string.ltrim(input))

-- 输出 ABC，输入字符串最后的两个空格被去掉了

Parameters

·        string input 输入字符串

Returns

·        string 结果

@see string.ltrim, string.trim

string.trim()

string.trim(input)

去掉字符串首尾的空白字符，返回结果

Parameters

·        string input 输入字符串

Returns

·        string 结果

@see string.ltrim, string.rtrim

string.ucfirst()

string.ucfirst(input)

将字符串的第一个字符转为大写，返回结果

local input = "hello"

print(string.ucfirst(input))

-- 输出 Hello

Parameters

·        string input 输入字符串

Returns

·        string 结果

string.urlencode()

string.urlencode(input)

将字符串转换为符合 URL 传递要求的格式，并返回转换结果

local input = "hello world"

print(string.urlencode(input))

-- 输出

-- hello%20world

Parameters

·        string input 输入字符串

Returns

·        string 转换后的结果

@see string.urldecode

string.urldecode()

string.urldecode(input)

将 URL 中的特殊字符还原，并返回结果

local input = "hello%20world"

print(string.urldecode(input))

-- 输出

-- hello world

Parameters

·        string input 输入字符串

Returns

·        string 转换后的结果

@see string.urlencode

string.utf8len()

string.utf8len(input)

计算 UTF8 字符串的长度，每一个中文算一个字符

local input = "你好World"

print(string.utf8len(input))

-- 输出 7

Parameters

·        string input 输入字符串

Returns

·        integer 长度

string.formatnumberthousands()

string.formatnumberthousands(num)

将数值格式化为包含千分位分隔符的字符串

print(string.formatnumberthousands(1924235))

-- 输出 1,924,235

Parameters

·        number num 数值

Returns

·        string 格式化结果

Functions

device.showActivityIndicator()

device.showActivityIndicator()

显示活动指示器

在 iOS 和Android 设备上显示系统的活动指示器，可以用于阻塞操作时通知用户需要等待。

device.hideActivityIndicator()

device.hideActivityIndicator()

隐藏正在显示的活动指示器

device.showAlert()

device.showAlert(title, message, buttonLabels, listener)

显示一个包含按钮的弹出对话框

local function onButtonClicked(event)

    if event.buttonIndex == 1 then

        .... 玩家选择了 YES 按钮

    else

        .... 玩家选择了 NO 按钮

    end

end

device.showAlert("Confirm Exit", "Are you sure exit game ?", {"YES", "NO"}, onButtonClicked)

当没有指定按钮标题时，对话框会默认显示一个“OK”按钮。 回调函数获得的表格中，buttonIndex 指示玩家选择了哪一个按钮，其值是按钮的显示顺序。

Parameters

·        string title 对话框标题

·        string message 内容

·        table buttonLabels 包含多个按钮标题的表格对象

·        function listener 回调函数

device.cancelAlert()

device.cancelAlert()

取消正在显示的对话框。

提示：取消对话框，不会执行显示对话框时指定的回调函数。

device.getOpenUDID()

device.getOpenUDID()

返回设备的 OpenUDID 值

OpenUDID 是为设备仿造的 UDID（唯一设备识别码），可以用来识别用户的设备。

但OpenUDID 存在下列问题：

·        如果删除了应用再重新安装，获得的 OpenUDID 会发生变化

·        iOS 7 不支持 OpenUDID

Returns

·        string 设备的 OpenUDID 值

device.openURL()

device.openURL(url)

用浏览器打开指定的网址

-- 打开网页

device.openURL("http://dualface.github.com/quick-cocos2d-x/")

-- 打开设备上的邮件程序，并创建新邮件，填入收件人地址

device.openURL("mailto:nobody@mycompany.com")

-- 增加主题和内容

local subject = string.urlencode("Hello")

local body = string.urlencode("How are you ?")

device.openURL(string.format("mailto:nobody@mycompany.com?subject=%s&body=%s", subject, body))

-- 打开设备上的拨号程序

device.openURL("tel:123-456-7890")

Parameters

·        string 网址，邮件，拨号等的字符串

device.showInputBox()

device.showInputBox(title, message, defaultValue)

显示一个输入框，并返回用户输入的内容。

当用户点击取消按钮时，showInputBox() 函数返回空字符串。

Parameters

·        string title 对话框标题

·        string message 提示信息

·        string defaultValue 输入框默认值

Returns

·        string 用户输入的字符串