Block Base API 文档

概述

ylhc_block_base.js 提供了 Odoo 仪表板中 GrapesJS 组件的基础模型和视图类。它是所有仪表板区块组件的基类，提供了配置管理、数据加载、事件绑定、模板渲染等核心功能。

核心类

BaseModel

BaseModel 是 GrapesJS 组件模型的基类，继承自 grapesjs.component。

构造函数

new BaseModel(...arguments)

主要属性

配置管理方法

// 获取配置 ID
get_config_id()

// 获取配置对象
get_config()

// 获取原始配置
get_raw_config()

// 重新加载配置
reload_config(clear_style = false)

// 克隆配置
clone_config()

// 应用原始配置
apply_raw_config(raw_config)

// 异步加载配置
_load_config(config_id, options = {})

// 自动重新加载配置
_auto_reload_config()

数据源方法

// 重新加载数据源
reload_data_source(options)

// 应用数据源
apply_data_source(result)

// 获取数据源获取选项
get_fetch_options()

事件绑定方法

// 绑定事件
_bind_events()

// 解绑事件
_un_bind_events()

// 配置变更回调
_on_config_change()

// 配置 ID 变更回调
_on_config_id_change()

// 编辑器就绪回调
_on_editor_ready()

// 所有依赖配置就绪
_on_all_depend_config_ready()

搜索相关方法

// 执行搜索
_do_search(event)

// 初始化搜索
_do_init_search(event)

// 获取分组名称
get_group_name()

工具方法

// 获取仪表板实例
get_dashboard()

// 获取仪表板 ID
get_dashboard_id()

// 检查是否为预览模式
is_preview()

// 检查是否为浅层模式
is_shallow()

// 检查编辑器是否就绪
is_editor_ready()

// RPC 调用
rpc(...args)
_rpc(...args)

// 触发向上事件
trigger_up(msg, data)

// 执行 Odoo 动作
do_action(...args)

样式和脚本方法

// 确保库加载
ensure_libs(js_libs = [], css_libs = [])

// 更新脚本
update_script(scripts)

// 移除样式
remove_styles()

// 添加动态样式
add_dynamic_style(style)

// 包装样式
wrap_style(style)

子组件管理

// 禁用子组件
disable_children()

// 禁用第一个子组件
disable_first_child()

// 子组件添加回调
_on_add_reset()

下钻功能

// 渲染上钻箭头
render_drill_up_arrow()

// 更新上钻显示状态
update_drill_up(visible)

模板方法

// 获取 QWeb 模板 ID
get_qweb_template_id()

// 获取 QWeb 演示模板 ID
get_qweb_demo_template_id()

// 设置模板数据
set_template_data(data)

// 获取模板数据
get_template_data()

自定义属性方法

// 设置自定义属性
set_custom_props(custom_props)

// 获取自定义属性
get_custom_props()

// 获取自定义配置信息
get_custom_config_infos()

// 保存自定义属性
save_custom_props()

// 获取默认属性
get_default_props()

上下文方法

// 获取上下文
get_context()

// 设置额外 domain
set_extra_domain(extra_domain)

// 设置额外信息
set_extra_info(extra_info)

定时器方法

// 定时重新加载配置
_on_timer_reload_config(event)

// 定时器重新加载配置
_onTimerReloadConfig

链接区块方法

// 链接区块变更回调
_on_linked_block_changed(event)

// 链接上下文变更回调
_on_linked_context_change()

主题方法

// 获取主题名称
get_theme_name()

// 主题变更回调
_on_config_theme_changed(event)

区块 ID 变更

// 区块 ID 变更回调
_on_block_id_change()

初始化配置

// 初始化配置回调
_on_init_config(event)

强制重新加载

// 强制重新加载配置
_on_force_reload_config(event)

查询数据

// 查询数据
_do_query_data(event)

配置就绪

// 配置就绪回调
_on_config_ready()

拖拽事件

// 拖拽开始
_on_drag_start()

// 拖拽结束
_on_drag_end()

数据源变更

// 数据源变更回调
_on_data_source_change()

异步加载配置变更

// 异步加载配置变更
_load_config_async_change()

获取模型

// 通过 ID 获取模型
get_model_by_id(id)

默认脚本

// 执行默认脚本
execute_default_script()

工具栏

// 初始化工具栏
initToolbar()

下一帧

// 下一帧
nextTick()

获取环境

// 获取环境
get_env()

销毁

// 销毁
destroy()

获取脚本字符串

// 获取脚本字符串
getScriptString(script, standalone = false)

BaseView

BaseView 是 GrapesJS 组件视图的基类，继承自 grapesjs.componentView。

构造函数

new BaseView(...arguments)

主要方法

选择器和元素

// jQuery 选择器
$(selector)

