實用程式

Framework7 實用程式是一組輔助方法，在內部使用，在開發期間也很方便。

它可用作 Framework7 類別的 utils 屬性（Framework7.utils）和已初始化應用程式執行個體的相同屬性（app.utils）

// If we need it in place where we don't have access to app instance or before we init the app
var now = Framework7.utils.now();


// After we init the app we can access it as app instance property
var app = new Framework7({ /*...*/ });
var now = app.utils.now();

它也可以使用 ES 模組匯入

import { utils } from 'framework7';

實用程式方法

`parseUrlQuery()`

app.utils.parseUrlQuery(url)- 解析 URL 查詢取得參數

url - 字串 - 含有 GET 參數的 URL。必填。

方法傳回包含查詢參數的物件

var query = app.utils.parseUrlQuery('http://google.com/?id=5&foo=bar');
console.log(query); // { id: 5, foo: 'bar' }

`serializeObject()`

app.utils.serializeObject(object)- 建立純粹物件的序列化表示，適合用於 URL 查詢字串

object - 物件 - 要序列化的物件

傳回一個新的唯一陣列

var params = { foo: 'bar', id: 5 };
console.log(app.utils.serializeObject(params)); // 'foo=bar&id=5'

`requestAnimationFrame()`

app.utils.requestAnimationFrame(callback)- requestAnimationFrame 的跨瀏覽器實作

callback - 函式 - 在需要更新下一次重新繪製的動畫時呼叫的函式

傳回動畫請求 ID，唯一識別回呼清單中的項目

var animId;
function anim() {
  var left = parseInt($$('#anim').css('left'), 10) + 1;
  $$('#anim').css({left: left + 'px'})
  animId = app.utils.requestAnimationFrame(anim);
}
animId = app.utils.requestAnimationFrame(anim);

`cancelAnimationFrame()`

app.utils.cancelAnimationFrame(requestID)- 取消動畫框架請求

requestID - 數字 - app.utils.requestAnimationFrame() 呼叫要求回呼傳回的 ID 值

app.utils.cancelAnimationFrame(animId);

`nextFrame()`

app.utils.nextFrame(callback)- 在下一個可用的動畫框架上執行程式碼。

callback - 字串 - 在需要更新下一次重新繪製的動畫時呼叫的函式。

app.utils.nextFrame(function() {
  // do something on next frame
});

`nextTick()`

app.utils.nextTick(callback, delay)- 在所需的延遲後執行程式碼。基本上是 setTimeout 的別名

callback - 字串 - 在指定延遲後呼叫的函式
delay - 數字 - 以毫秒為單位的延遲。選用，預設為 0

傳回逾時 ID

app.utils.nextTick(function() {
  // do something on next tick
});

`now()`

app.utils.now()- 返回目前時間戳記（毫秒）

var now = app.utils.now();
setTimeout(function () {
  var timeDiff = app.utils.now() - now;
  console.log(timeDiff + 'ms past');
}, 2000);

`extend()`

app.utils.extend(target, ...from)- 使用 from 物件的屬性和方法來擴充 target 物件

target - 物件 - 要擴充的目標物件
from - 物件 - 要複製屬性和方法的物件

傳回已擴充屬性和方法的目標物件

如果你需要使用其他物件的屬性來擴充一個物件，或需要物件的深度複製時，這個方法會非常方便。

var a = {
  apple: 0,
  cherry: 97
};
// Pass as empty object as target to copy a into b
var b = app.utils.extend({}, a);

console.log(b); // { apple: 0, cherry: 97 }
console.log(a === b); // false

var a = {
  apple: 0,
  cherry: 97
};
var b = {
  banana: 10,
  pineapple: 20,
}

// Extends a with b
app.utils.extend(a, b);

console.log(a); // { apple: 0, cherry: 97, banana: 10, pineapple: 20 }

var a = {
  apple: 0,
  cherry: 97
};
var b = {
  banana: 10,
  pineapple: 20,
}

// Create new object c from the merge of a and b
var c = app.utils.extend({}, a, b);

console.log(c); // { apple: 0, cherry: 97, banana: 10, pineapple: 20 }

var a = {
  apple: 0,
  cherry: 97
};
var b = {
  apple: 10,
  pineapple: 20,
}

// Extend a with b
app.utils.extend(a, b);

console.log(a); // { apple: 10, cherry: 97, pineapple: 20 }

`uniqueNumber()`

app.utils.uniqueNumber()- 傳回唯一數字，每次呼叫都會增加 1

app.utils.uniqueNumber(); // -> 2

