Matrix

Appearance

getFieldFromUa ​

从 UserAgent 中获取指定字段的值。

语法 ​

ts
getFieldFromUa(name: string): string | false

参数 ​

  • name (string): 要查找的字段名

返回值 ​

  • string - 字段对应的值
  • false - 字段不存在或无值时返回

异常 ​

  • TypeError - 当字段名不是字符串或为空时抛出

描述 ​

getFieldFromUa 函数用于解析 UserAgent 字符串，提取指定字段名后面的值。该函数支持常见的分隔符格式：

  • 斜杠分隔 (/)：AppName/1.2.3
  • 空格分隔 ()：AppName 1.2.3
  • 等号分隔 (=)：AppName=1.2.3

函数会自动处理值的边界，遇到空格、分号或括号时停止解析。

示例 ​

基本使用 ​

typescript
import { getFieldFromUa } from '@fu/matrix';

// UserAgent: "Mozilla/5.0 (iPhone; appVersion/2.1.0; theme/dark) Safari/537.36"
getFieldFromUa('appVersion'); // => "2.1.0"
getFieldFromUa('theme');      // => "dark"
getFieldFromUa('notExist');   // => false

同花顺应用场景 ​

typescript
import { getFieldFromUa } from '@fu/matrix';

// 同花顺主App: "iHexin/10.80.60 (iPhone; iOS 16.0; zh_CN) WebKit/605.1.15"
getFieldFromUa('iHexin'); // => "10.80.60"

// 期货App: "IHexin_Futures/8.90.50 (Android; 11; SM-G9750) AppleWebKit/537.36"
getFieldFromUa('IHexin_Futures'); // => "8.90.50"

获取浏览器信息 ​

typescript
import { getFieldFromUa } from '@fu/matrix';

// Chrome: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/120.0.0.0"
getFieldFromUa('Chrome'); // => "120.0.0.0"

// Safari: "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) Version/16.0 Safari/604.1"
getFieldFromUa('Version'); // => "16.0"
getFieldFromUa('Safari');  // => "604.1"

自定义应用字段 ​

typescript
import { getFieldFromUa } from '@fu/matrix';

// 自定义格式: "MyApp/2.1.0 (iOS; device=iPhone14; os=16.0; lang=zh_CN)"
getFieldFromUa('MyApp');   // => "2.1.0"
getFieldFromUa('device');  // => "iPhone14"
getFieldFromUa('os');      // => "16.0"
getFieldFromUa('lang');    // => "zh_CN"

版本信息提取 ​

typescript
import { getFieldFromUa } from '@fu/matrix';

function getAppVersion() {
  // 先尝试获取同花顺版本
  let version = getFieldFromUa('iHexin');
  if (version) {
    return { app: '同花顺', version };
  }
  
  // 再尝试期货App版本
  version = getFieldFromUa('IHexin_Futures');
  if (version) {
    return { app: '期货', version };
  }
  
  // 最后尝试通用版本字段
  version = getFieldFromUa('appVersion');
  if (version) {
    return { app: '未知', version };
  }
  
  return null;
}

const appInfo = getAppVersion();
if (appInfo) {
  console.log(`当前应用：${appInfo.app} v${appInfo.version}`);
}

主题检测增强 ​

typescript
import { getFieldFromUa, isDark } from '@fu/matrix';

function getThemeInfo() {
  // 从UA中获取主题信息（优先级更高）
  const uaTheme = getFieldFromUa('theme');
  if (uaTheme) {
    return uaTheme === 'dark' ? 'dark' : 'light';
  }
  
  // 回退到通用主题检测
  return isDark() ? 'dark' : 'light';
}

const theme = getThemeInfo();
console.log(`当前主题：${theme}`);

设备信息提取 ​

typescript
import { getFieldFromUa } from '@fu/matrix';

function getDeviceInfo() {
  const device = getFieldFromUa('device');
  const os = getFieldFromUa('os');
  const build = getFieldFromUa('build');
  
  return {
    device: device || '未知设备',
    os: os || '未知系统',
    build: build || '未知版本'
  };
}

const deviceInfo = getDeviceInfo();
console.log('设备信息:', deviceInfo);

边界情况处理 ​

字段不存在 ​

typescript
import { getFieldFromUa } from '@fu/matrix';

// UserAgent 中不存在的字段
getFieldFromUa('nonExistentField'); // => false

字段无值 ​

typescript
// UserAgent: "Mozilla/5.0 (iPhone; iOS 16.0) appName Safari/537.36"
getFieldFromUa('appName'); // => false (字段存在但无值)

错误处理 ​

typescript
import { getFieldFromUa } from '@fu/matrix';

try {
  getFieldFromUa('validField'); // 正常使用
} catch (error) {
  // 处理类型错误
  console.error('字段名必须是字符串');
}

// 错误示例
// getFieldFromUa('');     // 抛出 TypeError: 字段名不能为空
// getFieldFromUa(null);   // 抛出 TypeError: 字段名必须是字符串

支持的分隔符格式 ​

格式示例说明
斜杠AppName/1.2.3最常见的版本格式
空格AppName 1.2.3简单的空格分隔
等号AppName=1.2.3键值对格式

值边界识别 ​

函数会在遇到以下字符时停止解析：

  • 空格 ()
  • 分号 (;)
  • 右括号 ())
typescript
// "AppName/1.2.3; theme=dark) WebKit/537.36"
getFieldFromUa('AppName'); // => "1.2.3" (遇到分号停止)
getFieldFromUa('theme');   // => "dark"   (遇到括号停止)

环境支持 ​

  • ✅ 浏览器环境
  • ✅ Node.js 环境（navigator 不存在时返回 false）

注意事项 ​

  • 字段名区分大小写
  • 函数会查找第一个匹配的字段
  • 在 Node.js 环境中，如果 navigator 不存在，函数会安全地返回 false
  • 建议在解析前先验证 UserAgent 的格式

相关方法 ​

版本历史 ​

  • v1.3.0: 新增函数