// 等待元素存在
waitForElementToExist(el, callback)

配置获取

// 获取配置 ID
get_config_id()

// 获取配置对象
get_config()

// 获取原始配置
get_raw_config()

// 获取自定义属性
get_custom_props()

数据源

// 获取所有数据源
get_data_sources()

// 获取指定索引的数据源
get_data_source(index = 0)

仪表板

// 获取仪表板
get_dashboard()

// 获取仪表板 ID
get_dashboard_id()

// 获取环境
get_env()

事件

// 扩展事件
extend_events(events)

// 触发向上事件
trigger_up(msg, data)

RPC 和动作

// RPC 调用
rpc(...args)
_rpc(...args)

// 执行动作
do_action(...args)

模板

// 更新模板
update_template()

// 更新演示模板
update_demo_template()

// 是否有模板
has_template()

// 移除模板
remove_template()

// 获取 QWeb 模板 ID
get_qweb_template_id()

// 设置模板数据
set_template_data(data)

// 获取模板数据
get_template_data()

样式

// 样式变更回调
_onchange_styles()

// 添加动态样式
add_dynamic_style(style)

// 包装样式
wrap_style(style)

定时器

// 设置超时
setTimeout(callback, time)

// 清除超时
clearTimeout(timer_id)

// 设置间隔
setInterval(callback, time)

// 清除间隔
clearInterval(timer_id)

// 设置命名超时
set_time_out(name, func, time)

// 清除命名超时
clear_time_out(name)

// 清除所有超时
clear_time_outs()

// 设置命名间隔
setInterval(name, func, time)

// 清除所有间隔
clearIntervals()

// 清除命名间隔
clearInterval(name)

预览

// 预览开始
on_preview_started()

// 预览停止
on_preview_stopped()

// 是否在预览中
is_in_preview()

编辑模式

// 是否在编辑模式
in_edit_mode()

// 获取编辑器配置
get_editor_config()

// 获取编辑器模式
get_editor_mode()

// 获取视图模式
get_view_mode()

下钻

// 渲染上钻箭头
render_drill_up_arrow()

// 更新上钻显示
update_drill_up(visible)

// 鼠标进入
_on_mouseenter(event)

// 鼠标离开
_on_mouseleave(event)

依赖配置

// 所有依赖配置是否就绪
is_all_depend_config_ready()

// 是否有依赖配置
has_depend_configs()

// 依赖配置就绪回调
_on_all_depend_config_ready()

模型获取

// 通过 ID 获取模型
get_model_by_id(id)

表达式求值

// 求值表达式
evaluateExpr(expr, context)

// 求值表达式（别名）
eval_expr(expr, context)

库加载

// 确保库加载
ensure_libs(jslibs, csslibs)

服务

// 获取服务
get_service(service_name)

// action 服务
action

// ORM 服务
orm

// session
session

// user
user

渲染

// 渲染
render()

// 批量渲染
_render()

移除

// 移除
removed()

// 清除超时
clear_time_outs()

下一帧

// 下一帧
nextTick()

会话

// 获取会话
getSession()

配置加载失败

// 配置加载失败回调
_on_load_config_failed()

主题变更

// 主题变更回调
_onchange_theme()

脚本更新

// 更新脚本
updateScript(script)

浅层检查

// 是否为浅层模式
is_shallow()

导出

export const BlockBase = {
    BaseModel,
    BaseView
}

使用示例

创建自定义区块模型

import { BlockBase } from "@ylhc_dashboard_base/ylhc_block_base";

class MyBlockModel extends BlockBase.BaseModel {
    
    get defaults() {
        return {
            ...super.defaults,
            type: 'my-block',
            has_config: true,
            fetch_data: true,
        };
    }
    
    set_custom_props(custom_props) {
        // 解析自定义属性
        let props = JSON.parse(custom_props);
        this.set('my_prop', props.my_prop);
    }
    
    get_custom_props() {
        return {
            my_prop: this.get('my_prop')
        };
    }
}

创建自定义区块视图

class MyBlockView extends BlockBase.BaseView {
    
    render() {
        // 获取配置
        let config = this.get_config();
        
        // 获取数据源
        let dataSource = this.get_data_source(0);
        
        // 渲染逻辑
        this.$el.html('<div>My Block Content</div>');
        
        return this;
    }
    
    on_preview_started() {
        // 预览开始时的逻辑
    }
    
    on_preview_stopped() {
        // 预览停止时的逻辑
    }
}

注册组件

grapesjs.DomComponents.addType('my-block', {
    model: MyBlockModel,
    view: MyBlockView
});

事件系统

模型事件

视图事件

全局事件

文件结构

src/
├── ylhc_block_base.js    # Block Base 核心类
├── data_source/          # 数据源相关
├── utils/                # 工具函数
└── ...