在 OneNote 页中使用笔记标记Use note tags in OneNote pages

适用于 OneDrive 上的消费者笔记本 | Office 365 上的企业级笔记本Applies to Consumer notebooks on OneDrive | Enterprise notebooks on Office 365

使用 data-tag 属性在 OneNote 页面上添加并更新复选框、星标及其他内置笔记标记,如下图所示。Use the data-tag attribute to add and update check boxes, stars, and other built-in note tags on a OneNote page, as shown in the following image.

显示在 OneNote 页面上的三个笔记标记。

笔记标记属性Note tag attributes

在 OneNote 页面的 HTML 中,笔记标记由 data-tag 属性来表示。In the HTML of a OneNote page, a note tag is represented by the data-tag attribute. 例如:For example:

  • 未选中待办事项框:<p data-tag="to-do">An unchecked to-do box: <p data-tag="to-do">

  • 已选中的待办事项框:<p data-tag="to-do:completed">A checked to-do box: <p data-tag="to-do:completed">

  • 星标:<h2 data-tag="important">A star: <h2 data-tag="important">

data-tag 值由形状组成,有时由状态组成(查看所有支持的值)。A data-tag value is composed of a shape, and sometimes a status (see all supported values).

属性Property 说明Description
shapeshape 笔记标记的标识符(示例:to-doimportant)。The identifier of the note tag (example: to-do or important).
statusstatus 复选框笔记标记的状态。The status of check box note tags. 这仅用于将复选框设置为“已完成”。This is used only to set check boxes as completed.

添加或更新笔记标记Add or update note tags

要添加或更新内置笔记标记,只需使用受支持元素上的 data-tag 属性。To add or update a built-in note tag, just use the data-tag attribute on a supported element. 例如,下面是标记为“重要”的段落:For example, here's a paragraph marked as important:

<p data-tag="important">...</p>

使用逗号分隔多个笔记标记:Separate multiple note tags with commas:

<p data-tag="important, critical">...</p>

可以在以下元素上定义 data-tagYou can define a data-tag on the following elements:

请参阅内置的笔记标记,了解可与 Microsoft Graph 一起使用的笔记标记列表。See Built-in note tags for a list of note tags that you can use with Microsoft Graph. 不支持使用 Microsoft Graph 添加或更新自定义标记。Adding or updating custom tags using Microsoft Graph is not supported.

示例Examples

下面是一个简单的待办事项列表,其第一项已完成。Here's a simple to-do list with the first item completed.

<p data-tag="to-do:completed" data-id="prep">Till garden bed</p> 
<p data-tag="to-do" data-id="spring">Plant peas and spinach</p>
<p data-tag="to-do" data-id="summer">Plant tomatoes and peppers</p>

请注意,上述 <p> 标签各包含一个 data-id 属性。Note that the <p> tags above each include a data-id attribute. 这样,可以更容易地更新复选框笔记标记。This makes it easier to update the check box note tags. 例如,以下请求将春耕待办事项标记为“已完成”。For example, the following request marks the spring planting to-do item as completed.

PATCH https://graph.microsoft.com/v1.0/me/onenote/notebooks/pages/{page-id}/content

Content-Type: application/json
Authorization: Bearer {token}

[
   {
    'target':'#spring',
    'action':'replace',
    'content':'<p data-tag="to-do:completed"  data-id="spring">Plant peas and spinach</p>'
  }
]

以下请求将创建包含所有内置笔记标记的页面。The following request creates a page that contains all built-in note tags.

POST https://graph.microsoft.com/v1.0/me/onenote/notebooks/pages

Content-Type: text/html
Authorization: Bearer {token}


