Cheese

Appearance

中文UI相关 ​

javascript
const core = require('cheese-js');
lua
local core = require('cheese-lua')

入门路线（建议按顺序） ​

如果你是第一次用中文UI，推荐按这个顺序看：

  1. 先看 最小可运行示例（先跑通），目标是先把窗口打开并收到回调。
  2. 再看 先看这 4 条（新手必读），避免一上来就踩坑。
  3. 然后看 打开UI: open(...)，把事件判断和字段读取方法用起来。
  4. 最后按需查 控件详解 和下面的 API 列表（getTextValue、setChecked、saveConfig 等）。

最小可运行示例（先跑通） ​

先验证三件事：能打开窗口、点按钮能读到输入框内容、能通过关闭回调处理关闭事件。

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;

const ui = `
{
  控件: '窗口',
  标题: '快速开始',
  子: [
    { 控件: '标签页', 标题: '第一页', 子: [
      { 控件: '输入框', id: 'input1', 默认值: 'hello' },
      { 控件: '按钮', id: 'btn1', 标题: '点我' }
    ] }
  ]
}
`;

const handle = chineseui.open(ui, "demo.config", (event) => {
  if (chineseui.isWindowLoaded(event)) {
    console.log("窗口已加载:", chineseui.getUiHandle(event));
  } else if (chineseui.isControlClicked(event)) {
    const id = chineseui.getControlId(event);
    if (String(id) === "btn1") {
      // 点按钮后读取输入框内容
      console.log("输入框值:", chineseui.getTextValue(handle, 0, "input1"));
    }
  } else if (chineseui.isWindowCloseRequested(event)) {
    console.log("关闭请求");
    chineseui.close(chineseui.getUiHandle(event));
  }
});

console.log("handle =", handle);
lua
local core = require('cheese-lua')
local chineseui = core.chineseui

local ui = [[
{
  控件: '窗口',
  标题: '快速开始',
  子: [
    { 控件: '标签页', 标题: '第一页', 子: [
      { 控件: '输入框', id: 'input1', 默认值: 'hello' },
      { 控件: '按钮', id: 'btn1', 标题: '点我' }
    ] }
  ]
}
]]

local handle = chineseui.open(ui, "demo.config", function(self, event)
    local e = event or self
    if chineseui.isWindowLoaded(e) then
        print("窗口已加载:" .. tostring(chineseui.getUiHandle(e)))
    elseif chineseui.isControlClicked(e) then
        local id = chineseui.getControlId(e)
        if id == "btn1" then
            -- 点按钮后读取输入框内容
            local uiHandle = chineseui.getUiHandle(e)
            print("输入框值:" .. tostring(chineseui.getTextValue(uiHandle, 0, "input1")))
        end
    elseif chineseui.isWindowCloseRequested(e) then
        print("关闭请求")
        chineseui.close(chineseui.getUiHandle(e))
    end
end)

print("handle =", handle)

文档怎么查（按场景） ​

  • 只想先跑起来：看 最小可运行示例（先跑通） + 打开UI: open(...)。
  • 想知道 UI JSON 怎么写：看 控件名与别名、通用属性、控件详解。
  • 想做事件交互：看 事件判断辅助方法 + 事件字段读取辅助方法。
  • 想改控件状态：从 getTextValue/setTextValue、setChecked、setEnabled、setVisible 开始。
  • 想持久化配置：看 saveConfig/loadConfig。

先看这 4 条（新手必读） ​

  • open(ui, ...) 的 ui 必须是字符串（JSON/JSON5 风格），不能直接传 Lua table / JS object。
  • 根节点类型必须是 控件: '窗口'，否则 open 会返回 -1。
  • 子节点字段建议统一写 子（实现也兼容 子节点，但不建议混用）。
  • 对外 API（如 getTextValue、setChecked）依赖 id 定位控件，交互控件请务必加 id。

尺寸怎么写（先记结论） ​

  • 宽度: -1（铺满）：占满父容器可用宽度；高度: -1 同理，占满父容器可用高度。
  • 宽度/高度: -2（包裹）：大小跟内容走，内容多就变大，内容少就变小。
  • 宽度/高度: 正数：按像素处理，例如 宽度: 320、高度: 80。
  • 容器控件（水平布局、垂直布局）写 高度: 200 时，不一定真的就是 200；它更像“参考值”，最终高度还会受子控件影响。
  • 输入类控件（输入框、下拉框）写 高度: 80 的意思是“至少 80”，如果内容或样式需要更高，实际高度可能大于 80。

实现规则速查（进阶） ​

