T Comm

引入

import {
  extendUrlParams,
  filterUrlParams,
  formatUrlParams,
  genQueryToStr,
  decode,
  stringifyParams,
  addUrlParam,
  decode,
  stringifyParams,
  addUrlParam,
  addUrlParams,
  keepUrlParams,
  removeUrlParams,
  resolveUrlParams,
  getQueryObj,
  composeUrlQuery,
  encodeUrlParam,
  decodeUrlParam,
  getUrlPara
} from 't-comm';

// 不支持 tree-shaking 的项目
import {
  extendUrlParams,
  filterUrlParams,
  formatUrlParams,
  genQueryToStr,
  decode,
  stringifyParams,
  addUrlParam,
  decode,
  stringifyParams,
  addUrlParam,
  addUrlParams,
  keepUrlParams,
  removeUrlParams,
  resolveUrlParams,
  getQueryObj,
  composeUrlQuery,
  encodeUrlParam,
  decodeUrlParam,
  getUrlPara
} from 't-comm/lib/url/index';

// 只支持 ESM 的项目
import {
  extendUrlParams,
  filterUrlParams,
  formatUrlParams,
  genQueryToStr,
  decode,
  stringifyParams,
  addUrlParam,
  decode,
  stringifyParams,
  addUrlParam,
  addUrlParams,
  keepUrlParams,
  removeUrlParams,
  resolveUrlParams,
  getQueryObj,
  composeUrlQuery,
  encodeUrlParam,
  decodeUrlParam,
  getUrlPara
} from 't-comm/es/url/index';

`extendUrlParams(url, removeKeyArr)`

描述：拼接额外参数

参数：

参数名	类型	描述
url	`string`	地址
removeKeyArr	`string`	待添加的参数对象

返回: 重新拼接的地址

示例

typescript

// 地址是 hash 模式参数
extendUrlParams('http://www.test.com/#/detail?a=1&b=2&c=3', { d: 4 });
// => 'http://www.test.com/#/detail?a=1&b=2&c=3&d=4'

示例

typescript

// 地址 history 模式参数并存
extendUrlParams('http://www.test.com?a=1&b=2&c=3', { d: 4 });
// => 'http://www.test.com/?a=1&b=2&c=3&d=4'

示例

typescript

// 地址 history 模式参数并存 + 强制 history 模式返回
extendUrlParams('http://www.test.com?a=1&b=2&c=3', { d: 4 }, true);
// => 'http://www.test.com/?a=1&b=2&c=3&d=4'

示例

typescript

// hash 模式和 history 模式参数并存
extendUrlParams('http://www.test.com?a=1&b=2&c=3#/detail?d=4', { e: 5 });
// => 'http://www.test.com/#/detail?a=1&b=2&c=3&d=4&e=5'

示例

typescript

// 地址是 hash 模式和 history 模式参数并存，且是多个参数
extendUrlParams('http://www.test.com?d=4&f=6#/detail?a=1&b=2&c=3', { e: 5, g: 7 });
// => 'http://www.test.com/#/detail?d=4&f=6&a=1&b=2&c=3&e=5&g=7'

`filterUrlParams([params])`

描述：根据地址长度，进行过滤地址参数，允许指定保留特定参数

参数：

参数名	类型	默认值	描述
[params]	`object`	`{ limit: 1024 }`	参数
params.url	`number`		待过滤地址，默认当前页面地址
params.limit	`number`		参数长度限制
params.keepKey	`array`		指定保留的参数，比如业务参数、框架参数（登录态、统计上报等）

示例

typescript

// 未超过长度限制，原样返回
filterUrlParams({
  url: 'https://igame.qq.com/?name=mike#/?from=test',
  limit: 600,
  keepKey: ['name'],
});
// => 'https://igame.qq.com/?name=mike#/?from=test'

示例

typescript

// search 参数超长，仅保留 keepKey 指定参数
filterUrlParams({
  url: 'https://igame.qq.com/?name=mike&__lxsdk_params=...(超长)#/?from=test',
  limit: 600,
  keepKey: ['name'],
});
// => 'https://igame.qq.com/#/?name=mike'

示例

typescript

// search 参数超长 + 强制 history 模式返回
filterUrlParams({
  url: 'https://igame.qq.com/?name=mike&__lxsdk_params=...(超长)',
  limit: 600,
  keepKey: ['name'],
  forceHistoryMode: true,
});
// => 'https://igame.qq.com/?name=mike'

