The functions of the laboratory are only works in the next version, you can use npm i dumi@next to install the experimental version for experience; The experimental functions are unstable, please do not use it in production; If you have any suggestions, welcome to feedback and exchanges in the discussion group ❤

Develop mobile library

Dependent versions:dumi@1.1.0-beta.18+ & dumi-theme-mobile

It is easy to use, just make sure you are using the beta version of dumi, and have been installed the dumi-theme-mobile into your dependencies, then dumi will switch to the mobile library development mode. This mode includes the following features:

  1. Mobile simulated container with CSS sticky + iframe embedded demo
  2. Auto-enable rem ability (Base on 750 mode of umi-hd)
  3. QRCode for preview on the real device
Mobile theme preview

Motions

Dependent version:dumi@1.1.0-beta.13+

The name has not been thought out yet, it can be understood as a Demo action. If the developer writes motions in advanced when writing a Demo, for example, write it like this:

/**
* motions:
* - click:[data-action="addon"]
* - timeout:1000
* - click:[data-action="addon"]
* - timeout:1000
* - click:[data-action="reset"]
*/
import React, { useState } from 'react';
export default () => {
const [count, setCount] = useState(0);
return (
<>
<p>{count}</p>
<button type="button" data-action="addon" onClick={() => setCount(count + 1)}>
add
</button>
<button type="button" data-action="reset" onClick={() => setCount(0)}>
reset
</button>
</>
);
};

You will get the following Demo, try to click the play button on the operation bar, the motions predefined by developer will be executed in sequence:

0

Currently supports the following motion syntax:

  • autoplay: The motion will be executed automatically in the first place, and loop will be supported in the future
  • click:selector: here is a CSS selector, which is used to click on a selector
  • timeout:number: here is a number, which is used to wait for a time before executing the next step, such as waiting for the transition animation to complete
  • capture:selector: here is a CSS selector, which is used for postMessage. This selector can be extended in the future in combination with snapshots and other scenarios. The content of the message data sent is like:
    { type: 'dumi:capture-element', value: 'selector' }

Custom theme

Dependent version:dumi@1.1.0-beta.7+

Development

Directory Structure

Method one, Create a package starting with dumi-theme- or @group/dumi-theme-, here takes a theme using the default as an example:

.
├── package.json
└── src
├── builtins # [Convention] Built-in component folder, dumi will look for `j|tsx` in **first-level directory** to mount, the components in this folder can be used directly in md
├── components # [Non-Convention] The components extracted by the theme package in this folder. The folder name is customized by the developer
├── layout.tsx # [Convention] You can custom your own layout component, props.children is the content of each markdown, developers can control the navigation, sidebar and content rendering by themselves
├── layouts # [Convention] A custom layouts directory, used when you need to customize multiple layouts
│ ├── index.tsx # [Convention] Same as src/layout.tsx, choose one of the two methods, layout.tsx has higher priority
│ └── demo.tsx # [Convention] Separate route (~demos/:uuid) layout for custom component demo
└── style # [Non-Convention] Theme package style sheet

Here, [Convention] means a necessary structure for the theme package, and [Non-Convention] means that developers can control according to their own habits.

Method two, create a .dumi/theme folder in the local project, consider this folder as the src directory above, and write a custom theme directly, for example, create .dumi/theme/layout.tsx to customize the layout; This method is suitable for theme packages that do not need to be released, which is easier to debug.

Component Guarantee

It supports components that partially cover the official theme. If the theme package is not provided in builtins, dumi will guarantee to the default theme Previewer component. The components that will be guaranteed are as follows:

  1. Previewer.tsx - For demo wrapper
  2. SourceCode.tsx - For code block and highlighting it
  3. Alert.tsx - For alert box
  4. Badge.tsx - For badge

In addition, layout.tsx (or layouts/index.tsx) will also be guaranteed. If you only want to control the rendering of the text area, you can choose to wrap the layout of the default theme, and code the children of layout to achieve. For example, add a feedback button to the text area:

// src/layout.tsx
import React from 'react';
import Layout from 'dumi-theme-default/src/layout';
export default ({ children, ...props }) => (
<Layout {...props}>
<>
<button>feedback</button>
{children}
</>
</Layout>
);

Theme API

In order to customize the theme, dumi provides a set of theme APIs, you can import the following from dumi/theme:

  1. context - You can get the configurations of dumi, meta information of the current route, international language options, etc. The detailed definition of the context can be viewd source code
  2. Link - The wrapped umi Link can render external links
  3. NavLink - The wrapped umi NavLink can render external links
  4. AnchorLink - The wrapped umi NavLink can be used for links with anchor points, and can be highlighted
  5. useCodeSandbox - Generate a function based on the props of Previewer, and open the demo in codesandbox.io
  6. useCopy - Provide copy function and copy status to achieve to copy source code
  7. useSearch - Automatically provide algolia binding functions according to configuration or return search results according to keywords
  8. useLocaleProps - Automatically filter props according to locale to achieve to the definition of international frontmatter. For example, title.zh-CN will be converted to title in Chinese language
  9. useDemoUrl - Get the single demo page url via demo identifier, for example, useDemoUrl(props.identifier) may return like http://example.com/~demos/demo-id.

Debug and usage

If the developed theme package is a npm package, take the developed theme package npm link (debugging) or npm install (used) into the project, and make sure that it is declared in devDependencies or dependencies, dumi will automatically mount this theme, for example:

{
"dependencies": {
"dumi-theme-default": "0.0.0"
}
}

If the developed theme package is in the form of the .dumi/theme directory, dumi will automatically mount it and you can debug directly.

Use with Umi UI

Dependent versions:dumi@1.1.0-beta.0+ & @umijs/preset-ui@2.2.0+

The usage process is shown in the figure below:

Usage

1. Initialize the dumi component to develop project

$ mkdir dumi-lib && cd dumi-lib
$ npx @umijs/create-dumi-lib

2. Add asset meta information for Demo

Take the demo of the getting-started project as an example, open src/Foo/index.md and add the following frontmatter configuration:

// src/Foo/index.md
```jsx
+ /**
+ * title: Foo Demo
+ * thumbnail: [The url of thumbnail]
+ */
import React from 'react';
import { Foo } from 'dumi-lib';
export default () => <Foo title="First Demo" />;
```

In addition to writing frontmatter in the source code, adding attributes to the code tag of the external Demo can also add meta information:

<code src="/path/to/demo.tsx" title="Demo title" thumbnail="the url of thumbnail" />

3. Enable metadata generation capabilities

Add an script to package.json and declare the dumiAssets field, Umi UI will find asset metadata files based on this field:

{
"scripts": {
+ "postversion": "dumi assets"
},
+ "dumiAssets": "assets.json"
}

Since assets.json does not need to control versions , please add assets.json to gitignore.

4. Build and generate asset metadata

If it is just for testing, you can use npm version instead of npm publish, and then use link for testing:

$ npm run build
$ npm version patch -m "build: bump version to %s"

5. Use in Umi UI

Initialize the Umi application, install Umi UI and link the component library we just made:

$ mkdir umi-app && cd umi-app
$ npx @umijs/create-dumi-app
$ npm i @umijs/preset-ui -D
$ npm link path/to/dumi/lib

In the package.json of the Umi application, manually add the component library as a dependency:

{
"dependencies": {
// other dependencies
+ "your-lib-package-name": "*"
}
}

Then start the Umi project as usual, you can see the Demo assets in the dumi-lib project in the floating bubble of Umi UI, and can be directly inserted into the page for using: