工具集(utils)

Framework7 utils是一组在开发过程中内部使用的辅助方法，非常方便。

它作为Framework7类的utils属性（Framework7.utils）和初始化的应用实例的相同属性（app.utils）可用。

// 如果我们需要在没有访问应用程序实例或在初始化应用程序之前的地方使用它
var now = Framework7.utils.now();


// 我们初始化应用程序之后，我们可以将其作为应用程序实例属性访问
var app = new Framework7({ /*...*/ });
var now = app.utils.now();

它也可以使用ES模块导入：

import { utils } from 'framework7';

Utils Methods

`parseUrlQuery()`

app.utils.parseUrlQuery(url)- parse url query get parameters

url - string - url with GET parameters. Required.

Method returns object with query parameters

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

`serializeObject()`

app.utils.serializeObject(object)- Create a serialized representation of a plain object suitable for use in a URL query string

object - object - Object to serialize

returns a new unique array

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

`requestAnimationFrame()`

app.utils.requestAnimationFrame(callback)- Cross-browser implementation on requestAnimationFrame

callback - function - function to call when it's time to update your animation for the next repaint

returns animation request id, that uniquely identifies the entry in the callback list

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)- Cancels an animation frame request

requestID - number - The ID value returned by the call to app.utils.requestAnimationFrame() that requested the callback

app.utils.cancelAnimationFrame(animId);

`nextFrame()`

app.utils.nextFrame(callback)- Executes code on next available animation frame.

callback - string - function to call when it's time to update your animation for the next repaint.

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

`nextTick()`

app.utils.nextTick(callback, delay)- executes code after required delay. Basically alias for setTimeout

callback - string - function to call after specified delay
delay - number - delay in ms. Optional, by deault is 0

returns timeout ID

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

`now()`

app.utils.now()- returns current timestamp in ms

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)- extends target object with properties and methods from from objects

target - object - target object to extend
from - object - objects to copy properties and methods from

returns target object with extended properties and methods

This method becomes very handy if you need to extend one object with properties of others or when you need a deep copy of an object.

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()- returns unique number, increased by 1 with every call

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

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

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

`id()`

app.utils.id(mask, map)- generates random ID-like string

mask - string - ID string mask, by default is xxxxxxxxxx
map - string - characters that will be used for generation, by default is 0123456789abcdef

returns randomly generated string

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

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

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

`preloaderContent`

There are properties that contain theme-related (iOS, MD) content of Preloader element. Theses properties can be useful if you create preloaders dynamically.

app.utils.iosPreloaderContent- contains required preloader inner content (HTML string) for iOS theme

app.utils.mdPreloaderContent- contains required preloader inner content (HTML string) for MD theme

// 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)- converts HEX color to RGB color

hexColor - string - HEX color string

returns [R, G, B] array

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

`colorRgbToHex()`

app.utils.colorRgbToHex(R, G, B)- converts RGB color to HEX color

R - number - red value (0 - 255)
G - number - green value (0 - 255)
B - number - blue value (0 - 255)

returns HEX color string

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

`colorRgbToHsl()`

app.utils.colorRgbToHsl(R, G, B)- converts RGB color to HSL color

R - number - red value (0 - 255)
G - number - green value (0 - 255)
B - number - blue value (0 - 255)

returns [H, S, L] array

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

`colorHslToRgb()`

app.utils.colorHslToRgb(H, S, L)- converts HSL color to RGB color

H - number - hue value (0 - 360)
S - number - saturation value (0 - 1)
L - number - lightness value (0 - 1)

returns [R, G, B] array

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

`colorHsbToHsl()`

app.utils.colorHsbToHsl(H, S, B)- converts HSB(V) color to HSL color

H - number - hue value (0 - 360)
S - number - saturation value (0 - 1)
B - number - brightness value (0 - 1)

returns [H, S, L] array

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

`colorHslToHsb()`

app.utils.colorHslToHsb(H, S, L)- converts HSL color to HSB(V) color

H - number - hue value (0 - 360)
S - number - saturation value (0 - 1)
L - number - lightness value (0 - 1)

returns [H, S, B] array

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

`colorThemeCSSProperties()`

app.utils.colorThemeCSSProperties(hexColor)- returns object with generate CSS variables required to set specified theme color

hexColor - string - HEX color string

returns object with required CSS variables and their values.

app.utils.colorThemeCSSProperties(R, G, B)- returns object with generate CSS variables required to set specified theme color

R - number - red value
G - number - green value
B - number - blue value

returns object with required CSS variables and their values.

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]
  }
}
*/