示例

typescript

// hash 参数超长
filterUrlParams({
  url: 'https://igame.qq.com/?name=mike#/?name=mike&__lxsdk_params=...(超长)',
  limit: 600,
  keepKey: ['name'],
});
// => 'https://igame.qq.com/#/?name=mike'

示例

typescript

// 参数超长，并且支持识别路径
filterUrlParams({
  url: 'https://igame.qq.com/?name=mike#/detail?name=mike&__lxsdk_params=...(超长)',
  limit: 600,
  keepKey: ['name'],
});
// => 'https://igame.qq.com/#/detail?name=mike'

`formatUrlParams(url, keepParamsObj)`

描述：根据传入的参数，移除原来的所有参数，根据传入的 keepParamsObj 进行重新拼接地址，以 hash 模式返回

参数：

参数名	类型	描述
url	`string`	地址
keepParamsObj	`object`	参数对象

返回: 只有传入参数的地址

示例

typescript

// 地址是 hash 模式参数
formatUrlParams('http://www.test.com/#/detail?a=1&b=2&c=3', { d: 4 });
// => 'http://www.test.com/#/detail?d=4'

示例

typescript

// 地址 history 模式参数并存（默认仍以 hash 模式返回）
formatUrlParams('http://www.test.com?a=1&b=2&c=3', { d: 4 });
// => 'http://www.test.com/?d=4'

示例

typescript

// hash 模式和 history 模式参数并存
formatUrlParams('http://www.test.com?a=1&b=2&c=3#/detail?d=4', { e: 5 });
// => 'http://www.test.com/#/detail?e=5'

示例

typescript

// 地址是 hash 模式和 history 模式参数并存，且是多个参数
formatUrlParams('http://www.test.com?d=4&f=6#/detail?a=1&b=2&c=3', { e: 5, g: 7 });
// => 'http://www.test.com/#/detail?e=5&g=7'

示例

typescript

// 子工程是 history 模式（forceHistoryMode = true）
formatUrlParams('http://www.test.com?a=1&b=2&c=3', { d: 4 }, true);
// => 'http://www.test.com/?d=4'

`genQueryToStr([query])`

描述：将参数对象转换为 query 字符串（不进行 URL 编码）

参数：

参数名	类型	默认值	描述
[query]	`Record.<string, (string\|number)>`	`{}`	参数对象

返回: string

拼接后的 query 字符串

示例

typescript

genQueryToStr({ a: 1, b: 2 }); // => 'a=1&b=2'

`decode(str)`

描述：多重解码。避免内嵌在外部时地址参数被编码，先进行URL解码再进行HTML字符实体解码

Docgen:
参数：

参数名	类型	描述
str	`string`	文本

返回: 解码后的文本

示例

typescript

decode('') // => ''

示例

typescript

decode() // => ''

示例

typescript

decode('hello%20world') // => 'hello world'

示例

typescript

// 同时进行 URL 解码和 HTML 实体（&amp;）解码
decode('a%3D1%26amp%3Bb%3D2') // => 'a=1&b=2'

示例

typescript

decode('hello') // => 'hello'

`stringifyParams(params)`

描述：将参数对象转成字符串

Docgen:
参数：

参数名	类型	描述
params	`Object`	参数对象

示例

typescript

stringifyParams({}) // => ''

示例

typescript

stringifyParams({ a: '1' }) // => 'a=1'

示例

typescript

stringifyParams({ a: '1', b: '2' }) // => 'a=1&b=2'

示例

typescript

stringifyParams({ page: 1, size: 10 }) // => 'page=1&size=10'

`addUrlParam(url, key, value)`

描述：小程序不支持URL对象，用字符串拼接方式添加注意：已有相同key不支持覆盖，会重复添加

Docgen:
参数：

参数名	描述
url	输入url
key	键
value	值

示例

typescript

// url 无参数时用 ? 连接
addUrlParam('https://example.com', 'a', '1') // => 'https://example.com?a=1'

示例

typescript

// url 已有参数时用 & 连接
addUrlParam('https://example.com?x=1', 'a', '1') // => 'https://example.com?x=1&a=1'

`decode(str)`

描述：多重解码。避免内嵌在外部时地址参数被编码，先进行URL解码再进行HTML字符实体解码