<!DOCTYPE html>
<html>
  <head>
    <title data-tag="to-do:completed">All built-in note tags</title>
  </head>
  <body>
    <h1 data-tag="important">Paragraphs with built-in note tags</h1>
    <p data-tag="to-do">to-do</p>
    <p data-tag="important">important</p>
    <p data-tag="question">question</p>
    <p data-tag="definition">definition</p>
    <p data-tag="highlight">highlight</p>
    <p data-tag="contact">contact</p>
    <p data-tag="address">address</p>
    <p data-tag="phone-number">phone-number</p>
    <p data-tag="web-site-to-visit">web-site-to-visit</p>
    <p data-tag="idea">idea</p>
    <p data-tag="password">password</p>
    <p data-tag="critical">critical</p>
    <p data-tag="project-a">project-a</p>
    <p data-tag="project-b">project-b</p>
    <p data-tag="remember-for-later">remember-for-later</p>
    <p data-tag="movie-to-see">movie-to-see</p>
    <p data-tag="book-to-read">book-to-read</p>
    <p data-tag="music-to-listen-to">music-to-listen-to</p>
    <p data-tag="source-for-article">source-for-article</p>
    <p data-tag="remember-for-blog">remember-for-blog</p>
    <p data-tag="discuss-with-person-a">discuss-with-person-a</p>
    <p data-tag="discuss-with-person-b">discuss-with-person-b</p>
    <p data-tag="discuss-with-manager">discuss-with-manager</p>
    <p data-tag="send-in-email">send-in-email</p>
    <p data-tag="schedule-meeting">schedule-meeting</p>
    <p data-tag="call-back">call-back</p>
    <p data-tag="to-do-priority-1">to-do-priority-1</p>
    <p data-tag="to-do-priority-2">to-do-priority-2</p>
    <p data-tag="client-request">client-request</p>
    <h1 data-tag="important">Paragraphs with check boxes marked with "completed" status</h1>
    <p data-tag="to-do:completed">to-do:completed</p>
    <p data-tag="discuss-with-person-a:completed">discuss-with-person-a:completed</p>
    <p data-tag="discuss-with-person-b:completed">discuss-with-person-b:completed</p>
    <p data-tag="discuss-with-manager:completed">discuss-with-manager:completed</p>
    <p data-tag="schedule-meeting:completed">schedule-meeting:completed</p>
    <p data-tag="call-back:completed">call-back:completed</p>
    <p data-tag="to-do-priority-1:completed">to-do-priority-1:completed</p>
    <p data-tag="to-do-priority-2:completed">to-do-priority-2:completed</p>
    <p data-tag="client-request:completed">client-request:completed</p>
    <h1 data-tag="important">Multiple note tags</h1>
    <p data-tag="project-a,  client-request:completed">Two note tags:  project-a, client-request:completed</p>
    <p data-tag="idea, send-in-email, question">Three note tags:  idea, send-in-email, question</p>
    <h1 data-tag="important">Using note tags with other elements</h1>
    <p><b>Note tag on a list item:</b></p>
    <ul>
      <li data-tag="to-do-priority-1:completed">Make a to-do list</li>
    </ul>
    <p><b>Note tag on an image:</b></p>
    <img data-tag="source-for-article" src="https://placecorgi.com/200" />
    <p><b>Note tag with embedded style:</b></p>
    <p data-tag="important">Next time, <b>don't</b> forget to invite <span style="background-color:yellow">Dan</span>.</p>
  </body>
</html>

有关创建页面的详细信息,请参阅创建 OneNote 页面For more information about creating pages, see Create OneNote pages. 有关更新页面的详细信息,请参阅更新 OneNote 页面For more about updating pages, see Update OneNote pages.

列表上的笔记标记Note tags on lists

