Nudges Web

React 18 supported Nudges Component.

Development

npm install
npm start
open http://localhost:8000

Feature

• React life cycle support Nudges component

Install

npm i @digitalc/nudges

Usage

import { Nudges } from '@digitalc/nudges';

const Demo = () => {

  // 或者不用 useRef ，传一个唯一标识 来获取 DOM 元素。
  const createBtnRef = useRef<HTMLButtonElement>(null);
  const updateBtnRef = useRef<HTMLButtonElement>(null);
  const deleteBtnRef = useRef<HTMLButtonElement>(null);
  // 如果调用方有自己的逻辑
  const [isTourActive, setIsTourActive] = useState(true);

  useEffect(() => {
      if (isTourActive) {
      // 启动并注册一个 Nudges
      const stopTourFunction = Nudges('Nudges-container', {
        closeIcon:'关闭',
        defaultCurrent: 0,
        animated: true,
        arrow: true,
        steps: [
          {
            title: '创建',
            description: '创建一条数据',
            target: () => document.getElementById('testNudge'),
            mask: true,
          },
          {
            title: '更新',
            mask: false,
            // target: () => updateBtnRef.current,
            // target: () =>  document.getElementsByClassName('testNudge2')[0],
            target: () => document.querySelector('[data-cee-id="testNudge2"]'),
            description: (
              <div>
                <span>更新一条数据</span>
                <button>帮助文档</button>
                <img
                alt="Nudges.png"
                width={100}
                src="https://user-images.githubusercontent.com/5378891/197385811-55df8480-7ff4-44bd-9d43-a7dade598d70.png"
              />
              </div>
            ),
            cover: (
              <img
                alt="Nudges.png"
                src="https://user-images.githubusercontent.com/5378891/197385811-55df8480-7ff4-44bd-9d43-a7dade598d70.png"
              />
            ),
          },
          {
            title: '删除',
            description: (
              <div>
                <span>危险操作：删除一条数据</span>
                <button>帮助文档</button>
              </div>
            ),
            // target: () => deleteBtnRef.current,
            target: () =>  document.getElementById('testNudge3'),
            mask: {
              style: {
                boxShadow: 'inset 0 0 15px #fff',
              },
              color: 'rgba(243, 23, 3, 0.78)',
            },
          },
        ],
        props: { text: 'Default text' },
        onChange: (current, next) => {
          console.log('onChange', current, next);
        },
        onFinish: () => {
          console.log('onFinish');
        }
      });
      // 清理函数，用于组件卸载时停止 Nudges
      return () => {
        console.log("🚀 ~ 清理函数，用于组件卸载时停止 Nudges:")
        stopTourFunction(); // 停止 Nudges
      };
    }
  }, [isTourActive]);


   // 处理点击事件来启动和停止 Nudges
 const handleToggleTour = () => {
  setIsTourActive(!isTourActive);
};

    return (
        <div style={{ margin: 20 }}>
            <div>
                <button
                    className="ant-target"
                    id="testNudge"
                    // ref={createBtnRef}
                    style={{ marginLeft: 100 }}
                >
                    Create1
                </button>
                {/* <div style={{ height: 200 }} /> */}
                <button
                    className="ant-target testNudge2"
                    // ref={updateBtnRef}
                    id="testNudge2"
                >
                    Update2
                </button>

                <img
                    data-cee-id="testNudge2"
                    alt="tour.png"
                    width={400}
                    height={100}
                    src="https://user-images.githubusercontent.com/5378891/197385811-55df8480-7ff4-44bd-9d43-a7dade598d70.png"
                />
                <button
                    className="ant-target"
                    // ref={deleteBtnRef}
                    id="testNudge3"
                >
                    Delete3
                </button>
                </div>

            <div style={{ height: 200 }} />
        </div>
    );
};

export default Demo;

🔥 API

We use typescript to create the Type definition. You can view directly in IDE. But you can still check the type definition here.

Nudges

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | closeIcon | React.ReactNode | - | 自定义关闭按钮 | | steps | NudgesStep[] | - | 引导步骤 | | open | boolean | true | 受控打开引导（与 current 受控分开） | | current | number | 0 | 受控当前处于哪一步 | | defaultCurrent | number | 0 | 默认处于哪一步 | | gap | { offset?: number \| [number, number]; radius?: number } | - | 控制引导显示间距 | | onChange | (current: number) => void | - | 步骤改变时的回调，current为改变前的步骤，next为改变后的步骤 | | onClose | (current: number) => void | - | 关闭引导时的回调 | | onFinish | () => void | - | 完成引导时的回调 | | mask | boolean \| { style?: React.CSSProperties; color?: string; } | true | 整体是否启用蒙层，也可以传入自定义样式修改蒙层样式 | | animated | boolean \| { placeholder: boolean } | false | 是否启用目标遮罩动画 | | arrow | boolean \| { pointAtCenter: boolean} | true | 整体是否显示箭头，包含是否指向元素中心的配置 | | scrollIntoViewOptions | boolean \| ScrollIntoViewOptions | true | 是否支持当前元素滚动到视窗内，也可传入配置指定滚动视窗的相关参数 | | onPopupAlign | function(popupDomNode, align) | - | 当弹出框对齐后回调 | | zIndex | number | 1001 | 弹层的层级 |

NudgesStep

| 属性 | 类型 | 默认值 | 说明 | | --- | --- | --- | --- | | closeIcon | React.ReactNode | - | 自定义关闭按钮 | | target | () => HTMLElement | HTMLElement | - | 获取引导卡片指向的元素 | | arrow | boolean | { pointAtCenter: boolean} | true | 是否显示箭头，包含是否指向元素中心的配置 | | placement | left | leftTop | leftBottom | right | rightTop | rightBottom | top | topLeft | topRight | bottom | bottomLeft | bottomRight | bottom | 引导卡片相对于目标元素的位置 | | onClose | () => void | - | 关闭引导时的回调函数 | | mask | boolean \| { style?: React.CSSProperties; color?: string; } | true | 是否启用蒙层，也可以传入自定义样式修改蒙层样式，默认跟随 Nudges 的 mask 属性 | | renderPanel | (props: TourStepProps, current: number) => ReactNode; | | 渲染 popoup 弹窗方法 | | className | string | - | - | | style | React.CSSProperties | - | - | | scrollIntoViewOptions | boolean \| ScrollIntoViewOptions | true | 是否支持当前元素滚动到视窗内，也可传入配置指定滚动视窗的相关参数，默认跟随 Nudges 的 scrollIntoViewOptions 属性 |