# @atlaskit/ds-lib 中文文档

规范地址：https://npmcn.com/package/%40atlaskit/ds-lib/

版本：8\.0\.1
npm 元数据更新时间：2026-10-22T03:49:30.215Z
中文译文更新时间：2026-11-07T02:31:34.948Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40atlaskit/ds-lib
原文对照：https://npmcn.com/package/%40atlaskit/ds-lib/?lang=original
项目主页：https://atlaskit.atlassian.com/packages/design-system/ds-lib
源码仓库：https://bitbucket.org/atlassian/atlassian-frontend-mirror

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：102 kB，133 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- peer 依赖：react ^18\.2\.0 \|\| ^19\.0\.0
- 首次发布：2021-04-28T05:50:20.131Z
- 最新版本发布：2026-10-22T03:49:24.862Z
- 近 30 天下载量：6252901（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：49（近 12 个月 7 个）

## 中文简介

可重复使用的公用事业和设计系统专用的车钩.

## 安装

```sh
npm install @atlaskit/ds-lib
```

也可以使用：`pnpm add @atlaskit/ds-lib`、`yarn add @atlaskit/ds-lib`、`bun add @atlaskit/ds-lib`

## README

# DSLib 软件

这是Atlassian设计系统小组使用的具有共同功能的内部软件包。 这个 软件包来时没有支持和组合保证, 如果您直接使用, 您的应用程序会崩溃 !

## 安装

```sh
yarn add @atlaskit/ds-lib
```

## 公用事业

### `noop()`

```tsx
import noop from '@atlaskit/ds-lib/noop';

noop();
```

### `once()`

创建新 `function` 只允许存在 `function` 被调用一次.

```tsx
import once from '@atlaskit/ds-lib/once';

function getGreeting(name: string): string {
    return `Hello ${name}`;
}
const getGreetingOnce = once(getGreeting);

getGreetingOnce('Alex');
// getGreeting called and "Hello Alex" is returned
// "Hello Alex" is put into the cache.
// returns "Hello Alex"

getGreetingOnce('Sam');
// getGreeting is not called
// "Hello Alex" is returned from the cache.

getGreetingOnce('Greg');
// getGreeting is not called
// "Hello Alex" is returned from the cache.
```

注释:

-   如果 `onced` 函数抛出,然后函数的返回值不会被缓存
-   尊重呼叫站点环境( R)`this`) 当执行已确认的函数时

### `warnOnce()`

```tsx
import warnOnce from '@atlaskit/ds-lib/warn-once';

function Component() {
    // Print the warning messagein in the Web console only once per session.
    if (process.env.NODE_ENV !== 'production') {
        warnOnce('This component has been deprecated.');
    }

    return <div>This component has been deprecated</div>;
}
```

### `mergeRefs()`

```tsx
import mergeRefs from '@atlaskit/ds-lib/merge-refs';

const Component = forwardRef((props, ref) => {
  const customRef = useRef<HTMLElement | null>(null);

  return (
    // Use the utility function to merge the forwarded ref
    // with the created ref.
    <div ref={mergeRefs[ref, customRef]} />
  );
}
```

### `device-check`

```tsx
import { isAppleDevice, isSafari } from '@atlaskit/ds-lib/device-check';
isAppleDevice();
isSafari();
```

## 反应钩

### `useLazyRef()`

```tsx
import useLazyRef from '@atlaskit/ds-lib/use-lazy-ref';

function Component({ onClick }) {
    // Initialize the ref
    const ref = useLazyRef(() => {
        /* Return initial data */
    });

    // Access like a normal ref
    return <button onClick={() => onClick(ref.current)}>Click me!</button>;
}
```

### `useControlled()`

```tsx
import useControlled from '@atlaskit/ds-lib/use-controlled';

function ControlledComponent({ value, defaultValue = 0 }) {
    const [uncontrolledState, setUncontrolledState] = useControlled(value, () => defaultValue);
    return <button onClick={() => setUncontrolledState(uncontrolledState + 1)}>Update state</button>;
}
```

### `usePreviousValue()`

```js
function Component() {
    const [currentValue] = useState(1);
    const previousValue = usePreviousValue(currentValue);

    previousValue; // undefined
    currentValue; // 1

    return null;
}
```

### `useStableRef()`

```tsx
function Component({ canShow }: { canShow: () => boolean }) {
    const stableRef = useStableRef({ canShow });

    useEffect(
        () => {
            stableRef.current.canShow();
        },
        // Able to use the last render value of `canShow` without needing
        // to invalidate the effect. Useful for lazy usage of props.
        [],
    );

    return null;
}
```

### `useLazyCallback()`

```tsx
import useLazyCallback from '@atlaskit/ds-lib/use-lazy-callback';

function Component() {
    // `callback` always has the same reference.
    const callback = useLazyCallback(() => {
        // Watch out for its stale closure however!
    });

    return null;
}
```

### `useStateRef()`

```tsx
import useStateRef from '@atlaskit/ds-lib/use-state-ref';

function Component() {
  const [valueRef, setState] = useStateRef(0);

  // Access the latest value, even inside stale closures.
  console.log(valueRef.current);

  // Update state as you would with use state
  return <div onClick={() => setState(prev => prev + 1)} />;
```

### `useScrollbarWidth()`

```tsx
import useScrollbarWidth from '@atlaskit/ds-lib/use-scrollbar-width';

function Component() {
    const scrollbar = useScrollbarWidth();

    return (
        // Use the scrollbar width in your styles/as you wish.
        // The ref should be attached to the scrollable element.
        <div id="container" style={{ padding: scrollbar.width }}>
            <div id="scrollable" ref={scrollbar.ref} />
        </div>
    );
}
```

### `useCloseOnEscapePress()`

**通知 : `useCloseOnEscapePress()` 已贬值,请使用 `useCloseOnEscapePress` 从 `@atlaskit/layering` 换句话说.**

```tsx
import useCloseOnEscapePress from '@atlaskit/ds-lib/use-close-on-escape-press';

// Will callback when escape is pressed
useCloseOnEscapePress({
    onClose: () => {},
    isDisabled: false,
});
```

### `useAutoFocus()`

```tsx
import useAutoFocus from '@atlaskit/ds-lib/use-auto-focus';

const elementRef = useRef();
useAutoFocus(elementRef, true);

<div ref={elementRef} />;
```

## 常见问题

### @atlaskit/ds-lib 是什么？

可重复使用的公用事业和设计系统专用的车钩\.

### 如何安装 @atlaskit/ds-lib？

在项目目录运行 npm install @atlaskit/ds-lib，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @atlaskit/ds-lib 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @atlaskit/ds-lib 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @atlaskit/ds-lib 可以商用吗？

@atlaskit/ds-lib 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @atlaskit/ds-lib 的下载量有多少？

根据 npm 官方下载统计，@atlaskit/ds-lib 在 2026/10/07 – 2026/11/05 这 30 天内被下载 6,252,901 次，日均约 208,430 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @atlaskit/ds-lib 还在维护吗？

最新版本 8\.0\.1 发布于 2026/10/22（16 天前）；至今共发布 49 个版本，其中过去 12 个月发布了 7 个；首次发布于 2021/04/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。