下面是一些使用列表中笔记标记的相关指南:Here are some guidelines for working with note tags on lists:

  • 使用待办事项列表的 p 元素。Use p elements for to-do lists. 这些元素不会显示项目符号或编号,更加易于更新。They don't display a bullet or number, and they're easier to update.

  • 若要创建或更新为所有列表项显示相同笔记标记的列表,请在 ulol 上定义 data-tagTo create or update lists that display the same note tag for all list items, define data-tag on the ul or ol. 若要更新完整列表,需要对 ulol 重新定义 data-tagTo update the entire list, you'll need to redefine data-tag on the ul or ol.

  • 若要创建或更新为某些或全部列表项显示唯一笔记标记的列表,请在 li 元素上定义 data-tag,并且不要在 ulol 中嵌套 li 元素。To create or update lists that display a unique note tag for some or all list items, define data-tag on li elements, and don't nest the li elements in a ul or ol. 若要更新整个列表,将需要删除在输出 HTML 中返回的 ul,并仅提供非嵌套的 li 元素。To update the entire list, you'll need to remove the ul that's returned in the output HTML and provide only the unnested li elements.

  • 要更新特定的 li 元素,单独定位 li 元素并对 li 元素定义 data-tagTo update specific li elements, target the li elements individually and define the data-tag on the li element. 任何单独处理的 li 元素都可以进行更新,以显示唯一笔记标记,而不考虑列表的最初定义方式。Any individually addressed li element can be updated to display a unique note tag, no matter how the list was originally defined.

    准则基于 Microsoft Graph 所应用的以下规则:The guidelines are based on the following rules that are applied by Microsoft Graph:

    • uloldata-tag 设置会覆盖子 li 元素上的所有设置。The data-tag setting for a ul or ol overrides all settings on child li elements. 这同样适用于 ulol 未指定 data-tag 但其子 li 元素执行了该操作的情况。This applies even when the ul or ol doesn't specify a data-tag but its child li elements do.

      例如,如果创建定义 data-tag="project-a"ulol,其所有列表项将都显示项目 A 笔记标记。For example, if you create a ul or ol that defines data-tag="project-a", all its list items will display the Project A note tag. 或者,如果 ulol 未定义 data-tag,则没有任何项会显示笔记标记。Or if the ul or ol doesn't define a data-tag, none of its items will display a note tag. 无论子 li 元素有什么显式设置,都会发生这种覆盖。This override happens regardless of any explicit settings on child li elements.

  • 在下列情况下,唯一的 data-tag 设置被视为列表项:Unique data-tag settings are honored for list items under the following conditions:

    • 在创建或更新请求中,li 元素不嵌套在 ulol 中。The li elements are not nested in a ul or ol in a create or update request.

    • li 元素在更新请求中单独处理。An li element is individually addressed in an update request.

  • 在输入 HTML 中发送的未嵌套 li 元素将在输出 HTML 的 ul 中返回。Unnested li elements sent in input HTML are returned in a ul in the output HTML.

  • 在输出 HTML 中,所有 data-tag 列表设置都在列表项的 span 元素上定义。In output HTML, all data-tag list settings are defined on span elements on the list items.

以下代码显示如何应用其中的某些规则。The following code shows how some of these rules are applied. 输入 HTML 将使用笔记标记创建两个列表。The input HTML creates two lists with note tags. 输出 HTML 是检索页面内容时针对列表所返回的内容。The output HTML is what's returned for the lists when you retrieve page content.

输入 HTMLInput HTML

<!--To display the same note tag on all list items, define note tags on the ul or ol.--> 
<ul data-tag="project-a" data-id="agenda">
  <li>An item with a Project A note tag</li>
  <li>An item with a Project A note tag</li>
</ul>

<!--To display unique note tags on list items, don't nest li elements in a ul or ol.--> 
<li data-tag="idea" data-id="my-idea">An item with an Idea note tag</li>
<li data-tag="question" data-id="my-question">An item with a Question note tag</li>

输出 HTMLOutput HTML

<ul>
  <li><span data-tag="project-a">An item with a Project A note tag</span></li>
  <li><span data-tag="project-a">An item with a Project A note tag</span></li>
</ul>
<br />
<ul>
  <li style="..."><span data-tag="idea">An item with an Idea note tag</span></li>
  <li style="..."><span data-tag="question">An item with a Question note tag</span></li>
</ul>

检索笔记标记Retrieve note tags

当访问页面内容时,内置笔记标记将包含在输出 HTML 中:Built-in note tags are included in the output HTML when you get page content:

GET ../api/v1.0/pages/{page-id}/content

输出 HTML 中的 data-tag 属性始终包含形状值,并且仅在它表示设置为“已完成”的复选框笔记标记时才包含状态。A data-tag attribute in the output HTML always includes a shape value, and it only includes a status if it represents a check box note tag that's set to completed. 以下示例显示用于创建一些笔记标记的输入 HTML 和返回的输出 HTML。The following examples show the input HTML used to create some note tags and the output HTML that's returned.

输入 HTMLInput HTML

<h1>Status meeting</h1>
<p data-tag="important">Next week's meeting has been moved to <b>Wednesday</b>.</p>
<p data-tag="question">What are the exact dates for the conference?</p>
<p>Upcoming training opportunities. See Katie for more info.</p>
<p data-tag="project-a">Around the room updates.</p>
<ul data-tag="critical">
  <li>Design handouts</li>
  <li>Plan keynote</li>
</ul>

输出 HTMLOutput HTML

<h1 style="...">Status meeting</h1>
<p data-tag="important">Next week's meeting has been moved to <span style="font-weight:bold">Wednesday</span>.</p>
<p data-tag="question">What are the exact dates for the conference?</p>
<p>Upcoming training opportunities. See Katie for more info.</p>
<p data-tag="project-a">Around the room updates.</p>
<ul>
  <li><span data-tag="critical">Design handouts</span></li>
  <li><span data-tag="critical">Plan keynote</span></li>
</ul>

请注意,在列表级别上定义的 data-tag 属性会被推送到它的列表项。Note that the data-tag attribute defined at the list level is pushed to its list items. 有关将笔记标记与列表结合使用的详细信息,请参阅列表上的笔记标记For more information about using note tags with lists, see Note tags on lists.

注意: 在输出 HTML 中,定义和后续工作笔记标记均作为 data-tag="remember-for-later" 返回。Note: In the output HTML, the definition and remember-for-later note tags are both returned as data-tag="remember-for-later". title 元素不返回任何笔记标记信息。The title element doesn't return any note tag information.

OneNote 的内置笔记标记Built-in note tags for OneNote

OneNote 包括以下内置笔记标记:OneNote includes the following built-in note tags:

所有内置笔记标记。

可以为 data-tag 属性分配下表中显示的值。The values you can assign to the data-tag attribute are shown in the following table. 不支持自定义标记。Custom tags are not supported.

标记Tags
shape[:status] to-do

to-do:completed
important
question definition highlight
contact address phone-number
web-site-to-visit idea password
critical project-a project-b
remember-for-later movie-to-see book-to-read
music-to-listen-to source-for-article remember-for-blog
discuss-with-person-a

discuss-with-person-a:completed
discuss-with-person-b

discuss-with-person-b:completed
discuss-with-manager

discuss-with-manager:completed
send-in-email schedule-meeting

schedule-meeting:completed
call-back

call-back:completed
to-do-priority-1

to-do-priority-1:completed
to-do-priority-2

to-do-priority-2:completed
client-request

client-request:completed

响应信息Response information

Microsoft Graph 在响应中返回以下信息。Microsoft Graph returns the following information in the response.

响应数据Response data 说明Description
成功代码Success code 成功的 POST 请求的 HTTP 状态代码为 201,成功的 PATCH 请求的 HTTP 状态代码为 204。A 201 HTTP status code for a successful POST request, and a 204 HTTP status code for a successful PATCH request.
错误Errors 请阅读 Microsoft Graph 中 OneNote API 的错误代码,以了解 Microsoft Graph 可以返回的 OneNote 错误。Read Error codes for OneNote APIs in Microsoft Graph to learn about OneNote errors that Microsoft Graph can return.

权限Permissions

若要创建或更新 OneNote 页面,需要请求相应的权限。To create or update OneNote pages, you'll need to request appropriate permissions. 选择应用运行所需的最低级别的权限。Choose the lowest level of permissions that your app needs to do its work.

POST 页面的权限Permissions for POST pages

  • Notes.CreateNotes.Create
  • Notes.ReadWriteNotes.ReadWrite
  • Notes.ReadWrite.AllNotes.ReadWrite.All

PATCH 页面的权限Permissions for PATCH pages

  • Notes.ReadWriteNotes.ReadWrite
  • Notes.ReadWrite.AllNotes.ReadWrite.All

有关权限范围及其工作方式的详细信息,请参阅 OneNote 权限范围For more information about permission scopes and how they work, see OneNote permission scopes.

另请参阅See also