Docgen:
参数：

参数名	类型	描述
str	`string`	文本

返回: 解码后的文本

示例

typescript

decode('') // => ''

示例

typescript

decode() // => ''

示例

typescript

decode('hello%20world') // => 'hello world'

示例

typescript

// 同时进行 URL 解码和 HTML 实体（&amp;）解码
decode('a%3D1%26amp%3Bb%3D2') // => 'a=1&b=2'

示例

typescript

decode('hello') // => 'hello'

`stringifyParams(params)`

描述：将参数对象转成字符串

Docgen:
参数：

参数名	类型	描述
params	`Object`	参数对象

示例

typescript

stringifyParams({}) // => ''

示例

typescript

stringifyParams({ a: '1' }) // => 'a=1'

示例

typescript

stringifyParams({ a: '1', b: '2' }) // => 'a=1&b=2'

示例

typescript

stringifyParams({ page: 1, size: 10 }) // => 'page=1&size=10'

`addUrlParam(url, key, value)`

描述：小程序不支持URL对象，用字符串拼接方式添加注意：已有相同key不支持覆盖，会重复添加

Docgen:
参数：

参数名	描述
url	输入url
key	键
value	值

示例

typescript

// url 无参数时用 ? 连接
addUrlParam('https://example.com', 'a', '1') // => 'https://example.com?a=1'

示例

typescript

// url 已有参数时用 & 连接
addUrlParam('https://example.com?x=1', 'a', '1') // => 'https://example.com?x=1&a=1'

`addUrlParams(url, params, [shouldOverride])`

描述：为url添加参数

参数：

参数名	类型	默认值
url	`string`
params	`object`
[shouldOverride]	`boolean`	`false`

示例

typescript

// 向 url 添加多个参数
addUrlParams('https://example.com', { a: '1', b: '2' })
// => 'https://example.com?a=1&b=2'

示例

typescript

// shouldOverride=false（默认）时，不会覆盖已有参数
addUrlParams('https://example.com?a=old', { a: 'new' }, false)
// => 'https://example.com?a=old'

示例

typescript

// shouldOverride=true 时，会覆盖已有参数
addUrlParams('https://example.com?a=old', { a: 'new' }, true)
// => 'https://example.com?a=new'

示例

typescript

// 保留 hash 部分
addUrlParams('https://example.com#section', { a: '1' })
// => 'https://example.com?a=1#section'

示例

typescript

// url 无参数时正确添加参数
addUrlParams('https://example.com', { key: 'val' })
// => 'https://example.com?key=val'

`keepUrlParams(url, removeKeyArr)`

描述：除保留参数外，一律移除

参数：

参数名	类型	描述
url	`string`	地址
removeKeyArr	`string`	待保留的参数名集合

返回: 重新拼接的地址

示例

typescript

// 地址是 hash 模式参数
keepUrlParams('http://www.test.com/#/detail?a=1&b=2&c=3', ['a', 'b']);
// => 'http://www.test.com/#/detail?a=1&b=2'

示例

typescript

// 地址 history 模式参数并存
keepUrlParams('http://www.test.com?a=1&b=2&c=3', ['a', 'b']);
// => 'http://www.test.com/?a=1&b=2'

示例

typescript

// 地址 history 模式参数并存 + 强制 history 模式返回
keepUrlParams('http://www.test.com?a=1&b=2&c=3', ['a', 'b'], true);
// => 'http://www.test.com/?a=1&b=2'

示例

typescript

// hash 模式和 history 模式参数并存
keepUrlParams('http://www.test.com?a=1&b=2&c=3#/detail?d=4', ['a', 'd']);
// => 'http://www.test.com/#/detail?a=1&d=4'

示例

typescript

// 地址是 hash 模式和 history 模式参数并存，且是多个参数
keepUrlParams('http://www.test.com?d=4&f=6#/detail?a=1&b=2&c=3', ['a', 'd']);
// => 'http://www.test.com/#/detail?d=4&a=1'

`removeUrlParams(url, removeKeyArr)`

描述：移除参数

参数：

参数名	类型	描述
url	`string`	地址
removeKeyArr	`string`	待移除的参数名集合

返回: 重新拼接的地址

示例

typescript

// 地址是 hash 模式参数
removeUrlParams('http://www.test.com/#/detail?a=1&b=2&c=3', ['a', 'b']);
// => 'http://www.test.com/#/detail?c=3'