app.utils.uniqueNumber(); // -> 3

app.utils.uniqueNumber(); // -> 4

`id()`

app.utils.id(mask, map)- 產生隨機的 ID 字串

mask - 字串 - ID 字串遮罩，預設為 xxxxxxxxxx
map - 字串 - 用於產生的字元，預設為 0123456789abcdef

傳回隨機產生的字串

app.utils.id() // -> ffe28ab56e

app.utils.id('xxxx-xxxx-xxxx-xxxx') // -> 1ea3-f127-dc67-627d

app.utils.id('xxxx-xxxx', 'abcd') // -> aabc-ccda

`preloaderContent`

有一些屬性包含 Preloader 元素與主題相關的內容（iOS、MD）。如果你動態建立 preloader，這些屬性會很有用。

app.utils.iosPreloaderContent- 包含 iOS 主題所需的 preloader 內部內容（HTML 字串）

app.utils.mdPreloaderContent- 包含 MD 主題所需的 preloader 內部內容（HTML 字串）

// call method dynamically based on current app theme
var preloaderContent = app.utils[app.theme + 'PreloaderContent'];

// create required preloader content
var myPreloader = '<div class="preloader">' + preloaderContent + '</div>';

// add it somewhere
$('.something').append(myPreloader);

`colorHexToRgb()`

app.utils.colorHexToRgb(hexColor)- 將 HEX 顏色轉換為 RGB 顏色

hexColor - 字串 - HEX 顏色字串

傳回 [R, G, B] 陣列

app.utils.colorHexToRgb('#f00') // -> [255, 0, 0]

`colorRgbToHex()`

app.utils.colorRgbToHex(R, G, B)- 將 RGB 顏色轉換為 HEX 顏色

R - 數字 - 紅色值（0 - 255）
G - 數字 - 綠色值（0 - 255）
B - 數字 - 藍色值（0 - 255）

傳回 HEX 顏色字串

app.utils.colorHexToRgb(255, 0, 0) // -> '#ff0000'

`colorRgbToHsl()`

app.utils.colorRgbToHsl(R, G, B)- 將 RGB 顏色轉換為 HSL 顏色

R - 數字 - 紅色值（0 - 255）
G - 數字 - 綠色值（0 - 255）
B - 數字 - 藍色值（0 - 255）

傳回 [H, S, L] 陣列

app.utils.colorRgbToHsl(255, 0, 0) // -> [0, 1, 0.5]

`colorHslToRgb()`

app.utils.colorHslToRgb(H, S, L)- 將 HSL 顏色轉換為 RGB 顏色

H - 數字 - 色相值 (0 - 360)
S - 數字 - 飽和度值 (0 - 1)
L - 數字 - 明度值 (0 - 1)

傳回 [R, G, B] 陣列

app.utils.colorHslToRgb(0, 1, 0.5) // -> [255, 0, 0]

`colorHsbToHsl()`

app.utils.colorHsbToHsl(H, S, B)- 將 HSB(V) 顏色轉換為 HSL 顏色

H - 數字 - 色相值 (0 - 360)
S - 數字 - 飽和度值 (0 - 1)
B - 數字 - 亮度值 (0 - 1)

傳回 [H, S, L] 陣列

app.utils.colorHsbToHsl(360, 0.5, 0.5) // -> [360, 0.33, 0.375]

`colorHslToHsb()`

app.utils.colorHslToHsb(H, S, L)- 將 HSL 顏色轉換為 HSB(V) 顏色

H - 數字 - 色相值 (0 - 360)
S - 數字 - 飽和度值 (0 - 1)
L - 數字 - 明度值 (0 - 1)

傳回 [H, S, B] 陣列

app.utils.colorHslToHsb(360, 0.5, 0.5) // -> [360, 0.66, 0.75]

`colorThemeCSSProperties()`

app.utils.colorThemeCSSProperties(hexColor)- 傳回物件，其中包含產生 CSS 變數，用於設定指定的佈景主題顏色

hexColor - 字串 - HEX 顏色字串

傳回包含必要的 CSS 變數及其值的物件。

app.utils.colorThemeCSSProperties(R, G, B)- 傳回物件，其中包含產生 CSS 變數，用於設定指定的佈景主題顏色

R - 數字 - 紅色值
G - 數字 - 綠色值
B - 數字 - 藍色值

傳回包含必要的 CSS 變數及其值的物件。

