# 框架核心（Framework Core）

> 官方文档：https://developers.weixin.qq.com/miniprogram/dev/framework/

## 架构概述

小程序框架（MINA）分为两部分：
- **逻辑层（App Service）**：运行 JavaScript，处理数据和业务逻辑
- **视图层（View）**：渲染 WXML + WXSS，展示 UI

逻辑层和视图层分别运行在不同的线程中，通过 Native 层进行数据传输和事件通信。

**关键限制**：逻辑层不运行在浏览器中，没有 `window`、`document` 等 Web API。

## 目录结构

一个小程序主体部分由三个文件组成（必须放在项目根目录）：

| 文件 | 必需 | 作用 |
|------|------|------|
| `app.js` | 是 | 小程序逻辑（App() 注册） |
| `app.json` | 是 | 小程序公共配置 |
| `app.wxss` | 否 | 小程序公共样式表 |

一个小程序页面由四个文件组成：

| 文件 | 必需 | 作用 |
|------|------|------|
| `页面.js` | 是 | 页面逻辑（Page() 注册） |
| `页面.wxml` | 是 | 页面结构（模板） |
| `页面.wxss` | 否 | 页面样式 |
| `页面.json` | 否 | 页面配置 |

## app.json 全局配置

```json
{
  "pages": [
    "pages/index/index",
    "pages/logs/logs"
  ],
  "window": {
    "navigationBarTitleText": "小程序",
    "navigationBarBackgroundColor": "#ffffff",
    "navigationBarTextStyle": "black",
    "backgroundColor": "#eeeeee",
    "backgroundTextStyle": "light",
    "enablePullDownRefresh": false
  },
  "tabBar": {
    "color": "#999",
    "selectedColor": "#333",
    "backgroundColor": "#fff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "首页",
        "iconPath": "images/tab/home.png",
        "selectedIconPath": "images/tab/home-active.png"
      }
    ]
  },
  "networkTimeout": {
    "request": 10000,
    "downloadFile": 10000
  },
  "subpackages": [],
  "permission": {
    "scope.userLocation": {
      "desc": "你的位置信息将用于小程序位置接口的效果展示"
    }
  },
  "lazyCodeLoading": "requiredComponents"
}
```

### pages 配置
- 数组第一项为小程序初始页面（首页）
- 不需要写文件后缀，框架会自动寻找 `.json` `.js` `.wxml` `.wxss` 四个文件
- 新增/减少页面需要修改 pages 数组

### window 配置
| 属性 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| navigationBarBackgroundColor | HexColor | #000000 | 导航栏背景颜色 |
| navigationBarTextStyle | string | white | 导航栏标题颜色，仅支持 black / white |
| navigationBarTitleText | string | | 导航栏标题文字 |
| navigationStyle | string | default | 导航栏样式，custom 为自定义导航栏（只保留右上角胶囊按钮） |
| backgroundColor | HexColor | #ffffff | 窗口背景色 |
| backgroundTextStyle | string | dark | 下拉 loading 样式，仅支持 dark / light |
| enablePullDownRefresh | boolean | false | 是否开启全局下拉刷新 |
| onReachBottomDistance | number | 50 | 页面上拉触底事件触发时距页面底部距离（px） |

### tabBar 配置
- `list` 数组最少 2 个、最多 5 个 tab
- tabBar 页面必须在 pages 数组中
- `position` 可选 `bottom`（默认）或 `top`（顶部时不显示 icon）

## 页面配置（page.json）

每个页面可以有自己的 `.json` 文件，覆盖 `app.json` 中 `window` 的配置：

```json
{
  "navigationBarTitleText": "页面标题",
  "enablePullDownRefresh": true,
  "usingComponents": {
    "my-component": "/components/my-component/my-component"
  }
}
```

## sitemap.json

配置小程序及其页面是否允许被微信索引：

```json
{
  "rules": [
    {
      "action": "allow",
      "page": "*"
    }
  ]
}
```

## 场景值

场景值用于描述用户进入小程序的路径，常见场景值：

| 场景值 | 说明 |
|--------|------|
| 1001 | 发现栏小程序主入口 |
| 1007 | 单人聊天会话中的小程序消息卡片 |
| 1008 | 群聊会话中的小程序消息卡片 |
| 1011 | 扫描二维码 |
| 1012 | 长按识别二维码 |
| 1020 | 公众号 profile 页相关小程序列表 |
| 1035 | 公众号自定义菜单 |
| 1036 | App 分享消息卡片 |
| 1037 | 小程序打开小程序 |
| 1038 | 从另一个小程序返回 |
| 1043 | 公众号模板消息 |
| 1047 | 扫描小程序码 |
| 1048 | 长按识别小程序码 |
| 1089 | 微信聊天主界面下拉 |

可在 `App.onLaunch` / `App.onShow` 中通过 `options.scene` 获取。

## 基础库版本兼容

```javascript
// 方式一：wx.canIUse
if (wx.canIUse('openBluetoothAdapter')) {
  wx.openBluetoothAdapter()
} else {
  wx.showModal({ title: '提示', content: '当前微信版本过低，无法使用该功能' })
}

// 方式二：比较版本号
function compareVersion(v1, v2) {
  v1 = v1.split('.')
  v2 = v2.split('.')
  const len = Math.max(v1.length, v2.length)
  while (v1.length < len) v1.push('0')
  while (v2.length < len) v2.push('0')
  for (let i = 0; i < len; i++) {
    const num1 = parseInt(v1[i])
    const num2 = parseInt(v2[i])
    if (num1 > num2) return 1
    else if (num1 < num2) return -1
  }
  return 0
}

const SDKVersion = wx.getSystemInfoSync().SDKVersion
if (compareVersion(SDKVersion, '1.1.0') >= 0) {
  wx.openBluetoothAdapter()
}
```

## 在线查询

如需更详细的配置项说明，可直接抓取：
- 全局配置：https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/app.html
- 页面配置：https://developers.weixin.qq.com/miniprogram/dev/reference/configuration/page.html
- 场景值列表：https://developers.weixin.qq.com/miniprogram/dev/reference/scene-list.html