Appearance
unison.cocosui — UI 系统
基于 Cocos2d-x 的 UI 系统，提供完整的 Widget 组件树和 CSB 文件加载。
使用方式
python
from unison import cocosui初始化与生命周期
python
# 初始化
cocosui.initialize()
# 设置设计分辨率
cocosui.set_design_resolution(1920, 1080)
# 每帧更新
cocosui.update(delta_time)
# 关闭
cocosui.shutdown()| 函数 | 说明 |
|---|---|
initialize() | 初始化 CocosUI 管理器 |
shutdown() | 关闭 CocosUI 管理器 |
is_initialized() | 是否已初始化 |
update(delta_time) | 每帧更新 |
set_design_resolution(width, height) | 设置设计分辨率 |
get_dpi_scale_x() | DPI 缩放因子 X |
get_dpi_scale_y() | DPI 缩放因子 Y |
Widget 基类
所有 UI 组件的基类。
属性/方法
| 方法 | 说明 |
|---|---|
get_id() | 获取组件 ID |
get_name() | 获取名称 |
get_type() | 获取类型 |
destroy() | 销毁组件 |
set_position(x, y) | 设置位置 |
get_position() | 获取位置 |
set_size(w, h) | 设置大小 |
get_size() | 获取大小 |
set_visible(v) | 设置可见性 |
is_visible() | 是否可见 |
set_color(r, g, b, a=1.0) | 设置颜色 |
set_rotation(angle) | 设置旋转角度 |
get_rotation() | 获取旋转角度 |
set_rotation_mode(mode) | 设置旋转模式 |
get_rotation_mode() | 获取旋转模式 |
set_enabled(e) | 设置启用状态 |
is_enabled() | 是否启用 |
add_child(widget) | 添加子组件 |
remove_child(widget) | 移除子组件 |
remove_all_children() | 移除所有子组件 |
工厂函数
create_button(name, x, y, width, height, text='')
python
btn = cocosui.create_button("start_btn", 100, 200, 200, 60, "开始游戏")create_text(name, x, y, font_size, text='')
python
label = cocosui.create_text("score", 10, 10, 24, "分数: 0")create_text_with_font(name, x, y, font_size, text, font_path)
python
label = cocosui.create_text_with_font("title", 100, 100, 48, "标题", "fonts/title.ttf")create_image(name, x, y, width, height, texture_path='')
python
img = cocosui.create_image("bg", 0, 0, 1920, 1080, "textures/bg.png")create_layout(name, x, y, width, height)
python
layout = cocosui.create_layout("container", 0, 0, 400, 300)create_scroll_view(name, x, y, width, height)
python
scroll = cocosui.create_scroll_view("scroll", 0, 0, 400, 600)
scroll.set_inner_container_size(400, 2000)create_list_view(name, x, y, width, height)
python
lv = cocosui.create_list_view("list", 0, 0, 400, 600)
lv.push_back_item(item_widget)
lv.remove_item(index)
count = lv.get_item_count()create_checkbox(name, x, y)
python
cb = cocosui.create_checkbox("agree", 100, 100)
cb.set_selected(True)
cb.set_change_callback(my_callback)create_slider(name, x, y, width)
python
slider = cocosui.create_slider("volume", 100, 50, 300)
slider.set_percent(50)
slider.set_change_callback(on_volume_change)
print(slider.get_percent())create_text_field(name, x, y, width, height, placeholder='')
python
tf = cocosui.create_text_field("input", 100, 100, 300, 40, "请输入...")
tf.set_text("默认文本")
text = tf.get_text()
tf.set_placeholder("新占位文字")create_page_view(name, x, y, width, height)
python
pv = cocosui.create_page_view("pages", 0, 0, 1920, 1080)
pv.add_page(page1)
pv.set_current_page(0)
page = pv.get_current_page()create_progress_bar(name, x, y, width, height)
python
bar = cocosui.create_progress_bar("loading", 100, 600, 200, 20)
bar.set_percent(75)特殊组件
Button
python
btn = cocosui.create_button("btn", 100, 100, 200, 60, "点击")
btn.set_text("新文本")
btn.set_click_callback(on_click)| 方法 | 说明 |
|---|---|
set_text(text) | 设置按钮文本 |
get_text() | 获取按钮文本 |
set_click_callback(callback) | 设置点击回调 |
Text
python
label = cocosui.create_text("label", 10, 10, 24, "文本")
label.set_content("新内容")
label.set_halign(1) # 0=左, 1=中, 2=右
label.set_valign(1) # 0=上, 1=中, 2=下Image
python
img = cocosui.create_image("img", 0, 0, 100, 100, "tex.png")
img.set_texture("new_tex.png")VIDEO (VideoPlayer)
python
video = cocosui.create_video_player("vid", 0, 0, 1920, 1080)
video.set_file_name("video/cutscene.mp4")
video.set_url("http://example.com/video.mp4")
video.play()
video.pause()
video.resume()
video.stop()
video.seek_to(30.0) # 跳转到30秒
video.set_looping(True)Particle
python
particle = cocosui.create_particle("fire", 100, 100, "particles/fire.plist")
particle.set_emission_rate(50)
particle.set_life(2.0)
particle.set_speed(100.0)
particle.set_total_particles(500)CSB 文件加载
载入 Cocos Studio 导出的 CSB 文件。
python
# 基本加载
csb = cocosui.load_csb("ui_name", x=0, y=0, csb_path="ui/main_menu.csb")
# 指定大小
csb = cocosui.load_csb_with_size("ui_name", x=0, y=0, width=1920, height=1080, csb_path="ui/hud.csb")CSBWidget
| 方法 | 说明 |
|---|---|
play_animation(name, loops=-1) | 播放动画 |
stop_animation() | 停止 |
pause_animation() | 暂停 |
resume_animation() | 恢复 |
is_animation_playing() | 是否播放中 |
set_animation_speed(speed) | 设置动画速度 |
get_animation_speed() | 获取动画速度 |
set_animation_loops(loops) | 设置循环次数 |
get_animation_loops() | 获取循环次数 |
get_current_animation() | 获取当前动画名 |
get_node(name) | 获取内部节点 |
get_all_nodes() | 获取所有节点 |
get_all_node_names() | 获取所有节点名 |
has_node(name) | 检查节点是否存在 |
get_node_count() | 节点总数 |
getui() | 获取 UI 容器 (CSBUIResult) |
CSBUIResult — UI 容器
python
ui = csb.getui()
# 获取节点
btn = ui["start_button"] # 或 ui.get("start_button")
# 检查存在
if ui.has("title"):
node = ui["title"]
# 遍历
ui.for_each(lambda node: print(node.get_name()))
# 统计
all_nodes = ui.all()
names = ui.names()
count = ui.count()UINode
python
node = csb.get_node("title_label")
# 基本信息
name = node.get_name()
type = node.get_type() # "Label", "Button", "Sprite" 等
valid = node.is_valid()
# 变换
node.set_visible(True)
node.set_position(100, 200)
node.set_size(200, 50)
node.set_color(1.0, 1.0, 1.0, 1.0)
node.set_rotation(45)
node.set_scale(2.0, 2.0)
node.set_opacity(128)
# 文本 (Label/Text)
node.set_text("新文本")
node.set_font_size(24)
# 按钮
node.set_button_text("点击我")
# 图片 (ImageView/Sprite)
node.set_texture("textures/new.png")
# 复选框
node.set_selected(True)
# 滑动条
node.set_percent(50)
# 文本框
node.set_field_text("输入内容")
# 进度条
node.set_progress(75)
# 层级
child = node.get_child("child_name")
children = node.get_children()清理
python
cocosui.remove_widget(widget) # 移除指定组件
cocosui.remove_all_widgets() # 移除所有组件