概述

数据源 API 提供了管理 Odoo 仪表板数据的综合接口。它由四个主要组件组成：

• DataSource - 主数据容器和操作
• Record - 单个数据记录包装器
• Field - 字段元数据和格式化
• DataSourceManager - 缓存和事件管理

DataSource

DataSource 类是访问和操作仪表板数据的主要接口。

构造函数

new DataSource(data_source, config, parent)

• data_source - 来自后端的原始数据源对象
• config - 仪表板配置
• parent - 父数据源（用于上一周期数据）

属性

数据访问方法

原始数据访问

// 获取原始数据数组
dataSource.get_raw_datas()
dataSource.raw_datas  // getter

// 获取原始数据源对象
dataSource.get_raw_data_source()

记录访问

// 获取所有记录
dataSource.get_records()

// 通过索引获取记录
dataSource.get_record(index)

// 获取记录数量
dataSource.get_records_count()

// 通过列值获取记录
dataSource.get_record_by_col_value(col_name, col_value)

// 类数组访问（通过 Proxy）
dataSource[0]  // 第一条记录
dataSource[1]  // 第二条记录

行/列访问

// 获取列名
dataSource.get_col_names(just_visible = true)

// 获取指定列的值
dataSource.get_col_values(col_name, format = true, formatter = null)
dataSource.get_column_values(col_name, format = false)

// 获取列的唯一值
dataSource.get_unique_col_values(col_name, formatter = null)

// 按类别获取聚合值
dataSource.get_aggregated_col_values(measure_name, category_name)

// 获取指定行/列的值
dataSource.get_col_value(row_index, col_name)

// 获取行的所有值
dataSource.get_row_values(row_index)

// 通过值查找行
dataSource.get_row_by_value(col_name, value)

// 通过值获取行索引
dataSource.get_row_index_by_value(col_name, value)

// 获取多列值
dataSource.get_cols_values(col_names)

字段方法

// 获取所有字段
dataSource.get_fields()

// 仅获取可见字段
dataSource.get_visible_fields()

// 通过名称获取字段
dataSource.get_field(name)

// 获取字段名数组
dataSource.get_field_names()

// 获取列（用于表格显示）
dataSource.get_columns()

// 检查字段是否隐藏
dataSource.is_hide_field(column_name)

// 获取隐藏字段
dataSource.get_hidden_fields()

类别和分组方法

// 获取类别字段
dataSource.get_category_fields()

// 获取类别名称
dataSource.get_categories()

// 通过索引获取类别
dataSource.get_category(index)

// 获取类别的值
dataSource.get_category_values(category_name_or_index)

// 检查是否有分组
dataSource.has_group_by()

// 检查是否有多个分组
dataSource.has_multi_group_by()

// 获取第一个分组信息
dataSource.get_first_group_by()

// 获取分组名称
dataSource.get_group_by_names()

// 获取分组信息
dataSource.get_group_by_infos()

// 检查字段是否作为类别处理
dataSource.fields_as_category()

度量和聚合方法

// 获取度量字段
dataSource.get_measures()

// 获取聚合列
dataSource.get_aggregate_columns()

// 获取第一个聚合列值
dataSource.get_first_aggregate_column_value(aggregate = 'sum')

// 获取第一个聚合列名
dataSource.get_first_aggregate_column_name()

// 获取列的聚合值
dataSource.get_aggregate_value(col_name, aggregate_type)

// 聚合值
dataSource.get_aggregate(values, aggregate_type = 'sum')

// 求和
dataSource.get_sum(values, filter_func = null)

// 平均值
dataSource.get_avg(values, filter_func = null)

// 最大值
dataSource.get_max(values, filter_func = null)

// 最小值
dataSource.get_min(values, filter_func = null)

// 获取列中的最大值
dataSource.get_max_value(column_name)

数据源类型方法

// 检查是否为自定义数据源
dataSource.is_custom()

// 检查是否来自模型
dataSource.is_get_data_from_model()

// 检查是否来自 SQL
dataSource.is_get_data_from_sql()

// 获取数据源类型
dataSource.get_data_source_type()

// 获取数据源信息
dataSource.get_data_source_info()

上一周期数据

// 检查是否有上一周期数据
dataSource.has_previous_data()

// 获取上一周期数据源
dataSource.get_previous_data_source()

过滤和转换

// 按状态过滤
filter_by_states(field_name, states)

显示和格式化

// 获取标题
dataSource.get_title()

// 获取列别名
dataSource.get_alias(column_name_or_names)
dataSource.get_display_name(column_name_or_names)

// 转换列名为别名
dataSource.convert_to_alias(column_names)

// 格式化名称值
dataSource.format_name(column, name)

// 默认格式化器
dataSource.default_formater(col_name, val)

// 检查是否为选择字段
dataSource.is_selection(col_name)

// 获取选择显示值
dataSource.get_selection_val(col_name, key)

模型操作

// 获取模型数据的 Odoo 操作
dataSource.get_model_action()

// 获取模型名称
dataSource.get_model()

// 获取 domain
dataSource.get_domain()

// 获取上下文
dataSource.get_context()