规则项实际行为示例
尺寸解析-1 = 铺满父容器，-2 = 按内容包裹；其他按整数解析，非法则按未设置处理。宽度: -1
高度特殊行为容器（行/列）正数高度不会强制固定；输入框/下拉框正数高度按“最小高度”处理。高度: 80
边距解析支持 1/2/4 段：8=上右下左全 8；8,4=左右 8、上下 4；8,4,8,4=左上右下。边距: '8,8,8,8'
布尔解析支持 true/false、1/0、yes/no、是/否、开/关、开启/关闭。显示标题栏: false
文字大小小于等于 0 或非法值时回退默认值。文字大小: 16
颜色解析支持 #AARRGGBB，解析失败时回退为透明色。背景: '#ffffffff'
输入类型0 文本、1 数字、2 密码；其他值回退为 0。输入类型: 1
URL 规范化支持 http/https/file/javascript；普通路径（含以 / 开头）会按 WebView 搜索路径查找；若是系统绝对路径（如 /sdcard/ui/index.html）可直接按本地文件加载。链接: 'page/index.html'

控件名与别名（类型字段） ​

主类型名兼容别名
窗口无
标签页tab、Tab
水平布局row、Row、横向布局
垂直布局column、Column、纵向布局
文本框text、Text、标签
输入框input、Input、编辑框
按钮button、Button
下拉框spinner、select、Select
多选框checkbox、CheckBox、check
单选框radio、RadioGroup
浏览器webview、browser、WebView

通用属性（大多数控件都支持） ​

属性别名类型默认值说明示例
idIDstring空控件唯一标识，建议全局唯一。id: 'idButton'
宽度widthint未设置-1 占满父容器宽度；-2 按内容包裹；正数按像素。宽度: -1
高度heightint未设置-1 占满父容器高度；-2 按内容包裹；正数按像素（容器/输入类有特殊行为，见上方规则表）。高度: 80
边距marginstring0,0,0,0支持 1/2/4 段：8=四边相同；8,4=左右 8 上下 4；8,4,8,4=左上右下。边距: '8,4,8,4'

控件详解 ​

窗口 ​

用途：根容器，管理标题栏和页签外观。

属性别名类型默认值说明示例
标题titlestring窗口标题窗口顶部标题文本。标题: 'Demo2'
显示标题栏showTitleBarbooleantrue是否显示顶部标题栏。显示标题栏: false
标签头高度tabHeaderHeightint未设置页签头高度。标签头高度: 40
标签头背景tabHeaderBackgroundcolor#ffffffff页签头背景色。标签头背景: '#ffffffff'
标签头字体大小tabTextSizefloat16页签标题字号。标签头字体大小: 16
标签头选中字体颜色tabSelectedColorcolor#2f6bff选中页签文字颜色。标签头选中字体颜色: '#ffff3377'
标签头字体默认颜色tabDefaultColorcolor#4c7dff未选中页签文字颜色。标签头字体默认颜色: '#ff3355ff'
子子节点array[]窗口下的子控件列表，可放 标签页 和普通控件。子: [{ 控件: '标签页', 标题: '第一页', 子: [] }]
配置文件configNamestringmain.configopen(ui, configName) 第二参数优先；未传时使用该字段。相对路径会从 UI 目录查找，绝对路径按原路径读取。配置文件: 'demo.config'
json5
{ 控件: '窗口', 标题: 'Demo2', 显示标题栏: false, 子: [] }
配置文件路径解析规则（重点） ​
  • 默认值：main.config。
  • open(ui, configName) 第二参数优先；如果没传，使用窗口里的 配置文件/configName 字段。
  • 相对路径（如 demo.config 或 cfg/demo.config）：按配置搜索路径依次查找。
  • 绝对路径（如 /sdcard/cheese/demo.config）：按原路径读写。
  • saveConfig / loadConfig 与 open 使用同一套路径规则。
  • 默认配置搜索路径顺序：UI目录 -> assets目录 -> 当前目录。
  • 可通过 setConfigSearchPaths(...)、addConfigSearchPath(path)、getConfigSearchPaths() 自定义。

标签页 ​

用途：多个页面切换显示。

属性别名类型默认值说明示例
标题titlestring标签页页签显示名称。标题: '第一页'
背景backgroundcolor#ffffffff当前页背景色。背景: '#ffffffff'
子子节点array[]该标签页下的子控件列表（每一项仍是普通控件对象）。子: [{ 控件: '文本框', 默认值: '第一页内容' }]
json5
{
  控件: '窗口',
  子: [
    { 控件: '标签页', 标题: '第一页', 子: [{ 控件: '文本框', 默认值: '第一页内容' }] },
    { 控件: '标签页', 标题: '第二页', 子: [{ 控件: '文本框', 默认值: '第二页内容' }] }
  ]
}

