doodle-mini/miniprogram/base/pageMixin.README.md

# 通用页面基类 (pageMixin)

## 概述

`pageMixin.ts` 提供了一个通用的页面基类，可以被不同模块（数学学习、专注力等）共用。它抽象了 Canvas 绘制页面的通用功能。

## 核心功能

- Canvas 初始化和配置
- 分享功能（小程序分享、朋友圈分享）
- 图片导出和打印
- 页面信息初始化

## 使用方法

### 1. 基础用法（不依赖特定的页面信息查找）

```typescript
import { createPage } from '../../base/pageMixin';

createPage({
    canvas: null as Canvas | null,
    ctx: null as RenderingContext | null,
    // ... 其他属性

    data: {
        pageTitle: '页面标题',
        functionId: 'my-function-id',
        // ... 其他数据
    },

    onLoad(options: { id?: string }) {
        const functionId = options.id || 'my-function-id';

        // 方式1：直接提供页面信息
        this.initPageInfo({
            functionId,
            title: '页面标题',
            desc: '页面描述',
        });

        // 或者方式2：使用默认标题（需要传入 defaultTitle）
        this.initPageInfo(functionId, '默认标题');
    },
});
```

### 2. 自定义页面信息查找函数

如果你有多个页面需要共享同一个查找逻辑，可以创建自己的 mixin：

```typescript
import { createPage, PageCommonMethodsConfig } from '../../base/pageMixin';

// 定义自己的页面信息查找函数
function myPageInfoLookup(functionId: string) {
    // 从你的常量或配置中查找
    const pageInfo = MY_FUNCTION_TYPES.find((item) => item.id === functionId);
    if (pageInfo) {
        return {
            title: pageInfo.title,
            desc: pageInfo.desc,
        };
    }
    return undefined;
}

// 使用配置创建页面
const config: PageCommonMethodsConfig = {
    shareConfig: {
        title: '我的模块',
        imageUrl: 'https://example.com/share.png',
    },
    pageInfoLookup: myPageInfoLookup,
};

createPage(
    {
        // ... 页面配置
        onLoad(options: { id?: string }) {
            const functionId = options.id || 'default-id';
            // 现在可以使用简化的调用方式
            this.initPageInfo(functionId, '默认标题');
            // 如果有 pageInfoLookup，会自动查找并设置 title 和 desc
        },
    },
    config,
);
```

### 3. 数学模块的用法（向后兼容）

数学模块已经封装好了专用的 `mathPageMixin.ts`，可以直接使用：

```typescript
import { createMathPage, CanvasDataState } from '../common/mathPageMixin';

createMathPage({
    // ... 页面配置
    onLoad(options: { id?: string }) {
        const functionId = options.id || 'addition-5';
        // 自动从 MATH_FUNCTION_TYPES 中查找
        this.initPageInfo(functionId, '默认标题');
    },
});
```

## API 说明

### createPage(pageOptions, config?)

创建并注册一个页面。

**参数：**

- `pageOptions`: 页面配置对象
- `config`: 可选，公共方法配置（见 `PageCommonMethodsConfig`）

### initPageInfo(functionIdOrOptions, defaultTitle?)

初始化页面信息，支持两种调用方式：

**方式1：**

```typescript
this.initPageInfo(functionId: string, defaultTitle?: string)
```

- 如果有配置 `pageInfoLookup`，会尝试查找
- 否则使用 `defaultTitle`

**方式2：**

```typescript
this.initPageInfo({ title: string, desc?: string, functionId: string })
```

- 直接提供页面信息，忽略 `pageInfoLookup`

### initCanvas(options)

初始化 Canvas。

**参数：**

- `options.createDrawService`: 创建绘制服务的工厂函数
- `options.drawServiceOptions`: 绘制服务的选项
- `options.onCanvasReady`: Canvas 初始化完成后的回调

### exportToPrint()

导出并保存图片（用于打印）。

### getShareOptions() / getAppShareAppMessage() / getAppShareTimeline()

全站统一使用 `config/config.ts` 中的 `defaultShareConfig`（标题、分享图）；**分享 path 为当前页面**（含 `?id=` 等参数）。`createPage` 页面已内置 `onShareAppMessage` / `onShareTimeline`。

收藏、我的、设置页在 `*.json` 中关闭分享，并在 `onLoad` 调用 `disablePageShareMenu()`。

普通 `Page({})` 可展开：

```typescript
import { appSharePageMethods } from '../../base/pageMixin';

Page({
  // ...
  ...appSharePageMethods,
});
```

### onShareAppMessage() / onShareTimeline()

由 `pageMixin` 提供，分享内容固定为首页入口，埋点仍上报当前页 `pageTitle`（canvas 页）或不带标签（Tab 页）。

## 专注力模块使用示例

```typescript
import { createPage, PageCommonMethodsConfig } from '../../base/pageMixin';

// 专注力模块的函数类型定义
interface FocusFunctionType {
    id: string;
    title: string;
    desc: string;
}

// 专注力模块的函数列表
const FOCUS_FUNCTION_TYPES: FocusFunctionType[] = [
    {
        id: 'grid-drawing',
        title: '格子仿画',
        desc: '在格子中绘制颜色',
    },
    // ... 更多
];

// 专注力模块的页面信息查找函数
function focusPageInfoLookup(functionId: string) {
    const functionItem = FOCUS_FUNCTION_TYPES.find(
        (item) => item.id === functionId,
    );
    if (functionItem) {
        return {
            title: functionItem.title,
            desc: functionItem.desc,
        };
    }
    return undefined;
}

// 专注力模块的配置
const focusConfig: PageCommonMethodsConfig = {
    shareConfig: {
        title: '涂鸦丫-专注力训练',
        imageUrl: 'https://cdn.joeyone.cn/doodle/share-img/share-v3-800.png',
    },
    pageInfoLookup: focusPageInfoLookup,
};

// 创建专注力页面
createPage(
    {
        canvas: null as Canvas | null,
        // ... 其他配置

        onLoad(options: { id?: string }) {
            const functionId = options.id || 'grid-drawing';
            // 自动从 FOCUS_FUNCTION_TYPES 中查找
            this.initPageInfo(functionId, '格子仿画');
        },
    },
    focusConfig,
);
```

## 向后兼容性

所有现有的数学页面无需修改，因为 `mathPageMixin.ts` 保持了相同的接口。