app.utils.colorThemeCSSProperties('#f00')
/* returns the following object:
{
  "ios": {
    "--f7-theme-color": "var(--f7-ios-primary)",
    "--f7-theme-color-rgb": "var(--f7-ios-primary-rgb)",
    "--f7-theme-color-shade": "var(--f7-ios-primary-shade)",
    "--f7-theme-color-tint": "var(--f7-ios-primary-tint)"
  },
  "md": {
    "--f7-theme-color": "var(--f7-md-primary)",
    "--f7-theme-color-rgb": "var(--f7-md-primary-rgb)",
    "--f7-theme-color-shade": "var(--f7-md-primary-shade)",
    "--f7-theme-color-tint": "var(--f7-md-primary-tint)"
  },
  "light": {
    "--f7-ios-primary": "#f00",
    "--f7-ios-primary-shade": "#d60000",
    "--f7-ios-primary-tint": "#ff2929",
    "--f7-ios-primary-rgb": "255, 0, 0",
    "--f7-md-primary-shade": "#970100",
    "--f7-md-primary-tint": "#e90100",
    "--f7-md-primary-rgb": "192, 1, 0",
    "--f7-md-primary": "#c00100",
    "--f7-md-on-primary": "#ffffff",
    "--f7-md-primary-container": "#ffdad4",
    "--f7-md-on-primary-container": "#410000",
    "--f7-md-secondary": "#775651",
    "--f7-md-on-secondary": "#ffffff",
    "--f7-md-secondary-container": "#ffdad4",
    "--f7-md-on-secondary-container": "#2c1512",
    "--f7-md-surface": "#fffbff",
    "--f7-md-on-surface": "#201a19",
    "--f7-md-surface-variant": "#f5ddda",
    "--f7-md-on-surface-variant": "#534341",
    "--f7-md-outline": "#857370",
    "--f7-md-outline-variant": "#d8c2be",
    "--f7-md-inverse-surface": "#362f2e",
    "--f7-md-inverse-on-surface": "#fbeeec",
    "--f7-md-inverse-primary": "#ffb4a8",
    "--f7-md-surface-1": "#fceff2",
    "--f7-md-surface-2": "#fae7eb",
    "--f7-md-surface-3": "#f8e0e3",
    "--f7-md-surface-4": "#f7dde0",
    "--f7-md-surface-5": "#f6d8db",
    "--f7-md-surface-variant-rgb": [245, 221, 218],
    "--f7-md-on-surface-variant-rgb": [83, 67, 65],
    "--f7-md-surface-1-rgb": [252, 239, 242],
    "--f7-md-surface-2-rgb": [250, 231, 235],
    "--f7-md-surface-3-rgb": [248, 224, 227],
    "--f7-md-surface-4-rgb": [247, 221, 224],
    "--f7-md-surface-5-rgb": [246, 216, 219]
  },
  "dark": {
    "--f7-md-primary-shade": "#ff917f",
    "--f7-md-primary-tint": "#ffd7d1",
    "--f7-md-primary-rgb": "255, 180, 168",
    "--f7-md-primary": "#ffb4a8",
    "--f7-md-on-primary": "#690100",
    "--f7-md-primary-container": "#930100",
    "--f7-md-on-primary-container": "#ffdad4",
    "--f7-md-secondary": "#e7bdb6",
    "--f7-md-on-secondary": "#442925",
    "--f7-md-secondary-container": "#5d3f3b",
    "--f7-md-on-secondary-container": "#ffdad4",
    "--f7-md-surface": "#201a19",
    "--f7-md-on-surface": "#ede0dd",
    "--f7-md-surface-variant": "#534341",
    "--f7-md-on-surface-variant": "#d8c2be",
    "--f7-md-outline": "#a08c89",
    "--f7-md-outline-variant": "#534341",
    "--f7-md-inverse-surface": "#ede0dd",
    "--f7-md-inverse-on-surface": "#362f2e",
    "--f7-md-inverse-primary": "#c00100",
    "--f7-md-surface-1": "#2b2220",
    "--f7-md-surface-2": "#322624",
    "--f7-md-surface-3": "#392b29",
    "--f7-md-surface-4": "#3b2c2a",
    "--f7-md-surface-5": "#3f302d",
    "--f7-md-surface-variant-rgb": [83, 67, 65],
    "--f7-md-on-surface-variant-rgb": [216, 194, 190],
    "--f7-md-surface-1-rgb": [43, 34, 32],
    "--f7-md-surface-2-rgb": [50, 38, 36],
    "--f7-md-surface-3-rgb": [57, 43, 41],
    "--f7-md-surface-4-rgb": [59, 44, 42],
    "--f7-md-surface-5-rgb": [63, 48, 45]
  }
}
*/