垂直布局 ​

用途：子控件从上到下排列。

属性别名类型默认值说明示例
对齐alignstring空支持 居中、右对齐，其他值按左对齐处理。对齐: '居中'
背景backgroundcolor#00000000布局背景色。背景: '#ffffffff'
子子节点array[]垂直布局下的子控件列表（从上到下排列）。子: [{ 控件: '文本框', 默认值: '标题' }]
json5
{ 控件: '垂直布局', 子: [{ 控件: '文本框', 默认值: '标题' }, { 控件: '输入框', id: 'input1' }] }

水平布局 ​

用途：子控件从左到右排列。

属性别名类型默认值说明示例
对齐alignstring空支持 居中、右对齐，其他值按左对齐处理。对齐: '居中'
背景backgroundcolor#00000000布局背景色。背景: '#ffffffff'
子子节点array[]水平布局下的子控件列表（从左到右排列）。子: [{ 控件: '按钮', 标题: '确定' }]
json5
{ 控件: '水平布局', 子: [{ 控件: '按钮', 标题: '确定' }, { 控件: '按钮', 标题: '取消' }] }

文本框 ​

用途：展示静态文本。

属性别名类型默认值说明示例
默认值文本 / text / valuestring空初始文本内容。默认值: '显示内容'
文字大小textSize / 字体大小float14文本字号。文字大小: 16
json5
{ 控件: '文本框', id: 'idText', 默认值: '显示内容', 文字大小: 16 }

输入框 ​

用途：接收用户输入。

属性别名类型默认值说明示例
默认值文本 / text / valuestring空初始输入内容。默认值: '输入内容'
输入类型inputTypeint00文本/1数字/2密码。输入类型: 1
文字大小textSize / 字体大小float14文本字号。文字大小: 16
json5
{ 控件: '输入框', id: 'idEdit1', 输入类型: 0, 默认值: '输入内容', 文字大小: 16 }

按钮 ​

用途：触发点击事件。

属性别名类型默认值说明示例
标题titlestring按钮按钮显示文案。标题: '点击我'
json5
{ 控件: '按钮', id: 'idButton', 标题: '点击我' }

多选框 ​

用途：布尔开关（选中/未选中）。

属性别名类型默认值说明示例
选中checkedbooleanfalse初始是否勾选。选中: false
文本title / textstring空勾选项显示文案。文本: '选项1'
json5
{ 控件: '多选框', id: 'idCheckbox', 选中: false, 文本: '选项1' }

下拉框 ​

用途：候选项单选。

属性别名类型默认值说明示例
默认值defaultIndex / selectedIndexint0默认选中索引。默认值: 0
选项optionsarray/string/object空支持数组、逗号/竖线分隔字符串、对象数组（取 文本/标题/值/名称）、对象映射。选项: ['选项1', '选项2']
json5
{ 控件: '下拉框', id: 'idSelect1', 默认值: 0, 选项: ['选项1', '选项2', '选项3'] }

单选框 ​

用途：多项中选一项。

属性别名类型默认值说明示例
默认值defaultIndex / selectedIndexint0默认选中索引。默认值: 1
选项optionsarray/string/object空支持数组、逗号/竖线分隔字符串、对象数组（取 文本/标题/值/名称）、对象映射。选项: ['选项1', '选项2']
json5
{ 控件: '单选框', id: 'idRadiobox', 默认值: 1, 选项: ['选项1', '选项2', '选项3'] }

浏览器 ​

用途：WebView 页面容器。

属性别名类型默认值说明示例
链接url / srcstringhttp://www.baidu.com支持 http/https/file/javascript。普通路径（含 /a/b.html）会按 WebView 搜索路径查找；系统绝对路径（如 /sdcard/ui/index.html）可直接加载本地文件。链接: 'https://www.baidu.com'
json5
{ 控件: '浏览器', id: 'idWebView', 宽度: -1, 高度: 260, 链接: 'https://www.baidu.com' }
浏览器链接路径解析规则（重点） ​
  • http:// / https:// / file:// / javascript:：按原值直接使用。
  • 系统绝对路径（如 /sdcard/ui/index.html）：按本地文件加载。
  • 普通路径（如 page/index.html，以及 /page/index.html 这种写法）：会在 WebView 搜索路径中依次查找。
  • 默认搜索路径：UI目录、主目录、当前工作目录。
  • 你可以用 setWebViewSearchPaths(...) 完全重设搜索路径，或用 addWebViewSearchPath(path) 追加路径。
路径示例（推荐写法） ​
javascript
const core = require('cheese-js');
const chineseui = core.chineseui;