// 获取记录 ID
dataSource.get_ids()

缓存和刷新

// 清除缓存
dataSource.clearCache()

// 刷新数据（清除缓存并重新加载）
dataSource.refresh()

// 更新数据
dataSource.update_data(data_source)

工具方法

// 检查有效性
dataSource.is_valid()

// 清除数据
dataSource.clear()

// 获取维度（第一条记录的列名）
dataSource.get_dimensions()

// 获取维度值
dataSource.get_dimension_values(dimension_name)

// 获取数组风格数据
dataSource.get_array_style_datas()

// 通过名称获取字段信息
dataSource.get_field_info_by_name(field_name)

// 获取字段信息
dataSource.get_fields_info()

// 检查是否有排序
dataSource.has_order_by()

// 检查是否有多个排序
dataSource.has_multi_order_by()

Record

Record 类包装单个数据记录，支持字段元数据。

构造函数

new Record(record_data, fields_cache = null)

方法

// 通过列名获取值
record.get_value(col_name)

// 获取列名
record.get_col_names()
record.col_names  // getter

// 获取所有值
record.get_values()
record.values  // getter

// 获取所有字段
record.get_fields()
record.fields  // getter

// 通过名称获取字段
record.get_field(field_name)

// 检查是否有字段
record.has_field(field_name)

// 获取字段类型
record.get_field_type(field_name)

// 使用字段格式化器格式化值
record.format_value(field_name)

代理访问

记录支持代理访问数据属性：

record.field_name  // 直接属性访问
record['field_name']  // 括号表示法

Field

Field 类提供字段元数据和格式化功能。

构造函数

new Field(field_data)

属性

方法

// 基于字段类型格式化值
field.format_value(value)

// 检查是否支持聚合类型
field.supports_aggregation(aggregation_type)

// 导出字段信息
field.export_field_info()

// 获取原始字段数据
field.get_raw_data()

// 克隆字段
field.clone()

// 更新字段数据
field.update(data)

// 字符串表示
field.toString()

代理访问

字段支持代理访问原始字段数据：

field.any_property  // 访问 raw field_data 属性

DataSourceManager

DataSourceManager 为数据源提供缓存和事件管理。

事件

DataSourceEvents.ADD     // 数据源添加
DataSourceEvents.CHANGE  // 数据源变更
DataSourceEvents.REMOVE  // 数据源移除
DataSourceEvents.CLEAR   // 所有缓存清除

方法

// 订阅事件
const unsubscribe = data_source_manager.on(event, callback, ids = null)

// 取消订阅事件
data_source_manager.off(event, callback, ids = null)

// 设置缓存
data_source_manager.set(id, dataSource)

// 获取缓存
data_source_manager.get(id)

// 检查是否存在
data_source_manager.has(id)

// 更新缓存
data_source_manager.update(id, dataSource)

// 从缓存移除
data_source_manager.remove(id)

// 清除所有缓存
data_source_manager.clear()

// 获取缓存大小
data_source_manager.size  // getter

使用示例

import { data_source_manager, DataSourceEvents } from "@ylhc_dashboard_base/data_source/ylhc_data_source_manager";

// 监听变更
data_source_manager.on(DataSourceEvents.CHANGE, (id, dataSource, isUpdate) => {
    console.log(`数据源 ${id} 已变更`);
});

// 获取缓存的数据源
const ds = data_source_manager.get(dataSourceId);

// 缓存数据源
data_source_manager.set(dataSourceId, newDataSource);

使用示例

基本数据访问

import { DataSource } from "@ylhc_dashboard_base/data_source/ylhc_data_source";

// 创建数据源
const ds = new DataSource(rawData, config);

// 访问记录
const records = ds.get_records();
const firstRecord = ds.get_record(0);
const value = firstRecord.get_value('amount');

// 直接数组访问（通过 Proxy）
const alsoFirst = ds[0];

聚合

// 获取列求和
const sum = ds.get_aggregate_value('amount', 'sum');

// 获取第一个聚合值
const firstAgg = ds.get_first_aggregate_column_value('sum');

// 自定义聚合
const values = ds.get_col_values('amount');
const avg = ds.get_avg(values);

上一周期对比

if (ds.has_previous_data()) {
    const prevDs = ds.get_previous_data_source();
    const current = ds.get_first_aggregate_column_value();
    const previous = prevDs.get_first_aggregate_column_value();
    const change = ((current - previous) / previous) * 100;
}

字段信息

// 获取字段元数据
const field = ds.get_field('amount');
console.log(field.field_type);  // 'float'
console.log(field.is_measure);  // true

// 格式化值
const formatted = field.format_value(1234.56);  // 1234.56

类别和度量

// 获取 X 轴类别
const categories = ds.get_categories();
const categoryValues = ds.get_category_values(0);

// 获取 Y 轴度量
const measures = ds.get_measures();

文件结构

data_source/
├── ylhc_data_source.js          # DataSource 类
├── ylhc_record.js               # Record 类
├── ylhc_field.js                # Field 类
├── ylhc_data_source_manager.js  # DataSourceManager 类
└── DATA_SOURCE_API.md           # 本文档