tuyaopen-miniapp-charts-library

Files (8)

• SKILL.md
• evals.json · evals/
• examples.md
• reference.md
• README.md · references/energy-stats/
• evals.json · references/energy-stats/evals/
• integration-guide.md · references/energy-stats/
• snippets.md · references/energy-stats/

SKILL.md (first lines)

# @ray/charts-library Skill

## No `tuyaopen-cli` CLI coverage

`tuyaopen-cli` CLI 有 `miniapp` 命令组，但只覆盖构建 / 安装运行时 / 元数据 / DP schema 同步 / 预览 / 模板 / 上传等命令行操作（详见 the `tuyaopen-start` routing table）——具体的页面、组件、DP 交互编码不在其列。本技能的开发知识完全来自 `references/` 与项目内文档，不经 `tuyaopen-cli` CLI。


## 概述 {#description}

本 Skill 帮助 Agent 在 Ray 小程序页面中正确集成 `@ray/charts-library`。该库提供三类能力：**场景图表卡片**（开箱即用）、**可组合周期控件**（自定义布局）、以及**周期上下文 Hook**（完全自定义 UI）。

### 数据来源（不要硬编码本地路径）

1. 优先读取 **`node_modules/@ray/charts-library/README.md`**（如有中文版则用 `README-zh_CN.md`）。
2. 若依赖为 `file:` / monorepo 链接，通过 glob **`**/charts-library/README.md`** 定位。
3. README + 包类型声明为最终权威。

如果本地实现与 README 有冲突，以 README + 包导出为准。

### 可移植代码片段（项目无关）

代码片段收录在 [examples.md](examples.md) 中，设计为跨项目可移植：

- **不依赖**宿主项目的 `@/` 别名——复制后替换为项目实际别名。
- 复制后，根据 `@ray/charts-library` 的 README + 类型声明补全字段名和类型。

生成或迁移代码时：先从 [examples.md](examples.md) 读取对应模式，再从目标项目补全类型和国际化。

## 适用场景 {#scene}

当用户提及以下任何内容时触发本 Skill：

- `@ray/charts-library`、`@ray-js/charts-library`、`charts-library`
- `EleChartCard`、`TempAndHumChartCard`、`IlluminanceChartCard`
- `DataSourceProvider`、`ChartPeriodProvider`、`ChartSeriesPanel`、`ChartGranularityPicker`、`ChartPeriodNavigator`、`useChartPeriodContext`
- "用电图表 / 温湿度图表 / 照度图表 / 计量统计图表 / 周期切换图表"
- **用电量统计与峰谷计费**：参考 [references/energy-stats/README.md](references/energy-stats/README.md)
- `seriesDataToOption`、`withXAxis`、`withTooltip`
- 涂鸦统计 API：`getStatisticsConfig`、`getStatisticsRangHour`、`getStatisticsRang15min`、`getStatisticsRangDay`、`getStatisticsRangMonth`

**禁止**捏造 API。只使用本 Skill 或 `reference.md` 中记录的符号。如果用户的需求未被覆盖，先阅读库仓库中 `src/charts/` 和 `src/sceneCharts/` 的源码再回答。

### 快速决策树

根据用户描述推断场景，或向用户确认：

| 场景 | 使用方式 |
| --- | --- |
| 涂鸦用电量/电量消耗卡片，代码量最少 | `DataSourceProvider` + `EleChartCard` |
| 涂鸦温湿度（可切换），带阈值线 | `TempAndHumChartCard`（无需外部 Provider） |
| 涂鸦照度卡片 | `IlluminanceChartCard`（无需外部 Provider） |
| 涂鸦计量数据但需自定义页面布局 | `DataSourceProvider` + `ChartPeriodProvider` + `ChartGranularityPicker` + `ChartPeriodNavigator` + `ChartSeriesPanel` |
| 自定义 UI（自己的 tab / 图表）+ 涂鸦数据 | `DataSourceProvider` + `ChartPeriodProvider` + `useChartPeriodContext()` |
| 非涂鸦计量的任意数据源 | `ChartPeriodProvider` + `loadData` 属性 |

## 搭配使用 {#usage}

### 安装

```sh
yarn add @ray/charts-library
# 库依赖的 peer deps
yarn add @ray-js/ray @ray-js/common-charts dayjs
```

导入路径为 `@ray/charts-library`（在宿主小程序中）——匹配项目已有的别名即可。

### 模式 1 — 开箱即用场景卡片（EleChartCard）

最快路径。`DataSourceProvider` 注入涂鸦计量 API，`EleChartCard` 渲染标题 + 汇总 + 图表 + 导航器 + 粒度选择器。

```tsx
import { DataSourceProvider, EleChartCard } from '@ray/charts-library';

export default function Page() {
  return (
    <DataSourceProvider
      devId="your-device-id"
      dpId={18}
      algorithmType="sum"
      unit="kWh"
    >
      <EleChartCard
        title="用电量"
        initialGranularity="day"
        theme="light"
        chartHeight="520rpx"
      />
    </DataSourceProvider>
  );
}
```

关键属性（完整表格见 `reference.md`）：

- `DataSourceProvider`：`devId`、`dpId`、`algorithmType`、`dayInterval`（`'hour' | '15min'`，默认 `'hour'`）、`unit`、`noDataText`、`buildOption`、`api`。
- `EleChartCard`：`theme`（`'light' | 'dark'`）、`title`、`unit`、`chartHeight`、`granularityOptions`（默认 `['day','week','month','year']`）、`granularityLabels`、`chartProps`、`initialGranularity`、`initialRange`。

### 模式 2 — 温湿度卡片

`TempAndHumChartCard` 内部自带 `DataSourceProvider` + `ChartPeriodProvider`。只需传一次 `devId`，然后配置 `temperature` / `humidity` 中的一个或两个。同时提供两个时，会显示切换按钮。

```tsx
import { TempAndHumChartCard } from '@ray/charts-library';
import { iconTemperature, iconHumidity } from '@/res';

<TempAndHumChartCard
  devId={deviceId}
  title="环境"
  defaultMetric="temp"
  temperature={{
    dpId: 101,
    label: '温度',
    unit: '℃',
    icon: iconTemperature,
    threshold: { min: 18, max: 26 },
  }}
  humidity={{
    dpId: 102,
    label: '湿度',

From tuya/tuyaopen-ide-manifests, Apache-2.0.

More from tuya/tuyaopen-ide-manifests