// 1) 网络地址
const url1 = "https://www.baidu.com";
// 2) 本地 file 协议（最明确）
const url2 = "file:///sdcard/ui/index.html";
// 3) 普通相对路径（会走搜索路径）
const url3 = "web/index.html";

chineseui.setWebViewSearchPaths("/sdcard/ui", "/sdcard/web");
lua
local core = require('cheese-lua')
local chineseui = core.chineseui

local url1 = "https://www.baidu.com"
local url2 = "file:///sdcard/ui/index.html"
local url3 = "web/index.html"

chineseui.setWebViewSearchPaths("/sdcard/ui", "/sdcard/web")

新手常见坑（排错先看这里） ​

  • open 返回 -1：ui 不是字符串，或根节点不是 控件: '窗口'。
  • API 找不到控件：控件未设置 id，或操作时 pageIndex 不正确。
  • WebView 打不开：优先检查 链接 的协议、路径是否正确。

打开UI: open(ui: string, configNameOrCallback?: string | Function, callback?: Function): number ✅ ​

参数:

  • ?string (ui): UI配置字符串（JSON/JSON5风格，建议多行字符串传入）
  • string (configName): 配置名（可选）。相对路径按配置搜索路径依次查找；绝对路径按原路径读取。
  • Function (callback): 事件回调（可选，桥接层支持）

返回值:

  • 🟢number: UI句柄

回调事件类型 ​

用于描述 callback(event) 里收到的事件对象类型：

  • WindowLoaded: 窗口加载完成
  • ControlClicked: 控件被点击（如按钮、单选框、多选框）
  • ControlCheckedChanged: 多选框选中状态变化
  • ControlSelectionChanged: 下拉框/单选框选中项变化
  • WebViewMessage: WebView 向脚本层发送消息
  • WindowCloseRequested: 点击返回键触发关闭请求

事件判断辅助方法 ​

窗口加载判断: isWindowLoaded(event): boolean ​

说明：判断当前事件是否为 WindowLoaded，也就是页面是否已经完全加载完毕（UI 已经显示，可以开始做初始化操作）。

javascript
if (chineseui.isWindowLoaded(event)) {
  console.log("loaded");
}
lua
if chineseui.isWindowLoaded(event) then
    print("loaded")
end
窗口关闭请求判断: isWindowCloseRequested(event): boolean ​

说明：判断当前事件是否为 WindowCloseRequested，通常在用户点击“继续/退出”按钮或按返回键准备关闭窗口时触发。

javascript
if (chineseui.isWindowCloseRequested(event)) {
  console.log("close requested");
}
lua
if chineseui.isWindowCloseRequested(event) then
    print("close requested")
end
点击事件判断: isControlClicked(event): boolean ​

说明：判断当前事件是否为控件点击事件，常用于按钮、多选框、单选框等可点击控件。

javascript
if (chineseui.isControlClicked(event)) {
  console.log(chineseui.getControlId(event));
}
lua
if chineseui.isControlClicked(event) then
    print(chineseui.getControlId(event))
end
多选框事件判断: isControlCheckedChanged(event): boolean ​

说明：判断当前事件是否为多选框状态变化事件，即“勾选/取消勾选”时触发。

javascript
if (chineseui.isControlCheckedChanged(event)) {
  console.log(chineseui.getChecked(event));
}
lua
if chineseui.isControlCheckedChanged(event) then
    print(chineseui.getChecked(event))
end
选项变化事件判断: isControlSelectionChanged(event): boolean ​

说明：判断当前事件是否为下拉框/单选框选中项变化事件，用户切换选项时触发。

javascript
if (chineseui.isControlSelectionChanged(event)) {
  console.log(chineseui.getEventSelectedIndex(event));
}
lua
if chineseui.isControlSelectionChanged(event) then
    print(chineseui.getEventSelectedIndex(event))
end
WebView消息事件判断: isWebViewMessage(event): boolean ​

说明：判断当前事件是否为 WebView 消息事件，当前端页面通过桥接把消息发回脚本层时触发。

javascript
if (chineseui.isWebViewMessage(event)) {
  console.log(chineseui.getPayload(event));
}
lua
if chineseui.isWebViewMessage(event) then
    print(chineseui.getPayload(event))
end

事件字段读取辅助方法 ​

获取事件类型: getEventType(event): string ​

说明：返回事件类型字符串（如 ControlClicked）。

javascript
console.log(chineseui.getEventType(event));
lua
print(chineseui.getEventType(event))
获取UI句柄: getUiHandle(event): number ​

说明：返回当前事件所属 UI 句柄。

