@ canonical/ ds- utils
Pragma设计系统的框架-不可知性帮助者。 这些是设计系统本身组件所建的公用事业——导航-树木逻辑,一个用于URL查询的端口,速率限制和数字格式化——同样由React和Svelte执行共享.
对于没有设计系统含义的通用字符串和断言助手(casing, (中文(简体) ), invariant, (中文(简体) ), indent, (中文(简体) ), join,参见 @canonical/utils。 。 。 .
安装
bun add @canonical/ds-utils
可用函数
导航
设计系统的导航组件背后有树扶手和减手——面包屑,上下文菜单,侧向导航. 他们运行在 Item 类型来源 @canonical/ds-types。 。 。 .
import { annotateTree, getItemId, prepareIndex } from "@canonical/ds-utils";
// `root` is a single Item whose children hang off `root.items`.
const tree = annotateTree(root); // adds parentUrl and depth to every node
const index = prepareIndex(tree); // O(1) lookup by url or key
const id = getItemId(root); // the item's url, else its key
该模块还输出 resolveOrientation, (中文(简体) ), findAncestorPath, (中文(简体) ), getParentItem, (中文(简体) ),
getFirstInteractiveChild, (中文(简体) ), getLastInteractiveChild, (中文(简体) ), isInteractive 财务报告和审定财务报表
createNavigationReducer,加上导航动作和定向类型.
每件物品的编号——它的 url,否则 key ——必须在树上独有.
共享一个ID的两个项目是合同外输入:只有一个可以占用索引
插槽, 因此后面的条目获胜, 前面的则无法从查看中获取
(它永远无法被标记为当前). prepareIndex 开发中的警告
当它探测到这种相撞时; 生产是沉默的,并且保持不变
最后的写成行为.
地点
createLocationQuery 提供了读取和写入 URL 查询的一个组件方式, 无论路由器拥有 URL 。 它需要一个 LocationAdapter (单位:千美元)getLocation, (中文(简体) ), navigate 财务报告和审定财务报表 subscribe返回 a LocationQuery (单位:千美元)read, (中文(简体) ), write 财务报告和审定财务报表 subscribe) (中文(简体) ). 这些类型来自 @canonical/ds-types。重复的参数在读取和写作中存活下来.
import { createLocationQuery } from "@canonical/ds-utils";
import { createBrowserAdapter } from "@canonical/router-core";
// router-core's adapters fit by shape.
const query = createLocationQuery(createBrowserAdapter());
const params = query.read(); // a fresh URLSearchParams
params.set("page", "2");
query.write(params); // replaces the current history entry
query.write(params, { history: "push" }); // appends an entry instead
const unsubscribe = query.subscribe(() => render(query.read()));
另一个路由器通过包接自己的三个功能相匹配:
const query = createLocationQuery({
getLocation: () => router.currentHref,
navigate: (url, options) => router.go(url, { replace: options?.replace }),
subscribe: (listener) => router.onChange(listener),
});
在服务器上,路由器核心 createServerAdapter 读取一个请求. write 扔到那里, 因为服务器适配器无法导航 .
import { createServerAdapter } from "@canonical/router-core";
const query = createLocationQuery(createServerAdapter(request.url));
每个适配器一次创建端口,而不是每次渲染,因为每次调用都会返回新的功能. write 序列编号与 URLSearchParams.toString()因此空间变成 +。 。 。 . read 解码,所以编码无法到达消费者.
弹跳
创建一个已取消的版本的函数,该版本将等待自执行前最后一次调用以来指定的延迟通过。 可用于搜索输入,调整处理器大小等高频事件.
import { debounce } from "@canonical/ds-utils";
const debouncedSearch = debounce(async (query: string) => {
const response = await fetch(`/api/search?q=${query}`);
return response.json();
}, 300);
// Multiple rapid calls result in only one execution
debouncedSearch("hello").then(console.log); // Superseded by the next call
debouncedSearch("hello w").then(console.log); // Superseded by the next call
debouncedSearch("hello world").then(console.log); // Executes after 300ms
// Cancel a pending execution
debouncedSearch("query");
debouncedSearch.cancel(); // `cancel` lives on the debounced function
取消的函数返回一个承诺并有一个 cancel 方法. cancel 是一个
功能的属性,而不是它返回的许诺,它只会澄清
等待定时器——取消电话的承诺永远不会实现。 每个新电话
清空等待的定时器,所以只有最后的电话在爆炸中解决——一个被取代的
承诺永远不会解决, 这就是为什么上面的例子使用 .then 而不是说
await。 。 。 .
节流阀
费率限制一个函数,所以拨打电话需要一次。 后边的呼叫点火:一旦呼叫停止 wait 上个数后毫秒. 可用于卷轴处理器,连续输入事件,和限速操作.
import { throttle } from "@canonical/ds-utils";
const throttledResize = throttle(() => {
console.log("Window resized");
}, 500);
window.addEventListener("resize", throttledResize);
// Logs once, 500ms after the resizing stops
人数
以适当的单位后缀和精度来格式化人类可读性的数字。 它返回一个 HumanizeResult ——要显示的字符串,原值,以及被应用的单位——因此,一个呼叫者可以将单位单独制成,比如在aria-label中.
import { humanizeNumber } from "@canonical/ds-utils";
humanizeNumber(1234); // { displayValue: "1.2k+", value: 1234, unit: "k" }
humanizeNumber(1500000); // { displayValue: "1.5M", value: 1500000, unit: "M" }
数值被切入到三个字符,以及 overflowIndicator (单位:千美元)"+" 以
默认值),在切换失去精度时附加. 单位
倾角基数和溢出指标均可通过
HumanizeNumberOptions。 。 。 .
复数化
返回基于计数的单数或复数形式。 没有选项,它就会复数 "item";仅有 singular 附加一个 s。 。 。 .
import { pluralize } from "@canonical/ds-utils";
pluralize(1); // "item"
pluralize(5); // "items"
pluralize(1, { singular: "box", plural: "boxes" }); // "box"
pluralize(3, { singular: "box", plural: "boxes" }); // "boxes"
全欧尼
一组字段必须一起提供或根本不提供的道具类型助手 .
import type { AllOrNone } from "@canonical/ds-utils";
type Example = AllOrNone<{ a: string; b: number }>;
const both: Example = { a: "hello", b: 42 }; // OK
const neither: Example = {}; // OK
const partial: Example = { a: "hello" }; // Error
设计哲学
函数仅在对多个软件包证明有用后才输入此软件包 。 预先抽象被积极避免. 如果一个工具仅在一个地方需要,它就属于该套件,直到出现第二个使用情况.
每个函数都附有综合的TSDoc评论。 软件包唯一的依赖性是 @canonical/ds-types,它单独使用类型,所以它不会增加自身运行时间重量.