Merge pull request 'FAQ 相关' (#46) from feat/faq-to-docs into main

Reviewed-on: #46

README.MD

@@ -7,6 +7,7 @@
 - Unlock Music 的 CLI 版本可以在 [unlock-music/cli] 找到，大批量转换建议使用 CLI 版本。
 - 我们新建了 Telegram 群组 [`@unlock_music_chat`] ，欢迎加入！
 - CI 自动构建已经部署，可以在 [Packages][um-react-packages] 下载。
+- [常见问题参考](./docs/faq_zh-hans.md)
 
 [授权协议]: https://git.unlock-music.dev/um/um-react/src/branch/main/LICENSE
 [unlock-music/cli]: https://git.unlock-music.dev/um/cli

docs/faq_zh-hans.md

@@ -1,10 +1,15 @@
 # 常见问题解答
 
 ## QQ 音乐
+
 ### 解锁失败
+
 #### 1、请检查您的文件。
+
 尝试用下载音乐的设备播放一次看看，如果 QQ 音乐都没法播放，那解锁肯定会受到影响哦。
+
 #### 2、检查您的平台。
+
 日前，<mark>仅 Windows 客户端</mark>下载的歌曲无需密钥，其余平台的官方正式版本均需要提取密钥。
 
 > iOS 用户提取歌曲困难，建议换用电脑操作；Android 用户提取密钥需要 root，也建议用电脑操作。
@@ -12,47 +17,56 @@
 > 重复下载同一首的歌曲**不重复扣下载配额**，但是*同一首歌的两个版本会重复扣下载配额*，请仔细分辨。
 
 提取密钥教程请访问[新版解锁网站](https://um-react.netlify.app/)，前往网站内的设置 →“添加一条密钥”旁的<mark>**下拉按钮**</mark>→ 从文件导入密钥…→ 选择您对应的平台查看具体教程。
+
 > 如果仍无法理解，可参考文末的图片操作
 
 ## 酷我音乐
+
 ### 解锁失败
+
 酷我音乐的新版加密需要导入密钥。
+
 #### 1、请检查您的文件。
+
 尝试用下载音乐的设备播放一次看看，如果酷我音乐都没法播放，那解锁肯定会受到影响哦。
+
 #### 2、检查您的平台。
+
 日前，<mark>仅手机客户端</mark>下载的歌曲**至臻全景声**及**至臻母带**为新版加密，手机平台的其他音质暂时不需要提取密钥，PC 平台暂未推出使用新版加密的音质。
 
->iOS用户提取歌曲需要；Android用户提取密钥需要root，或者注入文件提供器。
+> Android 用户提取密钥需要 root，或者注入文件提供器。
 
 提取密钥教程请访问[新版解锁网站](https://um-react.netlify.app/)，前往网站内的设置 →<mark>切换密钥为 KWMv2 密钥</mark>→“添加一条密钥”旁的<mark>**下拉按钮**</mark>→ 从文件导入密钥…→ 选择您对应的平台查看具体教程。
 
 > 图片教程请参考 QQ 音乐（在文末），酷我音乐仅仅是需要切换一下密钥类型。
+
 ## 网易云音乐
+
 ### 解锁失败
+
 您大概率正在使用 Windows 平台的网易云音乐 3.0 测试版。该版本对歌曲的信息新增了某些字段，导致旧版解锁识别错误。您可以找 1.10.5 版本的旧解锁网站，或者直接换[新版解锁网站](https://um-react.netlify.app/)。
+
 > [旧解锁网站 Demo](https://demo.unlock-music.dev/)拥有者暂时联系不上，所以暂时无法更新。
 
 ## 其他问题
+
 ### 新版解锁网站解锁的歌曲没有封面
+
 目前新版没有做歌曲信息匹配与编辑，所以歌曲如果自己没有写入歌曲信息，解出来就是没有的。
+
 ### 新版解锁网站没有批量下载
+
 目前没有做。抱歉。
 
 ## 仍有问题？
+
 欢迎进入[Telegram 交流群](https://t.me/unlock_music_chat)，一起探讨。
 
 > QQ 音乐导入密钥的图片教程
-<div style="overflow-x: auto; white-space: nowrap;">
-    <div style="display: inline-block; text-align: center;">
-        <img src="https://onedrive.live.com/embed?resid=191A17ABC8C0EF56%2138446&authkey=%21AFL7ZJkt8xSdNHQ&width=1080&height=2376" style="width: 1080;">
-        <p>点击设置</p>
-    </div>
-    <div style="display: inline-block; text-align: center;">
-        <img src="https://onedrive.live.com/embed?resid=191A17ABC8C0EF56%2138448&authkey=%21AKpbY8ogYuq52K4&width=1080&height=2376" style="width: 1080;">
-        <p>点击导入</p>
-    </div>
-    <div style="display: inline-block; text-align: center;">
-        <img src="https://onedrive.live.com/embed?resid=191A17ABC8C0EF56%2138449&authkey=%21ALsY9cDFWz0L-P0&width=1080&height=2376" style="width: 1080;">
-        <p>查看密钥教程</p>
-    </div>
-</div>
+
+1. 选择【设定】
+   <br/>![选择【设定】](./assets/faq_1_home.webp)
+2. 点击下拉菜单，选择【从文件导入密钥…】
+   <br/>![点击下拉菜单，选择【从文件导入密钥…】](./assets/faq_2_import.webp)
+3. 选择对应的客户端并查阅说明
+   <br/>![选择对应的客户端并查阅说明](./assets/faq_3_instructions.webp)

src/components/AppRoot.tsx

@@ -1,5 +1,5 @@
 import { useEffect } from 'react';
-import { MdSettings, MdHome } from 'react-icons/md';
+import { MdSettings, MdHome, MdQuestionAnswer } from 'react-icons/md';
 import { ChakraProvider, Tabs, TabList, TabPanels, Tab, TabPanel, Icon, chakra } from '@chakra-ui/react';
 
 import { MainTab } from '~/tabs/MainTab';
@@ -10,6 +10,7 @@ import { theme } from '~/theme';
 import { persistSettings } from '~/features/settings/persistSettings';
 import { setupStore } from '~/store';
 import { Footer } from '~/components/Footer';
+import { FaqTab } from '~/tabs/FaqTab';
 
 // Private to this file only.
 const store = setupStore();
@@ -30,6 +31,10 @@ export function AppRoot() {
               <Icon as={MdSettings} mr="1" />
               <chakra.span>设置</chakra.span>
             </Tab>
+            <Tab>
+              <Icon as={MdQuestionAnswer} mr="1" />
+              <chakra.span>问答</chakra.span>
+            </Tab>
           </TabList>
 
           <TabPanels overflow="auto" minW={0} flexDir="column" flex={1} display="flex">
@@ -39,6 +44,9 @@ export function AppRoot() {
             <TabPanel flex={1} display="flex">
               <SettingsTab />
             </TabPanel>
+            <TabPanel>
+              <FaqTab />
+            </TabPanel>
           </TabPanels>
         </Tabs>
 

src/components/HelpText/Header3.tsx

@@ -0,0 +1,26 @@
+import { Heading } from '@chakra-ui/react';
+import React from 'react';
+
+export interface Header3Props {
+  children: React.ReactNode;
+  id?: string;
+  className?: string;
+}
+
+export function Header3({ children, className, id }: Header3Props) {
+  return (
+    <Heading
+      as="h3"
+      id={id}
+      className={className}
+      pt={3}
+      pb={1}
+      borderBottom={'1px solid'}
+      borderColor="gray.300"
+      color="gray.800"
+      size="lg"
+    >
+      {children}
+    </Heading>
+  );
+}

src/components/HelpText/Header4.tsx

@@ -0,0 +1,16 @@
+import { Heading } from '@chakra-ui/react';
+import React from 'react';
+
+export interface Header4Props {
+  children: React.ReactNode;
+  id?: string;
+  className?: string;
+}
+
+export function Header4({ children, className, id }: Header4Props) {
+  return (
+    <Heading as="h4" id={id} className={className} pt={3} pb={1} color="gray.700" size="md">
+      {children}
+    </Heading>
+  );
+}

src/components/HelpText/HiWord.tsx

@@ -0,0 +1,9 @@
+import { Mark } from '@chakra-ui/react';
+
+export function HiWord({ children }: { children: React.ReactNode }) {
+  return (
+    <Mark bg="orange.100" borderRadius={5} px={2} mx={1}>
+      {children}
+    </Mark>
+  );
+}

src/components/HelpText/VQuote.tsx

@@ -0,0 +1,13 @@
+import { chakra, css } from '@chakra-ui/react';
+
+const cssUnselectable = css({ pointerEvents: 'none', userSelect: 'none' });
+
+export function VQuote({ children }: { children: React.ReactNode }) {
+  return (
+    <>
+      <chakra.span css={cssUnselectable}>「</chakra.span>
+      {children}
+      <chakra.span css={cssUnselectable}>」</chakra.span>
+    </>
+  );
+}

src/components/ProjectIssue.tsx

@@ -0,0 +1,17 @@
+export interface ProjectIssueProps {
+  id: number | string;
+  title?: string;
+}
+
+export function ProjectIssue({ id, title }: ProjectIssueProps) {
+  return (
+    <a
+      rel="noopener noreferrer nofollow"
+      target="_blank"
+      href={`https://git.unlock-music.dev/um/um-react/issues/${id}`}
+    >
+      {`#${id}`}
+      {title && ` - ${title}`}
+    </a>
+  );
+}

src/faq/KuwoFAQ.tsx

@@ -0,0 +1,50 @@
+import { Alert, AlertIcon, Container, List, ListItem, Text, VStack, chakra } from '@chakra-ui/react';
+import { Header4 } from '~/components/HelpText/Header4';
+import { VQuote } from '~/components/HelpText/VQuote';
+import { SegmentTryOfficialPlayer } from './SegmentTryOfficialPlayer';
+import { HiWord } from '~/components/HelpText/HiWord';
+import { KWMv2AllInstructions } from '~/features/settings/panels/KWMv2/KWMv2AllInstructions';
+import { SegmentKeyImportInstructions } from './SegmentKeyImportInstructions';
+
+export function KuwoFAQ() {
+  return (
+    <>
+      <Header4>解锁失败</Header4>
+      <List spacing={2}>
+        <ListItem>
+          <SegmentTryOfficialPlayer />
+        </ListItem>
+        <ListItem>
+          <Text>
+            <chakra.strong>2、检查您的平台</chakra.strong>
+          </Text>
+          <Text>
+            日前，仅<HiWord>手机客户端</HiWord>下载的
+            <VQuote>
+              <strong>至臻全景声</strong>
+            </VQuote>
+            及
+            <VQuote>
+              <strong>至臻母带</strong>
+            </VQuote>
+            {'音质的音乐文件采用新版加密。'}
+          </Text>
+          <Text>其他音质目前不需要提取密钥。</Text>
+          <Text>PC平台暂未推出使用新版加密的音质。</Text>
+
+          <Container p={2}>
+            <Alert status="warning" borderRadius={5}>
+              <AlertIcon />
+              <VStack>
+                <Text>Android 用户提取密钥需要 root 权限，或注入文件提供器。</Text>
+                <Text>请注意：项目组不提倡使用第三方修改版应用亦不会提供，使用前请自行评估风险。</Text>
+              </VStack>
+            </Alert>
+          </Container>
+
+          <SegmentKeyImportInstructions tab="KWMv2 密钥" clientInstructions={<KWMv2AllInstructions />} />
+        </ListItem>
+      </List>
+    </>
+  );
+}

src/faq/OtherFAQ.tsx

@@ -0,0 +1,28 @@
+import { ExternalLinkIcon } from '@chakra-ui/icons';
+import { Link, Text } from '@chakra-ui/react';
+import { Header4 } from '~/components/HelpText/Header4';
+import { ProjectIssue } from '~/components/ProjectIssue';
+
+export function OtherFAQ() {
+  return (
+    <>
+      <Header4>解密后没有封面等信息</Header4>
+      <Text>该项目进行解密处理。如果加密前的资源没有内嵌元信息或封面，解密的文件也没有。</Text>
+      <Text>请使用第三方工具进行编辑或管理元信息。</Text>
+      <Header4>如何批量下载</Header4>
+      <Text>
+        暂时没有实现，不过你可以在 <ProjectIssue id={34} title="[UI] 全部下载功能" /> 以及{' '}
+        <ProjectIssue id={43} title="批量下载" /> 追踪该问题。
+      </Text>
+      <Header4>有更多问题？</Header4>
+      <Text>
+        {'欢迎进入 '}
+        <Link href={'https://t.me/unlock_music_chat'} isExternal>
+          Telegram “音乐解锁-交流” 交流群
+          <ExternalLinkIcon />
+        </Link>
+        {' 一起探讨。'}
+      </Text>
+    </>
+  );
+}

src/faq/QQMusicFAQ.tsx

@@ -0,0 +1,40 @@
+import { Alert, AlertIcon, Container, List, ListItem, Text, chakra } from '@chakra-ui/react';
+import { Header4 } from '~/components/HelpText/Header4';
+import { SegmentTryOfficialPlayer } from './SegmentTryOfficialPlayer';
+import { QMCv2AllInstructions } from '~/features/settings/panels/QMCv2/QMCv2AllInstructions';
+import { SegmentKeyImportInstructions } from './SegmentKeyImportInstructions';
+
+export function QQMusicFAQ() {
+  return (
+    <>
+      <Header4>解锁失败</Header4>
+      <List spacing={2}>
+        <ListItem>
+          <SegmentTryOfficialPlayer />
+        </ListItem>
+        <ListItem>
+          <Text>
+            <chakra.strong>2、检查您的平台</chakra.strong>
+          </Text>
+          <Text>日前，仅Windows客户端下载的歌曲无需密钥，其余平台的官方正式版本均需要提取密钥。</Text>
+
+          <Container p={2}>
+            <Alert status="warning" borderRadius={5}>
+              <AlertIcon />
+              iOS用户提取歌曲困难，建议换用电脑操作；Android用户提取密钥需要root，也建议用电脑操作。
+            </Alert>
+          </Container>
+
+          <Container p={2} pt={0}>
+            <Alert status="info" borderRadius={5}>
+              <AlertIcon />
+              重复下载同一首的歌曲不重复扣下载配额，但是同一首歌的两个版本会重复扣下载配额，请仔细分辨。
+            </Alert>
+          </Container>
+
+          <SegmentKeyImportInstructions tab="QMCv2 密钥" clientInstructions={<QMCv2AllInstructions />} />
+        </ListItem>
+      </List>
+    </>
+  );
+}

src/faq/SegmentAddKeyDropdown.tsx

@@ -0,0 +1,25 @@
+import { Flex, IconButton } from '@chakra-ui/react';
+import { MdExpandMore } from 'react-icons/md';
+import { HiWord } from '~/components/HelpText/HiWord';
+import { VQuote } from '~/components/HelpText/VQuote';
+
+export function SegmentAddKeyDropdown() {
+  return (
+    <Flex as="span" alignItems="center">
+      按下<VQuote>添加一条密钥</VQuote>按钮
+      <HiWord>右侧</HiWord>的
+      <IconButton
+        colorScheme="purple"
+        variant="outline"
+        size="sm"
+        icon={<MdExpandMore />}
+        ml="2"
+        borderTopLeftRadius={0}
+        borderBottomLeftRadius={0}
+        isDisabled
+        css={{ ':disabled': { opacity: 1 } }}
+        aria-label="示例按钮"
+      />
+    </Flex>
+  );
+}

src/faq/SegmentKeyImportInstructions.tsx

@@ -0,0 +1,44 @@
+import { Flex, Icon, ListItem, OrderedList, Tabs, Text } from '@chakra-ui/react';
+import { SegmentTopNavSettings } from './SegmentTopNavSettings';
+import { VQuote } from '~/components/HelpText/VQuote';
+import { SegmentAddKeyDropdown } from './SegmentAddKeyDropdown';
+import React from 'react';
+import { MdFileUpload } from 'react-icons/md';
+
+export interface SegmentKeyImportInstructionsProps {
+  clientInstructions: React.ReactNode;
+  tab: string;
+}
+
+export function SegmentKeyImportInstructions({ clientInstructions, tab }: SegmentKeyImportInstructionsProps) {
+  return (
+    <>
+      <Text>导入密钥可以参考下面的步骤：</Text>
+      <OrderedList>
+        <ListItem>
+          <SegmentTopNavSettings />
+        </ListItem>
+        <ListItem>
+          设定区域选择<VQuote>{tab}</VQuote>
+        </ListItem>
+        <ListItem>
+          <SegmentAddKeyDropdown />
+        </ListItem>
+        <ListItem>
+          <Flex flexDir="row" alignItems="center">
+            {'选择 '}
+            <VQuote>
+              <Icon as={MdFileUpload} boxSize={5} mr={2} /> 从文件导入密钥…
+            </VQuote>
+          </Flex>
+        </ListItem>
+        <ListItem>
+          <Text>选择你的客户端平台来查看密钥提取说明：</Text>
+          <Tabs display="flex" flexDir="column" border="1px solid" borderColor="gray.300" borderRadius={5}>
+            {clientInstructions}
+          </Tabs>
+        </ListItem>
+      </OrderedList>
+    </>
+  );
+}

src/faq/SegmentTopNavSettings.tsx

@@ -0,0 +1,9 @@
+import { VQuote } from '~/components/HelpText/VQuote';
+
+export function SegmentTopNavSettings() {
+  return (
+    <>
+      点击顶部的<VQuote>设置</VQuote>
+    </>
+  );
+}

src/faq/SegmentTryOfficialPlayer.tsx

@@ -0,0 +1,12 @@
+import { Text, chakra } from '@chakra-ui/react';
+
+export function SegmentTryOfficialPlayer() {
+  return (
+    <>
+      <Text>
+        <chakra.strong>1、请检查您的文件</chakra.strong>
+      </Text>
+      <Text>尝试用下载音乐的设备播放一次看看，如果官方客户端都无法播放，那解锁肯定会失败哦。</Text>
+    </>
+  );
+}

src/features/settings/panels/KWMv2/KWMv2AllInstructions.tsx

@@ -0,0 +1,25 @@
+import { Tab, TabList, TabPanel, TabPanels } from '@chakra-ui/react';
+import { AndroidADBPullInstruction } from '~/components/AndroidADBPullInstruction/AndroidADBPullInstruction';
+import { InstructionsPC } from './InstructionsPC';
+
+export function KWMv2AllInstructions() {
+  return (
+    <>
+      <TabList>
+        <Tab>安卓</Tab>
+        <Tab>Windows</Tab>
+      </TabList>
+      <TabPanels flex={1} overflow="auto">
+        <TabPanel>
+          <AndroidADBPullInstruction
+            dir="/data/data/cn.kuwo.player/files/mmkv"
+            file="cn.kuwo.player.mmkv.defaultconfig"
+          />
+        </TabPanel>
+        <TabPanel>
+          <InstructionsPC />
+        </TabPanel>
+      </TabPanels>
+    </>
+  );
+}

src/features/settings/panels/PanelKWMv2Key.tsx

@@ -14,10 +14,6 @@ import {
   MenuDivider,
   MenuItem,
   MenuList,
-  Tab,
-  TabList,
-  TabPanel,
-  TabPanels,
   Text,
   useToast,
 } from '@chakra-ui/react';
@@ -32,8 +28,7 @@ import { kwm2AddKey, kwm2ClearKeys, kwm2ImportKeys } from '../settingsSlice';
 import { selectStagingKWMv2Keys } from '../settingsSelector';
 import { KWMv2EKeyItem } from './KWMv2/KWMv2EKeyItem';
 import type { StagingKWMv2Key } from '../keyFormats';
-import { InstructionsPC } from './KWMv2/InstructionsPC';
-import { AndroidADBPullInstruction } from '~/components/AndroidADBPullInstruction/AndroidADBPullInstruction';
+import { KWMv2AllInstructions } from './KWMv2/KWMv2AllInstructions';
 
 export function PanelKWMv2Key() {
   const toast = useToast();
@@ -120,21 +115,7 @@ export function PanelKWMv2Key() {
         onClose={() => setShowImportModal(false)}
         onImport={handleSecretImport}
       >
-        <TabList>
-          <Tab>安卓</Tab>
-          <Tab>Windows</Tab>
-        </TabList>
-        <TabPanels flex={1} overflow="auto">
-          <TabPanel>
-            <AndroidADBPullInstruction
-              dir="/data/data/cn.kuwo.player/files/mmkv"
-              file="cn.kuwo.player.mmkv.defaultconfig"
-            />
-          </TabPanel>
-          <TabPanel>
-            <InstructionsPC />
-          </TabPanel>
-        </TabPanels>
+        <KWMv2AllInstructions />
       </ImportSecretModal>
     </Flex>
   );

src/features/settings/panels/PanelQMCv2Key.tsx

@@ -14,10 +14,6 @@ import {
   MenuDivider,
   MenuItem,
   MenuList,
-  Tab,
-  TabList,
-  TabPanel,
-  TabPanels,
   Text,
   Tooltip,
   useToast,
@@ -34,10 +30,7 @@ import { StagingQMCv2Key } from '../keyFormats';
 import { DatabaseKeyExtractor } from '~/util/DatabaseKeyExtractor';
 import { MMKVParser } from '~/util/MMKVParser';
 import { getFileName } from '~/util/pathHelper';
-import { InstructionsIOS } from './QMCv2/InstructionsIOS';
-import { InstructionsMac } from './QMCv2/InstructionsMac';
-import { InstructionsPC } from './QMCv2/InstructionsPC';
-import { AndroidADBPullInstruction } from '~/components/AndroidADBPullInstruction/AndroidADBPullInstruction';
+import { QMCv2AllInstructions } from './QMCv2/QMCv2AllInstructions';
 
 export function PanelQMCv2Key() {
   const toast = useToast();
@@ -171,26 +164,7 @@ export function PanelQMCv2Key() {
         onClose={() => setShowImportModal(false)}
         onImport={handleSecretImport}
       >
-        <TabList>
-          <Tab>安卓</Tab>
-          <Tab>iOS</Tab>
-          <Tab>Mac</Tab>
-          <Tab>Windows</Tab>
-        </TabList>
-        <TabPanels flex={1} overflow="auto">
-          <TabPanel>
-            <AndroidADBPullInstruction dir="/data/data/com.tencent.qqmusic/databases" file="player_process_db" />
-          </TabPanel>
-          <TabPanel>
-            <InstructionsIOS />
-          </TabPanel>
-          <TabPanel>
-            <InstructionsMac />
-          </TabPanel>
-          <TabPanel>
-            <InstructionsPC />
-          </TabPanel>
-        </TabPanels>
+        <QMCv2AllInstructions />
       </ImportSecretModal>
     </Flex>
   );

src/features/settings/panels/QMCv2/QMCv2AllInstructions.tsx

@@ -0,0 +1,32 @@
+import { Tab, TabList, TabPanel, TabPanels } from '@chakra-ui/react';
+import { AndroidADBPullInstruction } from '~/components/AndroidADBPullInstruction/AndroidADBPullInstruction';
+import { InstructionsIOS } from './InstructionsIOS';
+import { InstructionsMac } from './InstructionsMac';
+import { InstructionsPC } from './InstructionsPC';
+
+export function QMCv2AllInstructions() {
+  return (
+    <>
+      <TabList>
+        <Tab>安卓</Tab>
+        <Tab>iOS</Tab>
+        <Tab>Mac</Tab>
+        <Tab>Windows</Tab>
+      </TabList>
+      <TabPanels flex={1} overflow="auto">
+        <TabPanel>
+          <AndroidADBPullInstruction dir="/data/data/com.tencent.qqmusic/databases" file="player_process_db" />
+        </TabPanel>
+        <TabPanel>
+          <InstructionsIOS />
+        </TabPanel>
+        <TabPanel>
+          <InstructionsMac />
+        </TabPanel>
+        <TabPanel>
+          <InstructionsPC />
+        </TabPanel>
+      </TabPanels>
+    </>
+  );
+}

src/tabs/FaqTab.tsx

@@ -0,0 +1,21 @@
+import { Center, Container, Heading } from '@chakra-ui/react';
+import { Header3 } from '~/components/HelpText/Header3';
+import { KuwoFAQ } from '~/faq/KuwoFAQ';
+import { OtherFAQ } from '~/faq/OtherFAQ';
+import { QQMusicFAQ } from '~/faq/QQMusicFAQ';
+
+export function FaqTab() {
+  return (
+    <Container pb={10} maxW="container.md">
+      <Center>
+        <Heading as="h2">常见问题解答</Heading>
+      </Center>
+      <Header3>QQ 音乐</Header3>
+      <QQMusicFAQ />
+      <Header3>酷我音乐</Header3>
+      <KuwoFAQ />
+      <Header3>其它问题</Header3>
+      <OtherFAQ />
+    </Container>
+  );
+}