javascript
console.log(chineseui.getUiHandle(event));
lua
print(chineseui.getUiHandle(event))
获取页索引: getPageIndex(event): number ​

说明：返回事件关联的标签页索引。

javascript
console.log(chineseui.getPageIndex(event));
lua
print(chineseui.getPageIndex(event))
获取控件ID: getControlId(event): string ​

说明：返回事件关联控件 ID。

javascript
console.log(chineseui.getControlId(event));
lua
print(chineseui.getControlId(event))
获取多选状态: getChecked(event): boolean ​

说明：返回多选框事件的选中状态。

javascript
console.log(chineseui.getChecked(event));
lua
print(chineseui.getChecked(event))
获取事件选中索引: getEventSelectedIndex(event): number ​

说明：返回选项变化事件中的选中索引。

javascript
console.log(chineseui.getEventSelectedIndex(event));
lua
print(chineseui.getEventSelectedIndex(event))
获取WebView控件ID: getWebViewId(event): string ​

说明：返回 WebView 消息事件里的控件 ID。

javascript
console.log(chineseui.getWebViewId(event));
lua
print(chineseui.getWebViewId(event))
获取WebView载荷: getPayload(event): string ​

说明：返回 WebView 消息载荷字符串。
这里的“载荷”就是前端页面调用 sendToLua(payload) / sendToJs(payload) 时传入的那个 payload 原始文本（通常是 JSON 字符串）。

前端页面发送示例（WebView 内 JS）：

javascript
// 发送给脚本层（payload 是字符串）
window.bridge.sendToLua(JSON.stringify({
  action: "login",
  user: "alice",
  ts: Date.now()
}));

// 或者
window.bridge.sendToJs("hello from webview");

脚本侧接收示例（JS）：

javascript
if (chineseui.isWebViewMessage(event)) {
  const raw = chineseui.getPayload(event);
  console.log("raw payload =", raw); // 例如: {"action":"login","user":"alice","ts":1710000000000}
  try {
    const data = JSON.parse(String(raw));
    console.log("action =", data.action, "user =", data.user);
  } catch (_e) {
    console.log("非JSON消息:", raw);
  }
}
lua
if chineseui.isWebViewMessage(event) then
    local raw = chineseui.getPayload(event)
    print("raw payload =", raw) -- 例如: {"action":"login","user":"alice","ts":1710000000000}
    -- Lua 这里先拿到原始字符串，按你的项目习惯再决定是否做 JSON 解析
end

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
const ui = `
{
  控件: '窗口',
  标题: '示例',
  子: [
    {
      控件: '标签页',
      标题: 'demo',
      子: [
        { 控件: '文本框', id: 'txt1', 默认值: 'hello' },
        { 控件: '按钮', id: 'btn1', 标题: '点我' },
        { 控件: '多选框', id: 'check1', 文本: '选项1', 选中: false },
        { 控件: '下拉框', id: 'select1', 默认值: 0, 选项: ['A', 'B', 'C'] }
      ]
    }
  ]
}
`;
const handle = chineseui.open(ui, "demo_config", (event) => {
  if (chineseui.isWindowLoaded(event)) {
    console.log("窗口加载完成, handle =", chineseui.getUiHandle(event));
  } else if (chineseui.isControlClicked(event)) {
    console.log("点击事件:", chineseui.getPageIndex(event), chineseui.getControlId(event));
    if (String(chineseui.getControlId(event)) === "btn1") {
      console.log("按钮 btn1 被点击");
    }
  } else if (chineseui.isControlCheckedChanged(event)) {
    console.log("多选框变化:", chineseui.getControlId(event), chineseui.getChecked(event));
  } else if (chineseui.isControlSelectionChanged(event)) {
    console.log("选项变化:", chineseui.getControlId(event), chineseui.getEventSelectedIndex(event));
  } else if (chineseui.isWindowCloseRequested(event)) {
    console.log("关闭请求");
    chineseui.close(chineseui.getUiHandle(event));
  } else if (chineseui.isWebViewMessage(event)) {
    console.log("webview消息:", chineseui.getWebViewId(event), chineseui.getPayload(event));
  } else {
    console.log("其他事件:", chineseui.getEventType(event));
  }
});
console.log(handle);
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
local ui = [[
{
  控件: '窗口',
  标题: '示例',
  子: [
    {
      控件: '标签页',
      标题: 'demo',
      子: [
        { 控件: '文本框', id: 'txt1', 默认值: 'hello' },
        { 控件: '按钮', id: 'btn1', 标题: '点我' },
        { 控件: '多选框', id: 'check1', 文本: '选项1', 选中: false },
        { 控件: '下拉框', id: 'select1', 默认值: 0, 选项: ['A', 'B', 'C'] }
      ]
    }
  ]
}
]]
local handle = chineseui.open(ui, "demo_config", function(self, event)
    local e = event or self
    if chineseui.isWindowLoaded(e) then
        print("窗口加载完成, handle=" .. tostring(chineseui.getUiHandle(e)))
    elseif chineseui.isControlClicked(e) then
        print("点击事件: page=" .. tostring(chineseui.getPageIndex(e)) .. ", id=" .. tostring(chineseui.getControlId(e)))
        if tostring(chineseui.getControlId(e)) == "btn1" then
            print("按钮 btn1 被点击")
        end
    elseif chineseui.isControlCheckedChanged(e) then
        print("多选框变化: id=" .. tostring(chineseui.getControlId(e)) .. ", checked=" .. tostring(chineseui.getChecked(e)))
    elseif chineseui.isControlSelectionChanged(e) then
        print("选项变化: id=" .. tostring(chineseui.getControlId(e)) .. ", index=" .. tostring(chineseui.getEventSelectedIndex(e)))
    elseif chineseui.isWindowCloseRequested(e) then
        print("关闭请求")
        chineseui.close(chineseui.getUiHandle(e))
    elseif chineseui.isWebViewMessage(e) then
        print("webview消息: id=" .. tostring(chineseui.getWebViewId(e)) .. ", payload=" .. tostring(chineseui.getPayload(e)))
    else
        print("其他事件:" .. tostring(chineseui.getEventType(e)))
    end
end)
print(handle)