示例

typescript

// 地址 history 模式参数并存
removeUrlParams('http://www.test.com?a=1&b=2&c=3', ['a', 'b']);
// => 'http://www.test.com?c=3'

示例

typescript

// 地址 history 模式参数并存 + 强制 history 模式返回
removeUrlParams('http://www.test.com?a=1&b=2&c=3', ['a', 'b'], true);
// => 'http://www.test.com?c=3'

示例

typescript

// 全部参数移除完，返回不带 query 的地址
removeUrlParams('http://www.test.com?a=1&b=2&c=3', ['a', 'c', 'b'], true);
// => 'http://www.test.com'

示例

typescript

// hash 模式下 query 全部移除，会保留末尾的 ?
removeUrlParams('http://www.test.com?a=1&b=2&c=3#/detail?d=4', ['a', 'b', 'c', 'd']);
// => 'http://www.test.com/#/detail?'

示例

typescript

// hash 模式和 history 模式参数并存
removeUrlParams('http://www.test.com?a=1&b=2&c=3#/detail?d=4', ['a', 'd']);
// => 'http://www.test.com/#/detail?b=2&c=3'

示例

typescript

// 地址是 hash 模式和 history 模式参数并存，且是多个参数
removeUrlParams('http://www.test.com?d=4&f=6#/detail?a=1&b=2&c=3', ['a', 'd']);
// => 'http://www.test.com/#/detail?f=6&b=2&c=3'

`resolveUrlParams([url], [key])`

描述：提取链接参数，兼容hash模式和history模式，以及拼接异常情况

参数：

参数名	类型	默认值	描述
[url]	`string`	`"''"`	地址
[key]	`string`	`"''"`	可选，若不为空，则提取返回该key对应的参数值

返回: 地址参数对象，或者是指定参数值

示例

typescript

// 地址使用 search 参数
resolveUrlParams('https://igame.qq.com?name=mike&age=18');
// => { name: 'mike', age: '18' }

示例

typescript

// 地址使用 hash 参数
resolveUrlParams('https://igame.qq.com#/?from=china&home=china');
// => { from: 'china', home: 'china' }

示例

typescript

// 地址同时使用 search 和 hash 参数
resolveUrlParams('https://igame.qq.com?name=mike&age=18#/index?from=china&home=china');
// => { from: 'china', home: 'china', name: 'mike', age: '18' }

示例

typescript

// 通过 key 直接取值
resolveUrlParams('https://igame.qq.com?name=mike&age=18', 'age');
// => '18'

示例

typescript

// 空 url 时：未传 key 返回 {}，传 key 返回 undefined
resolveUrlParams('');         // => {}
resolveUrlParams('', 'age');  // => undefined

示例

typescript

// 兼容真实业务地址中带 %3F、&amp; 等异常拼接情况
resolveUrlParams('https://igame.qq.com/x.html#/index?brandid=b1662364289&amp%3BmultiCfgId=b16623642891663309541');
// => { brandid: 'b1662364289' }

`getQueryObj(url)`

描述：url参数变对象

参数：

参数名	类型	描述
url	`string`	输入URL

返回: Object

search对象

示例

typescript

// 完整 url
getQueryObj('https://igame.qq.com?name=mike&age=18&feel=cold&from=china');
// => { name: 'mike', age: '18', feel: 'cold', from: 'china' }

示例

typescript

// 仅传入 query 字符串（不含 ?）也能解析
getQueryObj('name=mike&age=18&feel=cold&from=china');
// => { name: 'mike', age: '18', feel: 'cold', from: 'china' }

`composeUrlQuery(url, queryObj)`

描述：组装url参数，将search参数添加在后面

参数：

参数名	类型	描述
url	`string`	输入URL
queryObj	`Object`	search对象

返回: string

组装后的url

示例

typescript

// url 本身无 query 参数
composeUrlQuery('https://baidu.com', {
  name: 'mike',
  feel: 'cold',
  age: '18',
  from: 'test',
});
// => 'https://baidu.com?name=mike&feel=cold&age=18&from=test'

示例

typescript

// url 已有 query 参数，会与新参数合并
composeUrlQuery('https://baidu.com?gender=male', {
  name: 'mike',
  feel: 'cold',
  age: '18',
  from: 'test',
});
// => 'https://baidu.com?gender=male&name=mike&feel=cold&age=18&from=test'

