# Uni-FontSync

**Repository Path**: lixin-git/uni-fontSync

## Basic Information

- **Project Name**: Uni-FontSync
- **Description**: 一个基于 UTS 的 uni-app 示例工程，通过原生能力读取 Android 与 iOS 的系统字体设置，并在应用内按照系统字体大小（或缩放比例）动态调整文字显示。由于 uni-app 默认隔离了系统字体大小，本项目以 UTS 插件方式进行绕过与适配。
- **Primary Language**: JavaScript
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-16
- **Last Updated**: 2025-12-23

## Categories & Tags

**Categories**: uniapp

**Tags**: None

## README

根据手机字体设置页面字体（uni-app + UTS 插件）

一个基于 UTS 的 uni-app 示例工程，通过原生能力读取 Android 与 iOS 的系统字体设置，并在应用内按照系统字体大小（或缩放比例）动态调整文字显示。由于 uni-app 默认隔离了系统字体大小，本项目以 UTS 插件方式进行绕过与适配。

<p>
  <img src="./SVID_20251211_171544_1.gif" alt="展示页预览" width="20%" />
</p>

## 功能概览

- Android：读取 `Configuration.fontScale` 获取系统字体缩放比例（如 `1.0`, `1.1`）  
- iOS：读取 `UIFont.preferredFont(forTextStyle: .body)` 的 `pointSize` 获取当前系统标准正文字体大小（如 `17.0`, `19.0`）  
- 全局混入：将读取到的值注入到页面 `data` 中，并提供方法在页面展示时进行计算和应用  
- 页面示例：根据系统设置动态计算文字大小并应用到 `text` 组件的 `style`

## 目录结构

```
项目根/
  common/
    font-scale-mixin.js           # 全局混入：读取系统字体并存储到 data
  pages/
    index/
      index.vue                   # 示例页面：按钮触发与动态字体大小展示
  uni_modules/
    uni-get-system-text-size/
      utssdk/
        interface.uts             # 插件接口定义（类型与默认实现）
        app-android/index.uts     # Android 原生实现：返回 fontScale
        app-ios/index.uts         # iOS 原生实现：返回 pointSize
      package.json                # 插件元信息
  main.js                         # 注入全局混入
  App.vue                         # 应用生命周期钩子
  manifest.json / pages.json      # 标准 uni-app 配置文件
```

## 原理说明

- Android：通过 `Resources.getConfiguration().fontScale` 获取系统字体缩放，`1.0` 为标准字号，`>1.0` 表示大字号，`<1.0` 表示小字号（`uni_modules/uni-get-system-text-size/utssdk/app-android/index.uts:7`）。  
- iOS：通过 `UIFont.preferredFont(forTextStyle: .body)` 获取系统当前“正文字体”的点大小，标准通常为 `17.0`（`uni_modules/uni-get-system-text-size/utssdk/app-ios/index.uts:4`）。  
- 页面应用：将获取到的数值与默认基准字体叠加，得到最终显示的像素值并应用到组件样式。

## 使用方法

1) 引入插件与全局混入  
- 在 `main.js` 中全局注入混入（`main.js:5`–`main.js:7`），混入会在页面展示时读取系统字体并写入 `fontSizeVal`（`common/font-scale-mixin.js:34`–`common/font-scale-mixin.js:37`）。
```js
import FontScaleMixin from './common/font-scale-mixin';
Vue.mixin(FontScaleMixin);
```

2) 页面示例  
- 在页面中使用计算属性，将系统值转换为最终字号，绑定到样式（`pages/index/index.vue:20`–`pages/index/index.vue:25`）。
```vue
<text :style="{ fontSize: computedFontSize + 'px' }">当前值: {{ fontSizeVal }}</text>
```

3) 同步获取与平台判断  
- 混入中调用同步方法 `getSystemFontSize()`（`common/font-scale-mixin.js:16`），并用条件编译宏判断平台（`common/font-scale-mixin.js:21`, `common/font-scale-mixin.js:27`）。

## 字体缩放归一化建议

当前实现返回值含义在两端不同：  
- Android 返回缩放比例（例如 `1.1`）  
- iOS 返回绝对点大小（例如 `19.0`）  

为便于统一计算，建议在页面层进行归一化为“缩放比例”：
```js
// 归一化为 scale：Android 直接使用，iOS 以 17 为基准点
const DEFAULT_IOS_BASE = 17;
const size = getSystemFontSize();
// #ifdef APP-ANDROID
const scale = size;                // 已是比例
// #endif
// #ifdef APP-IOS
const scale = size / DEFAULT_IOS_BASE;
// #endif
const baseFontPx = 17;             // 你的设计基准字号
const computedFontSize = scale * baseFontPx;
```
如需全局统一，可将归一化逻辑放入混入或封装为工具函数，避免每个页面重复。

## 关键代码位置

- 插件接口与默认实现：`uni_modules/uni-get-system-text-size/utssdk/interface.uts:10`  
- Android 实现（返回 `fontScale`）：`uni_modules/uni-get-system-text-size/utssdk/app-android/index.uts:7`  
- iOS 实现（返回 `pointSize`）：`uni_modules/uni-get-system-text-size/utssdk/app-ios/index.uts:4`  
- 全局混入注入：`main.js:5`  
- 读取系统字体并写入 `fontSizeVal`：`common/font-scale-mixin.js:16`、`common/font-scale-mixin.js:18`  
- 页面绑定与显示：`pages/index/index.vue:3`、`pages/index/index.vue:4`、`pages/index/index.vue:20`

## 运行与打包

- 推荐使用 HBuilderX 打开本项目，选择 App 平台运行（Android/iOS）。  
- UTS 代码由 HBuilderX 在构建期编译为目标平台字节码/原生代码（参考 `unpackage/` 下的编译产物）。

## 注意事项

- 不同设备与系统版本的“基准字号”可能有所差异，iOS 以 `.body` 的标准点大小为准，通常为 `17.0`。  
- 若你的设计基准字号不是 `17px`，请在归一化时调整 `DEFAULT_IOS_BASE` 与 `baseFontPx`。  
- 页面初次展示时即可读取系统值；若用户在系统设置中修改字体大小，需在应用前后台切换或页面重新展示时重新获取（可在 `onShow` 重试）。  
- 条件编译宏 `#ifdef APP-ANDROID` / `#ifdef APP-IOS` 仅在对应平台打包时生效。

## 后续扩展

- 将归一化 scale 注入到 CSS 变量，统一控制全局字号与间距：  
  例如在根节点维护 `--font-scale`，各组件字号均以该比例计算。  
- 监听系统设置变化（如可能）：通过原生层回调通知 JS 刷新 UI。  
- 提供更多文本样式适配：字重、行高、间距随 scale 协同调整。