关闭UI: close(handle: number): boolean ✅ ​

参数:

  • ?number (handle): UI句柄

返回值:

  • 🟢boolean: 执行结果

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
const ui = `{ 控件: '窗口', 标题: 'demo', 子: [{ 控件: '标签页', 标题: '第一页', 子: [] }] }`;
const handle = chineseui.open(ui);
console.log(chineseui.close(handle));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
local ui = [[{ 控件: '窗口', 标题: 'demo', 子: [{ 控件: '标签页', 标题: '第一页', 子: [] }] }]]
local handle = chineseui.open(ui)
print(chineseui.close(handle))

关闭会话: closeSession(handle: number, saveConfig?: boolean): boolean ✅ ​

参数:

  • ?number (handle): UI句柄
  • boolean (saveConfig): 是否保存配置

返回值:

  • 🟢boolean: 执行结果

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
const ui = `{ 控件: '窗口', 标题: 'demo', 子: [{ 控件: '标签页', 标题: '第一页', 子: [] }] }`;
const handle = chineseui.open(ui);
console.log(chineseui.closeSession(handle, true));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
local ui = [[{ 控件: '窗口', 标题: 'demo', 子: [{ 控件: '标签页', 标题: '第一页', 子: [] }] }]]
local handle = chineseui.open(ui)
print(chineseui.closeSession(handle, true))

获取WebView地址: getWebViewUrl(handle: number, pageIndex: number, webViewId: string): string ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (webViewId): WebView控件ID

返回值:

  • 🟢string: 当前地址

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.getWebViewUrl(handle, 0, "web1"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.getWebViewUrl(handle, 0, "web1"))

设置WebView地址: setWebViewUrl(handle: number, pageIndex: number, webViewId: string, urlOrScript: string): boolean ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (webViewId): WebView控件ID
  • ?string (urlOrScript): URL或脚本

返回值:

  • 🟢boolean: 执行结果

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.setWebViewUrl(handle, 0, "web1", "https://example.com"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.setWebViewUrl(handle, 0, "web1", "https://example.com"))

获取下拉索引: getSelectedIndex(handle: number, pageIndex: number, idName: string): number ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (idName): 控件ID

返回值:

  • 🟢number: 索引值

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.getSelectedIndex(handle, 0, "spinner1"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.getSelectedIndex(handle, 0, "spinner1"))

获取下拉文本: getSelectedText(handle: number, pageIndex: number, idName: string): string ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (idName): 控件ID

返回值:

  • 🟢string: 选中文本

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.getSelectedText(handle, 0, "spinner1"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.getSelectedText(handle, 0, "spinner1"))

获取文本内容: getTextValue(handle: number, pageIndex: number, idName: string): string ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (idName): 控件ID

返回值:

  • 🟢string: 文本值

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.getTextValue(handle, 0, "input1"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.getTextValue(handle, 0, "input1"))

设置文本内容: setTextValue(handle: number, pageIndex: number, idName: string, text: string): boolean ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (idName): 控件ID
  • ?string (text): 文本内容

返回值:

  • 🟢boolean: 执行结果

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.setTextValue(handle, 0, "input1", "hello"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.setTextValue(handle, 0, "input1", "hello"))