`encodeUrlParam(obj)`

描述：将对象字符串化

参数：

参数名	类型	描述
obj	`object`	输入对象

返回: string

字符串

示例

typescript

// 编码普通对象
encodeUrlParam({ a: 1 });
// => '%7B%22a%22%3A1%7D'

示例

typescript

// 编码空对象
encodeUrlParam({});
// => '%7B%7D'

示例

typescript

// 编码嵌套对象（等价于 encodeURIComponent(JSON.stringify(obj))）
encodeUrlParam({ name: 'mike', info: { age: 18 } });

示例

typescript

// 编码数组
encodeUrlParam([1, 2, 3]);
// => encodeURIComponent('[1,2,3]')

示例

typescript

// 编码含中文的对象
encodeUrlParam({ name: '张三' });
// => encodeURIComponent(JSON.stringify({ name: '张三' }))

`decodeUrlParam(obj)`

描述：将字符串解码，与encodeUrlParam相对

参数：

参数名	类型	描述
obj	`string`	输入字符串

返回: object

对象

示例

typescript

// 解码普通对象
decodeUrlParam('%7B%22a%22%3A1%7D');
// => { a: 1 }

示例

typescript

// 解码空对象
decodeUrlParam('%7B%7D');
// => {}

示例

typescript

// 解码嵌套对象
const encoded = encodeURIComponent(JSON.stringify({ name: 'mike', info: { age: 18 } }));
decodeUrlParam(encoded);
// => { name: 'mike', info: { age: 18 } }

示例

typescript

// 无效字符串返回空对象
decodeUrlParam('invalid-string');
// => {}

示例

typescript

// encode 和 decode 互逆
decodeUrlParam(encodeUrlParam({ name: 'mike', age: 18, list: [1, 2] }));
// => { name: 'mike', age: 18, list: [1, 2] }

`getUrlPara(paraName, search)`

描述：获取 Url 参数

参数：

参数名	类型	描述
paraName	`string`	参数 key
search	`string`	url search 部分

返回: paraValue

示例

typescript

getUrlPara('gender', '?gender=male&name=mike&feel=cold&age=18&from=test');
// => 'male'

示例

typescript

getUrlPara('from', '?gender=male&name=mike&feel=cold&age=18&from=test');
// => 'test'

示例

typescript

getUrlPara('age', '?gender=male&name=mike&feel=cold&age=18&from=test');
// => '18'

示例

typescript

// 不存在的 key 返回空字符串
getUrlPara('other', '?gender=male&name=mike&feel=cold&age=18&from=test');
// => ''

示例

typescript

// 未传 search 且环境不存在 location 时，返回空字符串
getUrlPara('other');
// => ''

引入 ​

extendUrlParams(url, removeKeyArr) ​

filterUrlParams([params]) ​

formatUrlParams(url, keepParamsObj) ​

genQueryToStr([query]) ​

decode(str) ​

stringifyParams(params) ​

addUrlParam(url, key, value) ​

decode(str) ​

stringifyParams(params) ​

addUrlParam(url, key, value) ​

addUrlParams(url, params, [shouldOverride]) ​

keepUrlParams(url, removeKeyArr) ​

removeUrlParams(url, removeKeyArr) ​

resolveUrlParams([url], [key]) ​

getQueryObj(url) ​

composeUrlQuery(url, queryObj) ​

encodeUrlParam(obj) ​

decodeUrlParam(obj) ​

getUrlPara(paraName, search) ​

引入

`extendUrlParams(url, removeKeyArr)`

`filterUrlParams([params])`

`formatUrlParams(url, keepParamsObj)`

`genQueryToStr([query])`

`decode(str)`

`stringifyParams(params)`

`addUrlParam(url, key, value)`

`decode(str)`

`stringifyParams(params)`

`addUrlParam(url, key, value)`

`addUrlParams(url, params, [shouldOverride])`

`keepUrlParams(url, removeKeyArr)`

`removeUrlParams(url, removeKeyArr)`

`resolveUrlParams([url], [key])`

`getQueryObj(url)`

`composeUrlQuery(url, queryObj)`

`encodeUrlParam(obj)`

`decodeUrlParam(obj)`

`getUrlPara(paraName, search)`