设置下拉索引: setSelectedIndex(handle: number, pageIndex: number, idName: string, index: number): boolean ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (idName): 控件ID
  • ?number (index): 目标索引

返回值:

  • 🟢boolean: 执行结果

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.setSelectedIndex(handle, 0, "spinner1", 1));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.setSelectedIndex(handle, 0, "spinner1", 1))

设置选中状态: setChecked(handle: number, pageIndex: number, idName: string, selected: boolean): boolean ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (idName): 控件ID
  • ?boolean (selected): 是否选中

返回值:

  • 🟢boolean: 执行结果

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.setChecked(handle, 0, "check1", true));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.setChecked(handle, 0, "check1", true))

获取选中状态: isChecked(handle: number, pageIndex: number, idName: string): boolean ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (idName): 控件ID

返回值:

  • 🟢boolean: true
  • 🔴boolean: false

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.isChecked(handle, 0, "check1"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.isChecked(handle, 0, "check1"))

获取可用状态: isEnabled(handle: number, pageIndex: number, idName: string): boolean ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (idName): 控件ID

返回值:

  • 🟢boolean: true
  • 🔴boolean: false

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.isEnabled(handle, 0, "btn1"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.isEnabled(handle, 0, "btn1"))

设置可用状态: setEnabled(handle: number, pageIndex: number, idName: string, enable: boolean): boolean ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (idName): 控件ID
  • ?boolean (enable): 是否可用

返回值:

  • 🟢boolean: 执行结果

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.setEnabled(handle, 0, "btn1", true));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.setEnabled(handle, 0, "btn1", true))

获取可见状态: getVisibility(handle: number, pageIndex: number, idName: string): number ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (idName): 控件ID

返回值:

  • 🟢number: 可见状态值

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.getVisibility(handle, 0, "panel1"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.getVisibility(handle, 0, "panel1"))

设置可见状态: setVisible(handle: number, pageIndex: number, idName: string, visible: number): boolean ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (idName): 控件ID
  • ?number (visible): 可见状态值

返回值:

  • 🟢boolean: 执行结果

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.setVisible(handle, 0, "panel1", 0));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.setVisible(handle, 0, "panel1", 0))

设置文本颜色: setTextColor(handle: number, pageIndex: number, idName: string, textColor: string): boolean ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (idName): 控件ID
  • ?string (textColor): 颜色值

返回值:

  • 🟢boolean: 执行结果

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.setTextColor(handle, 0, "title1", "#FF0000"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.setTextColor(handle, 0, "title1", "#FF0000"))

设置背景颜色: setBackgroundColor(handle: number, pageIndex: number, idName: string, bg: string): boolean ✅ ​

参数:

  • ?number (handle): UI句柄
  • ?number (pageIndex): 页索引
  • ?string (idName): 控件ID
  • ?string (bg): 背景值

返回值:

  • 🟢boolean: 执行结果

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.setBackgroundColor(handle, 0, "panel1", "#FFFFFF"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.setBackgroundColor(handle, 0, "panel1", "#FFFFFF"))

保存配置: saveConfig(handle: number, configName?: string): boolean ✅ ​

说明：保存路径规则与 open(..., configName) 一致。相对路径优先写入配置搜索路径中的第一个目录；绝对路径写入指定文件。

参数:

  • ?number (handle): UI句柄
  • string (configName): 配置名。相对路径写入配置搜索路径第一个目录；绝对路径写入指定路径。

返回值:

  • 🟢boolean: 执行结果

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.saveConfig(handle, "demo_config"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.saveConfig(handle, "demo_config"))

加载配置: loadConfig(handle: number, configSource?: string): boolean ✅ ​

说明：参数看起来像路径时按文件读取（规则同 open(..., configName)，会按配置搜索路径依次查找）；否则按配置 JSON 字符串直接应用。

参数:

  • ?number (handle): UI句柄
  • string (configSource): 配置名、文件路径或配置 JSON 字符串。

返回值:

  • 🟢boolean: 执行结果

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.loadConfig(handle, "demo_config"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.loadConfig(handle, "demo_config"))

加载 JSON 字符串示例（含对应中文UI）:

下面这份 UI 里有 3 个可持久化控件：idEdit1、idCheckbox、idSelect1。
loadConfig 传入的 JSON 字符串需要按 page{索引} + 控件id 对应值来写。

json5
{
  控件: '窗口',
  子: [
    {
      控件: '标签页',
      标题: '第一页',
      子: [
        { 控件: '输入框', id: 'idEdit1', 默认值: '初始文本' },
        { 控件: '多选框', id: 'idCheckbox', 文本: '开启功能', 选中: false },
        { 控件: '下拉框', id: 'idSelect1', 默认值: 0, 选项: ['A', 'B', 'C'] }
      ]
    }
  ]
}
javascript
const core = require('cheese-js');
const chineseui = core.chineseui;

const configJson = JSON.stringify({
  page0: {
    idEdit1: "这是loadConfig加载后的文本",
    idCheckbox: "true",
    idSelect1: "2"
  }
});

console.log(chineseui.loadConfig(handle, configJson));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui

local configJson = [[
{
  "page0": {
    "idEdit1": "这是loadConfig加载后的文本",
    "idCheckbox": "true",
    "idSelect1": "2"
  }
}
]]

print(chineseui.loadConfig(handle, configJson))

多标签页示例（page0 / page1 同时写）:

下面 UI 有两个标签页：

  • page0：第一页，控件 idEdit1、idSelect1
  • page1：第二页，控件 idEdit2、idCheckbox2
json5
{
  控件: '窗口',
  子: [
    {
      控件: '标签页',
      标题: '第一页',
      子: [
        { 控件: '输入框', id: 'idEdit1', 默认值: 'page0-默认文本' },
        { 控件: '下拉框', id: 'idSelect1', 默认值: 0, 选项: ['A', 'B', 'C'] }
      ]
    },
    {
      控件: '标签页',
      标题: '第二页',
      子: [
        { 控件: '输入框', id: 'idEdit2', 默认值: 'page1-默认文本' },
        { 控件: '多选框', id: 'idCheckbox2', 文本: '第二页选项', 选中: false }
      ]
    }
  ]
}
javascript
const core = require('cheese-js');
const chineseui = core.chineseui;

const configJson = JSON.stringify({
  page0: {
    idEdit1: "第一页-加载后的文本",
    idSelect1: "2"
  },
  page1: {
    idEdit2: "第二页-加载后的文本",
    idCheckbox2: "true"
  }
});

console.log(chineseui.loadConfig(handle, configJson));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui

local configJson = [[
{
  "page0": {
    "idEdit1": "第一页-加载后的文本",
    "idSelect1": "2"
  },
  "page1": {
    "idEdit2": "第二页-加载后的文本",
    "idCheckbox2": "true"
  }
}
]]

print(chineseui.loadConfig(handle, configJson))

设置WebView搜索路径: setWebViewSearchPaths(...paths: string[]): void ✅ ​

说明：设置“普通路径/相对路径”查找目录。设置后会覆盖默认搜索路径。

参数:

  • ?string[] (...paths): 路径列表

返回值:

  • 🟢void: 设置完成

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.setWebViewSearchPaths("/sdcard/ui", "/sdcard/cache"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.setWebViewSearchPaths("/sdcard/ui", "/sdcard/cache"))

追加WebView搜索路径: addWebViewSearchPath(path: string): boolean ✅ ​

参数:

  • ?string (path): 路径

返回值:

  • 🟢boolean: 执行结果

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.addWebViewSearchPath("/sdcard/custom"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.addWebViewSearchPath("/sdcard/custom"))

获取WebView搜索路径: getWebViewSearchPaths(): string[] ✅ ​

返回值:

  • 🟢string[]: 路径集合

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.getWebViewSearchPaths());
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.getWebViewSearchPaths())

设置配置搜索路径: setConfigSearchPaths(...paths: string[]): void ✅ ​

说明：设置配置文件搜索路径（用于 open/saveConfig/loadConfig 的相对路径查找）。设置后会覆盖默认搜索路径。

参数:

  • ?string[] (...paths): 路径列表

返回值:

  • 🟢void: 设置完成

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
chineseui.setConfigSearchPaths("/sdcard/ui", "/sdcard/assets", "/sdcard/work");
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
chineseui.setConfigSearchPaths("/sdcard/ui", "/sdcard/assets", "/sdcard/work")

追加配置搜索路径: addConfigSearchPath(path: string): boolean ✅ ​

参数:

  • ?string (path): 路径

返回值:

  • 🟢boolean: 执行结果

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.addConfigSearchPath("/sdcard/custom_config"));
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.addConfigSearchPath("/sdcard/custom_config"))

获取配置搜索路径: getConfigSearchPaths(): string[] ✅ ​

返回值:

  • 🟢string[]: 路径集合

用法示例:

javascript
const core = require('cheese-js');
const chineseui = core.chineseui;
console.log(chineseui.getConfigSearchPaths());
lua
local core = require('cheese-lua')
local chineseui = core.chineseui
print(chineseui.getConfigSearchPaths())

Released under the GPL-3.0 License.

Copyright © 2022-present Cheese Team